API Reference

REST API v1 для программной интеграции с CourierFlow

Base URL

https://courierflow.ru/api/v1

Аутентификация

Все запросы к API требуют заголовок Authorization с вашим API-ключом. Ключ генерируется в Настройках → API-ключи.

Важно: API-ключ показывается только при создании. Храните его в безопасном месте (env variables, secrets manager). Не передавайте в URL и клиентском коде.

Формат заголовка

Authorization: Bearer cf_live_XXXXXXXXXXXXXXXX...

Пример запроса (curl)

curl -H "Authorization: Bearer cf_live_UIBujy5g..." \
  -H "Content-Type: application/json" \
  https://courierflow.ru/api/v1/deliveries

Permissions (разрешения)

Каждый ключ может иметь ограниченный набор разрешений:

deliveries:readЧтение доставок

deliveries:writeСоздание и обновление доставок

couriers:readЧтение курьеров

couriers:writeСоздание и обновление курьеров

couriers:locationОтправка геопозиции курьера

webhooks:readЧтение webhook endpoints

webhooks:writeУправление webhook endpoints

analytics:readЧтение аналитики

organization:readДанные организации

Пустой массив permissions = доступ ко всему (legacy-ключи).

Rate Limiting

Защита от перегрузок на двух уровнях:

Per-key

60 req/min (настраиваемый)

Sliding window. Настраивается при создании ключа (0–1000).

Per-IP

200 req/min

Глобальный лимит для защиты от DDoS. Не настраивается.

Заголовки ответа

Headers при превышении лимита

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "error": "rate_limit_exceeded",
  "message": "Превышен лимит запросов: 60/мин. Повторите через 42с.",
  "limit": 60,
  "retryAfter": 42
}

Формат ошибок

Все ошибки возвращают JSON с полями error и message:

Пример ошибки

{
  "error": "unauthorized",
  "message": "Неверный или неактивный API-ключ."
}

401unauthorizedОтсутствует или неверный API-ключ

403forbiddenНедостаточно прав (permissions)

404not_foundРесурс не найден

422validation_error / status_change_errorОшибка валидации / невозможный переход статуса

429rate_limit_exceededПревышен лимит запросов

500create_error / fetch_errorВнутренняя ошибка сервера

GET/api/v1/deliveries

Получить список доставок организации с пагинацией и фильтрацией.

Query-параметры

page

number

Номер страницы (по умолчанию 1)

limit

number

Записей на странице (1–100, по умолчанию 20)

status

string

Фильтр по статусу: created, assigned, en_route, delivered, failed, canceled

curl

curl -H "Authorization: Bearer cf_live_..." \
  "https://courierflow.ru/api/v1/deliveries?page=1&limit=10&status=en_route"

Response 200

{
  "data": [
    {
      "id": "abc123",
      "organizationId": "org-xxx",
      "status": "en_route",
      "deliveryAddress": "ул. Ленина, 42",
      "deliveryContact": "Иван Петров",
      "deliveryPhone": "+79001234567",
      "courierId": "courier-1",
      "trackingToken": "TRK_abc123",
      "scheduledDate": "2026-02-10T00:00:00Z",
      "createdAt": "2026-02-08T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 147,
    "totalPages": 15
  }
}

Permission: deliveries:read

POST/api/v1/deliveries

Создать новую доставку. Автоматически генерируется трекинг-токен.

Body (JSON)

deliveryAddress*

string

Адрес доставки

deliveryContact

string

Имя получателя

deliveryPhone

string

Телефон получателя

pickupAddress

string

Адрес забора

description

string

Описание / комментарий

weight

number

Вес в кг

scheduledDate

ISO 8601

Дата доставки

tags

string[]

Теги для фильтрации

curl

curl -X POST -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryAddress": "ул. Ленина, 42, кв. 7",
    "deliveryContact": "Иван Петров",
    "deliveryPhone": "+79001234567",
    "weight": 2.5,
    "scheduledDate": "2026-02-10",
    "tags": ["fragile"]
  }' \
  https://courierflow.ru/api/v1/deliveries

Response 201

{
  "delivery": {
    "id": "new-id-123",
    "status": "created",
    "trackingToken": "TRK_xxxx",
    ...
  }
}

Permission: deliveries:write

GET/api/v1/deliveries/:id

