Приём по API: ключи, потоки, поля

Нативный приём — способ отдавать заказы в систему из своего кода: с лендинга, из скрипта партнёра, из чужой CRM. Один запрос на заказ, ответ сразу с номером, понятные коды ошибок и защита от повторной отправки.

Ключ приёма

Ключ приёма создаёт заказы и позволяет запросить статус доступного ему заказа в своём проекте. Ключ, связанный с вебмастером, читает только статусы заказов этого партнёра. Он не меняет статусы и не даёт общего доступа к карточкам клиентов. Это другой ключ, чем в разделе APIКлючи проекта: тот работает с заказами и партнёрам не выдаётся, о нём — статья API проекта.

1. 1Нажмите Выпустить ключ.
2. 2Укажите Вебмастер — тогда все заказы по этому ключу закрепятся за партнёром, и статистика с выплатами посчитаются сами. Для своего лендинга оставьте Внутренний ключ.
3. 3Выберите Поток по умолчанию, если у партнёра он один: тогда ему не нужно передавать код потока в каждом запросе.
4. 4Заполните Разрешённые адреса, когда у партнёра постоянный сервер. Украденный ключ с чужого адреса работать не будет.

Запрос и поля

Один POST на адрес приёма, тело — JSON, ключ в заголовке Authorization:

curl -X POST https://ваш-проект.xe.kg/api/v1/intake/orders \
  -H 'Authorization: Bearer vtx_a1b2c3d4_ВАШ_СЕКРЕТ' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-12345' \
  -d '{
    "external_id": "12345",
    "flow": "kg_fb_01",
    "fio": "Асанов Азамат",
    "phones": ["0555123456"],
    "region": "Чуйская область",
    "city": "Бишкек",
    "address": "ул. Киевская, 95",
    "items": [{"product_id": 950, "quantity": 2}],
    "ip": "213.145.1.5",
    "time_spent": 47
  }'

Обязательное поле одно — phones: от одного до пяти номеров в любом виде, мы приведём их к международному. Заказ без телефона в колл-центре бесполезен, звонить по нему некому. Остальное:

Ещё принимаются email, country, region, city, address, house, flat, post_index, comment, domain, referer. Незнакомое поле в теле — ошибка, а не молчаливое игнорирование: опечатку в имени лучше заметить при подключении, чем через месяц по пустым адресам.

Ответ и ошибки

Успех — код 201 после сохранения заказа в базе. Ответ уже подтверждает приём и содержит номер заказа. Дополнительное ожидание фонового приёма через ответ 202 или опрос статуса здесь не требуется:

{
  "order_id": 100000042,
  "number": 42,
  "status": "Обработка",
  "status_group": "processing",
  "duplicate_of": null,
  "idempotent_replay": false
}

Повтор того же запроса с прежним ключом идемпотентности вернёт тот же заказ и idempotent_replay: true. Изменённые данные под уже использованным ключом дают конфликт. Отдельная проверка дублей по телефону может принять новую заявку с отметкой дубля; это не повтор сохранённого запроса. duplicate_of указывает найденные прежние заказы, а idempotent_replay — повтор по ключу.

Чтение статуса

После успешного приёма можно узнавать последующие изменения заказа: отправьте GET на /api/v1/intake/orders/{order_id} с тем же способом авторизации. Используйте order_id из ответа приёма. Ответ содержит идентификатор заказа, статус, группу статуса и внешний идентификатор; телефона, имени и адреса клиента в нём нет.

Этот запрос нужен, когда партнёру важен текущий статус. Успешный POST уже подтвердил создание, поэтому запускать частый опрос ради подтверждения приёма не нужно. Если ответ на POST потерян, повторите исходный POST с тем же ключом и данными.

Повторы и лимиты

До первой отправки сохраните данные заявки и постоянный ключ повтора. Ключом служит заголовок Idempotency-Key, а если его нет — external_id. При таймауте или потере ответа отправляйте прежний ключ и те же данные. Если заказ уже принят, конвейер вернёт его с idempotent_replay: true.

Лимит задаётся на каждый ключ отдельно, по умолчанию 120 запросов за фиксированную минуту UTC отдельно на создание и на чтение статусов. Опрос статусов не расходует лимит создания. Нативный приём и три адреса приёма LeadVertex используют один бюджет создания ключа. В следующую минуту счётчики начинаются заново. Дополнительно действуют ограничения сервера по IP; у нативного создания и чтения статусов они тоже разделены. Повышение лимита ключа само по себе не снимает ограничение по IP.

• Держите одну отправку на ключ заявки. После 201 прекратите повторы создания. Для таймаута или 5xx увеличивайте паузу: 1, 2, 4, 8, 16, 32, затем 60 секунд, добавляя случайные 0–25% к каждой паузе. После восьми повторов или 15 минут оставьте заявку на сверку с прежним ключом, вместо бесконечной отправки.
• При 429 приостановите очередь соответствующей операции минимум на число секунд из Retry-After, затем добавьте небольшую случайную паузу. Ограничение опроса статусов не требует останавливать создание заявок. Учитывайте этот заголовок и при 503, если он есть; без него используйте описанное увеличение задержки. Ошибки 401, 403, 409 и 422 требуют разбора причины, а не автоматических повторов.
• Разделите очереди создания и опроса, чтобы ожидание статуса не задерживало новые заявки. Консервативная начальная настройка для каждой — один запрос в секунду без накопленного залпа. Если IP или ключ используют другие программы, оставьте им запас и уменьшите эту частоту.
• Опрос статуса начинайте с интервала 60 секунд. Если статус не меняется, увеличивайте интервал до 120, затем 300 секунд и добавляйте случайную паузу. Не опрашивайте один заказ параллельно; всю очередь держите в лимите чтения статусов. Нужную свежесть, срок наблюдения и статусы прекращения опроса согласуйте с получателем данных.

Что отдать партнёру

Не переписывайте эту статью в переписку. В списке ключей у каждой строки есть кнопка документации: она копирует ссылку вида /partner-docs?src=… с подписью. Открывается без пароля и собрана под конкретный проект — там уже подставлены адрес приёма, список товаров с идентификаторами для goodID, доступные партнёру потоки, таблица полей с их именами в формате LeadVertex, готовые примеры запросов, коды ошибок, статусы проекта и список макросов постбэков.

• Токен по этой ссылке не передаётся — только подпись, восстановить ключ по ней нельзя.
• Отозвали ключ — документация по его ссылке перестаёт открываться.
• Проверять, дошли ли запросы, удобнее по колонке Последнее обращение и по журналу приёма: Способы передачи заказов.

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