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

Внешние системы — склад, аналитика, старый бэкофис — читают заказы проекта по ключу. Пути и формат ответов повторяют LeadVertex, чтобы переезд сводился к замене адреса и токена, а не к переписыванию интеграции. Справочник методов лежит внутри системы и подставляет в примеры ваши номера статусов и товаров.

Два разных ключа

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

Ключ приёма отдают партнёру или лендингу — как, описано в Приёме заказов по API. Ключ проекта партнёру не выдают никогда.

1. 1Откройте вкладку Ключи проекта и нажмите Выпустить ключ.
2. 2В поле Кому выдаём напишите систему, а не человека: «Склад», «Аналитика». По этому названию потом отзывают доступ.
3. 3При необходимости заполните Разрешённые адреса, через запятую. Пусто — запрос пройдёт с любого адреса.
4. 4Переключатель Разрешить менять статусы и комментарии оставьте выключенным, пока запись действительно не понадобилась.
5. 5Скопируйте ключ из окна Ключ выпущен: в базе хранится только хеш, второй раз показать его система не сможет.

Авторизация и лимиты

• Методы в стиле LeadVertex принимают ключ параметром token в строке запроса.
• Приём заказов в собственном формате — заголовком Authorization: Bearer.
• Данные и ответы — в UTF-8. Ошибка приходит с кодом HTTP и текстом причины в теле.
• Частота ограничена на ключ, по умолчанию 600 запросов в минуту. При превышении приходит 429 с заголовком Retry-After.

Чтение заказов по ключу проекта попадает в журнал аудита: одна запись на запрос, с началом ключа вместо имени сотрудника. Смотреть её там же, где остальные журналы, — см. Защиту данных.

Методы

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

Примеры запросов

Справочник статусов — с него начинают, потому что дальше нужны их номера:

curl 'https://ваш-проект.xe.kg/api/admin/getStatusList.html?token=КЛЮЧ_ПРОЕКТА'

{"0": {"name": "Обработка", "group": "processing", "id": 12}}

Карточки заказов пачкой: номера через запятую, до ста за запрос.

curl 'https://ваш-проект.xe.kg/api/admin/getOrdersByIds.html?token=КЛЮЧ_ПРОЕКТА&ids=100000042,100000043'

{"100000042": {"fio": "Асанов А.", "status": 0, "total": "1990.00"}}

Смена статуса — только ключом с разрешением записи:

curl -X POST 'https://ваш-проект.xe.kg/api/admin/updateOrder.html?token=КЛЮЧ_ПРОЕКТА&id=100000042' \
  --data-urlencode 'status=1' \
  --data-urlencode 'comment=Подтверждён по телефону'

{"100000042": "OK"}

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

curl 'https://ваш-проект.xe.kg/api/admin/getOrdersIdsByConditionSearchAfter.html?token=КЛЮЧ_ПРОЕКТА&dateFrom=2026-08-01&dateTo=2026-08-08'

{"ids": [100000042, 100000043], "searchAfter": 100000043}

В интерфейсе те же примеры показаны с вашим адресом и вашими номерами товаров и статусов — их копируют в терминал целиком.

Ошибки и чего нет

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