Документация API Ket Logistic

Обзор

Заказ создаётся одним запросом POST на эндпоинт выше. Тело — JSON с данными получателя и, при необходимости, списком позиций. Для доступа нужен ключ API партнёра (см. «Ключ API»). Ответ всегда в формате JSON в обёртке result.

• Протокол: HTTPS рекомендуется в продакшене; хост и точный URL вы берёте из строки эндпоинта на этой странице
• Кодировка тела: UTF-8
• Основной тип содержимого: Content-Type: application/json
• Альтернатива (удобно для PHP и старых интеграций): application/x-www-form-urlencoded с одним полем data — его значение это строка JSON с теми же полями, что и при прямой отправке JSON
• Это API Ket Logistic, не внешние сервисы третьих сторон; контракт ниже описывает только приём заказа в нашу систему

Чек-лист для подключения партнёра

1. Получить у менеджера Ket Logistic ключ API и убедиться, что карточка партнёра в системе активна
2. Реализовать вызов только с вашего бэкенда (сервер магазина, CRM, 1С и т.д.) — не из браузера покупателя
3. Передавать ключ в заголовке Authorization: Bearer … или X-API-Key (см. «Авторизация»)
4. Отправлять обязательные поля: телефон, ФИО, полный адрес доставки; при необходимости — external_id для идемпотентности
5. Обрабатывать HTTP-коды и JSON: успех 201 (новый заказ), 200 (повтор с тем же external_id), ошибки 401 / 400 / 500
6. Сохранять возвращаемый result.id — внутренний номер заказа у Ket Logistic для сверки с панелью

Ключ API: где получить и как использовать

Где. Ключ привязан к вашей компании как к партнёру Ket Logistic. Его выдаёт и при необходимости обновляет наша служба (сотрудники с доступом к внутренней панели управления): в карточке партнёра → блок «Интеграция API» — там отображается текущий ключ и кнопка копирования. Эта страница документации не содержит входа в панель и не предназначена для получения ключа — для этого свяжитесь с вашим менеджером Ket Logistic.

Как создаётся. После первого сохранения карточки партнёра в системе ключ генерируется автоматически (один уникальный ключ на партнёра). Сотрудник может сгенерировать новый ключ в той же карточке — тогда предыдущий перестаёт действовать, и обновить ключ нужно во всех ваших системах (CRM, сайт, 1С).

Как передавать в запросах (рекомендуется). В заголовках HTTP (см. «Авторизация»): Authorization: Bearer … или X-API-Key. Так безопаснее для логов и прокси.

Альтернатива. Ключ можно передать в теле JSON полем api_key (если заголовки недоступны в вашей среде). Этот способ менее предпочтителен: ключ чаще попадает в лишние логи. Не вставляйте ключ в клиентский JavaScript, мобильные приложения и открытые репозитории — только обмен сервер-сервер.

Если партнёр отключён в системе (неактивен), запросы с даже верным ключом не принимаются.

Структура заказа (JSON)

Минимально нужны три поля получателя и доставки. Остальное — для синхронизации с вашей системой и для отображения состава в панели.

{
  "recipient_phone": "+77028540451",
  "recipient_name": "Иванов Иван Иванович",
  "delivery_address": "г. Алматы, ул. Абая, д. 150, кв. 25",
  "external_id": "SHOP-2026-1001",
  "comment": "Позвонить за час",
  "items": [
    { "name": "tovar_sku_a", "quantity": 2, "price": "5000.00" },
    { "name": "tovar_sku_b", "quantity": 1, "price": "3200.50" }
  ]
}

Если items не передать, но указать одну строку offer (как в старых интеграциях), будет создана одна позиция с этим названием.

Как данные отображаются в системе

После успешной отправки заказ попадает в работу диспетчеров: в списке заказов с колонками, соответствующими полям API. Соответствие полей и интерфейса:

Поиск на странице заказов учитывает ФИО, телефон, адрес, комментарий, внутренний и внешний номер.

