OpenAPI 3.1 · Sandbox · SDK PILOT

BULLS API — машинно-читаемая логистика

Полная спецификация в OpenAPI 3.1. Sandbox с тестовыми данными. SDK для Python и Node.js. MCP-сервер для AI-агентов клиентов и партнёров.

Каталог endpoints SDK MCP-сервер
live

99.97%

Uptime API за 30 дней

142 ms

Median TTFB API

37

Публичных endpoints

12

MCP-tools для агентов

Каталог endpoints

Ключевые ресурсы

Все запросы — REST, JSON, OAuth 2.1. Версионирование через заголовок X-Bulls-Api-Version. Полная спецификация — в OpenAPI 3.1.

Перевозки

GET/v1/shipmentsсписок
GET/v1/shipments/{id}детали
POST/v1/shipmentsсоздать
PUT/v1/shipments/{id}/escalateэскалация

Парк и контейнеры BULLS BOX

GET/v1/containersсписок парка
GET/v1/containers/{id}/telemetrylive IoT
GET/v1/wagonsвагоны

ЭТРАН и РЖД

POST/v1/etran/gu12оформить ГУ-12
GET/v1/etran/penaltiesштрафы РЖД

Финансы и документы

GET/v1/finance/balanceбаланс
GET/v1/finance/transactionsтранзакции
GET/v1/documentsсписок документов
POST/v1/documents/{id}/signЭП

Аналитика и ESG

GET/v1/analytics/shipmentsобзор
GET/v1/analytics/ecoCO₂ / тонно-км
GET/v1/analytics/costразбивка стоимости

Webhooks

POST/v1/webhooks/shipmentsподписка на события
GET/v1/webhooksмои webhooks
Quickstart

Получить статус перевозки за 30 секунд

Зарегистрируйте OAuth-приложение в Control Tower → /settings/api-keys. Используйте полученный токен в заголовке Authorization: Bearer ....

  1. Получите токен — sandbox или production.
  2. Сделайте запрос GET /v1/shipments/{id}.
  3. Обработайте ответ. Подпишитесь на webhook для live-обновлений.
# Получить статус перевозки
curl "https://api.bulls.win/v1/shipments/SHP-2026-04-1247" \
  -H "Authorization: Bearer $BULLS_TOKEN" \
  -H "X-Bulls-Api-Version: 2026-04-01"

# Ответ (фрагмент)
{
  "id": "SHP-2026-04-1247",
  "status": "in_transit",
  "route": { "from": "Джабык", "to": "Раменское" },
  "eta": "2026-05-02T14:30:00Z",
  "containers": ["BULLS-40HT-0918"],
  "telemetry_url": "/v1/containers/BULLS-40HT-0918/telemetry",
  "co2_kg": 1284.6
}
SDK

Python и Node.js — типизированные клиенты

Python

pip install bulls-sdk

from bulls import Client
client = Client(token="$BULLS_TOKEN")
shipment = client.shipments.get("SHP-2026-04-1247")
print(shipment.status, shipment.eta)

Node.js / TypeScript

npm install @bulls/sdk

import { BullsClient } from "@bulls/sdk";
const client = new BullsClient({ token: process.env.BULLS_TOKEN });
const shp = await client.shipments.get("SHP-2026-04-1247");
console.log(shp.status, shp.eta);
MCP-сервер

Для AI-агентов клиентов и партнёров

BULLS публикует MCP-сервер: ваш ChatGPT-агент, Claude или корпоративный AI может машинно-читаемо узнать тарифы, проверить наличие парка, забронировать перевозку.

  • ↳ Resources: services, containers, routes, tariffs
  • ↳ Tools: search_route, get_quote, book_shipment
  • ↳ Безопасность: signed token, rate-limit, scope per partner
  • ↳ llms.txt с описанием публичных сущностей
Документация MCP → 
{
  "mcpServers": {
    "bulls": {
      "url": "https://mcp.bulls.win/v1",
      "auth": {
        "type": "oauth2",
        "scopes": ["routes:read", "quotes:read"]
      }
    }
  }
}

# Пример вызова tool
{
  "tool": "get_quote",
  "args": {
    "from": "Джабык",
    "to": "Раменское",
    "container": "40ft_hard_top",
    "qty": 30
  }
}

Лимиты и условия использования

Sandbox

1000 RPS · бесплатно

Тестовые данные, обновляются ежедневно. SLA нет.

Production

100 RPS / org · по контракту

SLA 99.9%, MTTR ≤ 4 ч. Расширение по запросу.

MCP-сервер

60 запросов / мин / партнёр

Расширенные лимиты для известных партнёров.