Получить доставку по ID с историей статусов.

curl

curl -H "Authorization: Bearer cf_live_..." \
  https://courierflow.ru/api/v1/deliveries/abc123

Response 200

{
  "delivery": {
    "id": "abc123",
    "status": "en_route",
    "deliveryAddress": "ул. Ленина, 42",
    "statusHistory": [
      { "fromStatus": "assigned", "toStatus": "en_route", "createdAt": "..." },
      { "fromStatus": "created", "toStatus": "assigned", "createdAt": "..." }
    ],
    ...
  }
}

Permission: deliveries:read

PATCH/api/v1/deliveries/:id

Обновить поля доставки или сменить статус.

Обновление полей

curl (PATCH)

curl -X PATCH -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"deliveryAddress": "Новый адрес, 10"}' \
  https://courierflow.ru/api/v1/deliveries/abc123

Смена статуса

Передайте поле status в body. Сервер проверит допустимость перехода.

curl (status change)

curl -X POST -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "delivered",
    "note": "Оставлено у двери",
    "lat": 55.7558,
    "lng": 37.6173
  }' \
  https://courierflow.ru/api/v1/deliveries/abc123

Permission: deliveries:write

GET/api/v1/couriers

Получить список курьеров организации.

curl

curl -H "Authorization: Bearer cf_live_..." \
  https://courierflow.ru/api/v1/couriers

Response 200

{
  "data": [
    {
      "id": "c-1",
      "name": "Алексей Иванов",
      "phone": "+79001234567",
      "status": "available",
      "vehicleType": "car",
      "vehicleBrand": "Kia Rio",
      "vehiclePlate": "А123БВ77",
      "lastLat": 55.7558,
      "lastLng": 37.6173
    }
  ],
  "total": 12
}

Permission: couriers:read

POST/api/v1/couriers

Добавить нового курьера.

name*

string

ФИО курьера

phone

string

Телефон

email

string

vehicleType

string

Тип ТС: foot, bike, motorcycle, car, truck

vehicleBrand

string

Марка ТС

vehiclePlate

string

Номер ТС

curl

curl -X POST -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Алексей Иванов", "phone": "+79001234567", "vehicleType": "car"}' \
  https://courierflow.ru/api/v1/couriers

Permission: couriers:write

GET/api/v1/couriers/:id

Получить курьера по ID с историей последних смен.

curl

curl -H "Authorization: Bearer cf_live_..." \
  https://courierflow.ru/api/v1/couriers/c-1

Permission: couriers:read

PATCH/api/v1/couriers/:id

Обновить данные курьера или отправить геопозицию.

Обновление геопозиции

Передайте lat и lng для обновления позиции курьера на карте.

curl (геопозиция)

curl -X POST -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"lat": 55.7558, "lng": 37.6173}' \
  https://courierflow.ru/api/v1/couriers/c-1

Обновление профиля

curl (PATCH)

curl -X PATCH -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"vehicleBrand": "Toyota Camry", "vehiclePlate": "В456ГД77"}' \
  https://courierflow.ru/api/v1/couriers/c-1

Permission: couriers:write или couriers:location (для геопозиции)

Webhook-и

Webhook-и настраиваются через панель управления: Webhooks. Каждый запрос подписан HMAC-SHA256.

Формат payload

POST на ваш URL

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: a1b2c3d4e5...
X-Webhook-Event: delivery.completed

{
  "event": "delivery.completed",
  "payload": {
    "deliveryId": "abc123",
    "status": "delivered",
    "courierId": "c-1",
    "completedAt": "2026-02-08T14:30:00Z"
  },
  "timestamp": "2026-02-08T14:30:01Z",
  "signature": "a1b2c3d4e5..."
}

Доступные события

delivery.createdДоставка создана

delivery.assignedКурьер назначен

delivery.en_routeКурьер выехал

delivery.completedДоставка завершена

delivery.failedОшибка доставки

delivery.*Все события доставок

courier.locationОбновление позиции курьера

Проверка подписи

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

Retry-политика

3 попытки с задержкой: 1с → 5с → 15с
Таймаут ответа: 10 секунд
Успех: HTTP 2xx
Логи всех попыток видны в панели Webhooks

Готовы к интеграции?

Создайте API-ключ и начните интегрировать CourierFlow прямо сейчас

Создать API-ключ ← Документация