Авторизация

Ключ обязателен при каждом запросе. Допустим один из вариантов (приоритет сверху вниз):

Если ключ отсутствует или не совпадает с активным партнёром — ответ 401. У неактивного партнёра приём заказов также отклоняется.

Поля запроса (JSON)

Имена ниже — канонические. Для совместимости с другими схемами принимаются алиасы (одна колонка «или»).

* Обязательно либо осмысленный items/offer, либо пустой состав (служебная строка в панели). † Обязателен ключ в запросе любым из способов из раздела «Авторизация».

Алиасы полей (совместимость)

Позиции заказа (items)

Каждый элемент массива items — объект с полями:

Пустые или некорректные элементы массива пропускаются. Если ни одна позиция не пришла, но передан offer, создаётся одна позиция из этой строки.

Ответ сервера

Всегда JSON. Поле result.success — булево значение JSON (true / false), не строка.

Новый заказ создан

HTTP 201 Created. Внутренний идентификатор заказа в Ket Logistic — строка в result.id (его стоит сохранять у себя для сверки).

{
  "result": {
    "success": true,
    "message": "200 OK",
    "id": "12345"
  }
}

Повтор того же external_id

Если вы снова отправляете запрос с external_id, который уже был успешно принят для вашего партнёра, второй заказ не создаётся. Возвращается HTTP 200 OK, тот же id и признак дубликата:

{
  "result": {
    "success": true,
    "message": "Заказ с таким external_id уже существует.",
    "id": "12345",
    "duplicate": true
  }
}

Примеры

curl -X POST "https://api.ketkz.kz/api/v1/orders/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -d '{
    "recipient_phone": "+77028540451",
    "recipient_name": "Иванов Иван",
    "delivery_address": "г. Алматы, ул. Абая, 150, кв. 25",
    "external_id": "SHOP-1001",
    "items": [
      {"name": "tovar_a", "quantity": 2, "price": "5000.00"}
    ]
  }'

curl -X POST "https://api.ketkz.kz/api/v1/orders/" \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -d 'data={"recipient_phone":"+77028540451","recipient_name":"Иванов","delivery_address":"г. Алматы, ул. Абая, 150"}'

В значении data — одна JSON-строка; кавычки внутри экранируйте по правилам вашей оболочки.

curl -X POST "https://api.ketkz.kz/api/v1/orders/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ВАШ_КЛЮЧ",
    "recipient_phone": "+77028540451",
    "recipient_name": "Иванов Иван",
    "delivery_address": "г. Алматы, ул. Абая, 150"
  }'

Ошибки и коды HTTP

При ошибке result.success равен false. Примеры:

{
  "result": {
    "success": false,
    "message": "Укажите ключ API (заголовок Authorization: Bearer … или X-API-Key)."
  }
}

{
  "result": {
    "success": false,
    "message": "Неверный ключ API или партнёр неактивен."
  }
}

{
  "result": {
    "success": false,
    "message": "Обязательное поле: delivery_address (адрес доставки)."
  }
}

Точный текст message может уточняться; ориентируйтесь на код HTTP и на то, какое поле не прошло проверку.

Ограничения и поведение

• external_id — до 100 символов (лишнее обрезается)
• Телефон получателя — до 30 символов после нормализации пробелов
• ФИО получателя — до 200 символов
• Наименование позиции (items[].name) — до 250 символов
• Количество в позиции — целое от 1 до 9999
• Выгрузка списка заказов и статусов через отдельный публичный URL в этой версии API не предусмотрена — учёт ведётся в панели Ket Logistic; при необходимости обсудите с менеджером отдельные сценарии

Безопасность и рекомендации

• Храните ключ только на сервере; не вшивайте в мобильные приложения и фронтенд магазина
• При смене ключа в панели обновите его во всех системах, которые бьют в API
• Используйте HTTPS при обращении к API в продакшене
• Для идемпотентности повторных отправок используйте стабильный external_id на стороне магазина