Главная / Документация / API

API для разработчиков

Версия v1

Два направления обмена: вы отправляете заказы в платформу, платформа сообщает вашей системе об изменениях статуса. Оба доступны на любом тарифе.

1. Ключ доступа

Ключ выпускается в панели: раздел «Интеграции» → «Ключи API», доступен администратору компании. Задаются название и срок действия — бессрочно, 90 дней или год.

Ключ показывается один раз, сразу после выпуска — в базе хранится только его свёртка. Потеряли — выпускайте новый.

Там же ключ можно заменить (новый с теми же правами, старый перестаёт работать сразу — так поступают, если ключ мог утечь) или отозвать. В списке видно время последнего обращения: по нему заметно, что интеграция замолчала.

Ключ передаётся заголовком X-API-Key. Базовый адрес:

https://app.fast-shipping.ru/backend/api/v1

2. Создание заказа

POST /api/v1/orders
X-API-Key: <ваш ключ>
Content-Type: application/json

{
  "external_id": "CRM-10423",
  "customer_name": "Иван Петров",
  "customer_phone": "+7 999 000-11-22",
  "address_raw": "Москва, ул. Пушкина, д. 1, кв. 5",
  "delivery_date": "2026-09-10",
  "time_window_start": "14:00",
  "time_window_end": "18:00",
  "items_summary": "Кофемашина, 1 шт.",
  "total_price": "24990.00",
  "payment_type": "cash",
  "extra_fields": { "menedzher": "Смирнова", "kanal": "маркетплейс" }
}

Ответ:

{
  "id": "6f1c...",
  "external_id": "CRM-10423",
  "status": "new",
  "created": true,
  "tracking_token": "b3xk...",
  "tracking_url": "https://t.fast-shipping.ru/t/b3xk..."
}

tracking_url — публичная ссылка для получателя. Её можно сразу подставить в своё письмо или SMS. Ссылка живёт 30 дней с момента создания заказа.

3. Повторная отправка

Заказ опознаётся по external_id в пределах вашей компании. Повторный запрос с тем же значением обновит существующий заказ, а не создаст второй: в ответе придёт "created": false.

Поэтому при сбое сети запрос можно спокойно повторить — дублей не будет.

4. Ошибки и ограничения

Ограничение частоты — 120 запросов в минуту на ключ. Для разовой загрузки большого объёма удобнее импорт файлом в панели.

5. Уведомления в вашу систему

Подписка создаётся в панели: раздел «Интеграции» → «Вебхуки». Указываете адрес (только https) и, при желании, список интересующих событий. Пустой список означает «все события».

Тип события — order.<статус>: order.assigned, order.in_transit, order.delivered, order.canceled, order.rescheduled.

POST <ваш адрес>
X-FastShipping-Event: order.delivered
X-FastShipping-Signature: sha256=<подпись>
Content-Type: application/json

{
  "event": "order.delivered",
  "occurred_at": "2026-09-10T15:42:11+03:00",
  "order": {
    "id": "6f1c...",
    "external_id": "CRM-10423",
    "status": "delivered",
    "collected_amount": "24990.00",
    "extra_fields": { "menedzher": "Смирнова" },
    "tracking_url": "https://t.fast-shipping.ru/t/b3xk..."
  }
}

Возвращённые external_id и extra_fields позволяют найти заказ в вашей системе, не сохраняя наших идентификаторов.

Повторы. Если ваш адрес не ответил успехом, доставка повторяется: всего до пяти попыток с растущей паузой — минута, две, четыре и так далее. Если подписка не отвечает пять раз подряд, она отключается автоматически, чтобы очередь не забивалась мёртвым адресом.

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

При создании подписки выдаётся секрет вида whsec_... — он показывается один раз. Каждое уведомление подписывается им: HMAC-SHA256 от тела запроса, в заголовке X-FastShipping-Signature в формате sha256=<hex>.

Проверяйте подпись до того, как доверитесь содержимому: адрес вашего обработчика открыт в интернет, и постучаться туда может кто угодно.

import hmac, hashlib

def valid(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    # сравнение с постоянным временем: обычное == подсказывает подбор
    return hmac.compare_digest(expected, header)

Подпись считается от байтов тела запроса как они пришли. Если сначала разобрать JSON, а потом собрать обратно, подпись не сойдётся — порядок ключей и пробелы изменятся.

7. Если события перестали приходить

Разбор начинается в панели, в разделе «Интеграции»: там видно и то, что происходит с подпиской, и каждую отправку по отдельности. Порядок такой.

Сначала посмотрите на состояние подписки. Если под адресом написана причина отключения — подписка погашена автоматически после пяти неудач подряд, и новые события в неё уже не ставятся. Почините приёмник и нажмите «Включить»; счётчик неудач начнётся заново. Пока подписка выключена, события не копятся — они просто не создаются.

Потом откройте журнал доставок. Он отвечает на вопрос, который иначе выясняется перепиской: отправляли мы событие или нет.

Потерянное событие можно отправить заново. У несостоявшейся доставки есть кнопка «Отправить снова»: тело события хранится с момента, когда оно произошло, поэтому повтор придёт таким же, каким пришёл бы тогда, — даже если заказ с тех пор изменился. Восстанавливать что-то у себя вручную не нужно.

Кнопка не появится, пока подписка выключена: отправлять было бы некуда. Сначала включите подписку, потом повторяйте доставки.

Частая причина, которую стоит исключить сразу. Обработчик должен отвечать быстро и кодом 2xx. Если он сначала делает всю работу и только потом отвечает, при долгой обработке мы посчитаем доставку неудачной и повторим её — а вы получите то же событие дважды. Отвечайте сразу, а работу ставьте в свою очередь; на нашей стороне повторная доставка того же события возможна и это нормально.

Вопросы

Пишите на support@fast-shipping.ru — приложите пример запроса и полученный ответ.