Приём по 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 и номер, по которому заказ ищется у нас и у партнёра:

{
  "order_id": 100000042,
  "number": 42,
  "status": "Обработка",
  "duplicate_of": [100000019],
  "idempotent_replay": false
}

duplicate_of — прошлые заказы с тем же телефоном; заказ при этом принят, просто оператор увидит историю клиента. idempotent_replay отвечает на вопрос «создался ли новый заказ»: true означает, что вернулся уже существующий.

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

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

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

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

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

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

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