Интеграция через API

API Технокренделя нужен для обмена данными между порталом и внешними системами: ERP, WMS, CRM, учетными системами покупателя, поставщика или посредника.

Через API можно передавать заявки, получать заказы, обновлять статусы, отправлять документы и синхронизировать данные по доставке.

Базовый адрес

Все запросы проходят через API Gateway:

https://services.technokrendel.ru/api-gateway/api/v1/<token>/<url>

Где:

• <token> - токен интеграции, который выдает команда Технокренделя.
• <url> - путь конкретного метода API, например orders/TC-2026-000124.

Пример полного URL:

https://services.technokrendel.ru/api-gateway/api/v1/8f3a2c9e/orders/TC-2026-000124

Авторизация

Токен передается в URL после версии API:

/api-gateway/api/v1/<token>/<url>

Дополнительный заголовок Authorization для базового сценария не требуется.

warning

Токен в URL является секретом. Не публикуйте его в документации, скриншотах, чатах и логах, которые доступны сторонним пользователям.

Формат данных

API принимает и возвращает JSON в кодировке UTF-8.

Content-Type: application/json; charset=utf-8
Accept: application/json

Даты и время передаются в ISO 8601:

2026-04-28T16:30:00+03:00

Денежные значения передаются числом с двумя знаками после запятой, валюта - отдельным полем:

{
  "amount": 15420.50,
  "currency": "RUB"
}

Заголовки запроса

Заголовок	Обязателен	Назначение
Content-Type	Да для POST, PUT, PATCH	Формат тела запроса.
Accept	Рекомендуется	Ожидаемый формат ответа.
X-Request-Id	Рекомендуется	Уникальный идентификатор запроса для трассировки.
Idempotency-Key	Рекомендуется для создания	Защита от дублей при повторной отправке запроса.
X-Client-System	Рекомендуется	Название внешней системы, например customer-erp.

Методы API

• Создать заявку покупателя
• Получить заявку
• Получить список заказов
• Получить заказ
• Подтвердить заказ поставщиком
• Обновить статус заказа
• Передать данные доставки
• Загрузить документ
• Получить документы заказа
• Webhook для статусов

Идемпотентность

Для операций создания используйте Idempotency-Key. Если сеть оборвалась и клиент повторил тот же запрос с тем же ключом, API должен вернуть результат первичной операции, а не создать дубль.

Рекомендованный формат ключа:

<system-code>-<operation>-<external-id>

Пример:

erp-request-RQ-2026-0412

Ошибки

Ошибки возвращаются в едином формате.

{
  "error": {
    "code": "validation_error",
    "message": "Некорректные данные запроса",
    "details": [
      {
        "field": "items[0].quantity",
        "message": "Количество должно быть больше 0"
      }
    ]
  },
  "requestId": "0e8c4a25-d707-4d2a-8d93-0d7154ce1c83"
}

HTTP-код	Когда возникает
400 Bad Request	Некорректное тело запроса или параметры.
401 Unauthorized	Не передан или недействителен токен в URL.
403 Forbidden	Нет прав на операцию или объект.
404 Not Found	Объект не найден.
409 Conflict	Конфликт состояния или дубль операции.
422 Unprocessable Entity	Данные корректны синтаксически, но не проходят бизнес-проверки.
429 Too Many Requests	Превышен лимит запросов.
500 Internal Server Error	Внутренняя ошибка сервера.

Повторы запросов

Повторяйте запросы только для временных ошибок: 429, 500, 502, 503, 504. Для POST используйте тот же Idempotency-Key, чтобы избежать дублей.

Рекомендуемая стратегия:

1. Повтор через 5 секунд.
2. Повтор через 30 секунд.
3. Повтор через 2 минуты.
4. Если ошибка сохраняется, передайте X-Request-Id в поддержку.

Чеклист подключения

• Получен токен интеграции.
• Все запросы отправляются на https://services.technokrendel.ru/api-gateway/api/v1/<token>/<url>.
• В запросах передаются Content-Type, Accept и X-Request-Id.
• Для создания заявок, документов и данных доставки используется Idempotency-Key.
• Внешняя система хранит идентификаторы Технокренделя и свои externalId.
• Обработаны ошибки 400, 401, 403, 404, 409, 422, 429 и 5xx.
• Настроены логи запросов с маскированием токена в URL.
• Согласован формат webhook, если нужны входящие уведомления.