Инструкция по партнёрскому API

1. Быстрый старт

1. Откройте мини-приложение бота → Профиль → API и создайте токен: имя, срок действия, доступ («только каталог» или «каталог и заказы») и при необходимости канал (склад + валюта, как направления в боте). Раздел виден, только если менеджер включил вам API.
2. Общий токен — все каналы, которые разрешил менеджер. Узкий — один выбранный канал: витрина и заказы только по этому складу и валюте.
3. Токен показывается один раз. Сохраните его в секретном хранилище; в репозиторий и клиентский код его класть нельзя. При утечке отзовите токен там же и выпустите новый.
4. Передавайте токен в каждом запросе: Authorization: Bearer fcp_….

export FC_API="https://api.unimtrn.com/api/partner"
curl -H "Authorization: Bearer $FC_TOKEN" "$FC_API/schedule"

Базовый адрес API: https://api.unimtrn.com/api/partner. API серверное: браузерные запросы (CORS) не поддерживаются, вызывайте его с вашего сервера.

2. Общие правила

• Цена — как у вас в боте (тип цены, наценка, валюта из карточки клиента). Цену вы не передаёте никогда: её определяет сервер, в том числе по шкале для количества.
• Склады и валюта — из каналов токена (карточка клиента ∩ политика менеджера ∩ выбор при выпуске). Если склад один, параметр warehouse можно не указывать. Узкий токен с одной валютой отдаёт цены только в ней.
• Часы работы. У бота есть расписание: он принимает заказы только в рабочие часы. Часы на сегодня можно узнать запросом GET /schedule (он отвечает всегда, в том числе когда бот закрыт); менеджер тоже сообщит их.
  • Изменения заказа (добавить позицию, изменить количество, убрать строку, отменить заказ) вне рабочих часов не принимаются: ответ 423 bot_closed. Это действует всегда.
  • Каталог (/catalog, /brands, /categories) вне рабочих часов закрыт только в том случае, если менеджер включил вам соблюдение расписания; тогда он тоже отвечает 423 bot_closed. Если не включил, каталог доступен круглосуточно.
  • 423 bot_closed — не ошибка запроса. Повторите его в рабочее время; при повторе используйте тот же Idempotency-Key: отказ по расписанию не запоминается, и действие выполнится заново.
  • Если время работы бота на сегодня известно, оно приходит прямо в ответе, в поле error.details: время открытия и закрытия и часовой пояс, в котором оно указано. Если известно только, что бот сейчас не принимает запросы, поля details в ответе нет. Пример:

    HTTP 423
    {
      "error": {
        "code": "bot_closed",
        "message": "Бот закрыт. Сегодня работает с 10:00 до 18:00 (Asia/Dubai)",
        "details": { "opensAt": "10:00", "closesAt": "18:00", "timezone": "Asia/Dubai" }
      }
    }

• Лимиты запросов задаёт менеджер. При превышении — 429 rate_limited: подождите и повторите. Много неверных токенов подряд с одного IP тоже ведут к 429.
• Версии в пути нет. Несовместимые изменения оформляются новыми полями и эндпоинтами: игнорируйте неизвестные поля в ответах.

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

HTTP 403
{ "error": { "code": "scope_missing", "message": "…" } }

Ориентируйтесь на code, а не на текст message. Основные группы:

Примеры ошибок при работе с заказом

Устаревший lineId:

HTTP 409
{
  "error": { "code": "line_changed", "message": "Строка заказа изменилась, перечитайте заказ" },
  "order": { "id": "6ae9aefdd12dd7057d4bf68e", "lines": [ "…" ] }
}

Нет остатка:

HTTP 422
{ "error": { "code": "order_rejected", "message": "Товар недоступен в нужном количестве" } }

Действие отключено менеджером:

HTTP 403
{ "error": { "code": "forbidden", "message": "Удаление строк заказа через API отключено для этого клиента" } }

Числа, коды товаров, цены и идентификаторы в примерах условные.

8. Idempotency-Key

Зачем. Если ответ не получен, повтор «вслепую» опасен. Ключ гарантирует: повтор с тем же ключом вернёт ответ первого запроса, а не выполнит действие дважды.

Где нужен. Все изменяющие запросы заказов: POST /orders/lines, PATCH, DELETE, POST …/cancel. Без него — 400 idempotency_key_required. Для GET не нужен.

Кто создаёт. Ваша система, перед запросом (например UUID v4). Новое действие — новый ключ. Сохраните ключ до получения ответа.

KEY=$(uuidgen)
curl -sS -X PATCH "https://api.unimtrn.com/api/partner/orders/$ORDER/lines/$LINE" \
  -H "Authorization: Bearer $FC_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"qty": 5}'
# ответ не получен — повтор с тем же $KEY
# → 200 и заголовок Idempotent-Replay: true

• Один ключ — одно действие. 8–128 символов: A-Za-z0-9_.:-.
• Тот же ключ с другим запросом — 422 idempotency_key_reused.
• Пока первый запрос выполняется — 409 request_in_progress; подождите и повторите.
• Бизнес-отказы (409, 422) запоминаются. Временные (423, 429, 503) — нет.

9. Частые вопросы

• 403 api_disabled / orders_disabled. API или заказы не включены вам менеджером.
• 422 order_rejected. Нет остатка, исчерпана квота или позиция недоступна — причина в message.
• 422 onec_error. Учётная система не приняла изменение. Обратитесь к менеджеру, если повторяется.
• Токен перестал работать. Проверьте срок и отзыв в Профиль → API; код ошибки 401 говорит, что именно произошло.