Для администратора и разработчика

Интеграции и API

Точные пользовательские сценарии и ссылки на опубликованный API contract.

Kontrum 1.0.0 · обновлено 16.08.2026

1. Виды каналов

Встроенные маркетплейсы

Kaspi.kz, Wildberries, Halyk Market и Flip.kz имеют identity, заданную Kontrum. Tenant может настроить или отключить подключение, но не удалить identity площадки.

Собственные каналы

Сайт или другая система клиента создаётся как tenant-owned custom channel. Respect.kz остаётся собственным каналом, а не пятым встроенным маркетплейсом.

2. Прямой API и «Через 1С»

Прямой API использует credential и контракт соответствующего канала.
Через 1С использует уже существующую базу из раздела «Подключение 1С» и не создаёт второй механизм подключения.

При режиме 1С marketplace credentials не требуются. При Direct API selector базы 1С не используется.

3. Работа с секретами

Секрет показывается только в момент создания или rotation, если это предусмотрено интерфейсом.
Обычный browser GET не возвращает secret.
Пустое поле при редактировании не должно менять существующий secret.
Никогда не передавайте API key в query string, скриншоте или support message.

4. Проверка собственного канала

В «Интеграции» создайте собственный канал.
Выберите «Прямой API» и создайте API-ключ.
Сохраните ключ в защищённом хранилище: повторно он не показывается.
Проверьте доступ через readiness endpoint.

curl -fsS -H "Authorization: Bearer YOUR_API_KEY" "https://api.kontrum.kz/api/v1/custom-integration-channels/YOUR_CHANNEL_ID/ready"

Успешный ответ содержит ok, название и разрешённые направления. Endpoint /ready проверяет доступ и не принимает заказы или товары.

Отдельного endpoint приёма данных здесь нетДля передачи canonical entities используйте только опубликованный контракт Universal Connector и выданный для него connector token. API-ключ канала не заменяет connector token в /api/v2/connectors/*.

5. API 2.0 и 2.1

Source of truth — OpenAPI, опубликованный самим Kontrum API. Protocol 2.0 / Schema 1.0 остаётся обратно совместимым; Protocol 2.1 / Schema 1.1 добавляет возможности только после capability negotiation.

Открыть API docs OpenAPI 2.0 OpenAPI 2.1 Postman

Проверка схемы без авторизации

curl -fsS "https://api.kontrum.kz/api/v2/schema"

Авторизация connector API

Authorization: Bearer YOUR_CONNECTOR_TOKEN
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY

Tenant определяется только по connector token. Поле tenantId в payload не меняет область данных.

6. Ошибки и безопасная диагностика

Сохраните HTTP status, безопасный response body и время запроса.
Для retry используйте только ошибки, отмеченные контрактом как retryable.
Не логируйте Authorization header.
Не повторяйте non-idempotent request с новым key, пока не проверили предыдущий результат.