Как подключиться

Пошаговый сценарий регистрации и получения доступа к API

1
Зарегистрируйте организацию
POST/clients
Укажите БИН, наименование, email, телефон и контактное лицо. Вы автоматически станете владельцем (OWNER), а статус аккаунта перейдет в PENDING_VERIFICATION.
2
Привяжите верификационные документы
POST/clients/{id}/documents
Загрузите файлы (договор, свидетельство БИН, доверенность) в хранилище и передайте массив полученных fileId для привязки к вашей организации.
3
Настройка биллинга и пополнение
POST/clients/{id}/topup
Администратор проверяет документы и назначает модель оплаты (Prepaid/Postpaid). При предоплате - отправьте запрос на пополнение баланса и дождитесь подтверждения.
4
Авторизация в ЕСУТД (OAuth)
GET/oauth/consent
Получите ссылку на консент и перейдите на портал ЕСУТД. Подтвердите доступ с помощью ЭЦП первого руководителя. После возврата (callback) аккаунт получит статус ACTIVE.
5
Сгенерируйте X-API-KEY
POST/clients/{id}/api-key
В панели управления создайте API-ключ. В целях безопасности значение ключа отображается на экране только у владельца. Вы можете создавать несколько ключей и управлять ими.
6
Отправляйте запросы в ЕСУТД
POST/api/proxy
Передавайте метод ЕСУТД и тело запроса в POST /api/proxy с заголовком X-API-KEY. Smart Cargo проверяет ключ, баланс и проксирует вызов в ЕСУТД.

Модели биллинга

Выберите модель после успешной верификации документов

prepaidPrepaid (предоплата)
Пополняйте баланс по счёту. Каждый успешный запрос в ЕСУТД списывает одну единицу. При balance = 0 запросы блокируются.
Полный контроль расходов
Email при 80% и 100% баланса
Нет неожиданных счетов
Нужно следить за балансом
Минимальное пополнение 1000 ₸
postpaidPostpaid (постоплата)
Запросы не блокируются. Счёт выставляется в конце расчётного периода (месяц). Требует реквизиты организации.
Никаких блокировок
Единый счёт в конце месяца
Удобно при непредсказуемом объёме
Требует загрузку реквизитов
Счёт формируется постфактум

Авторизация

Три независимые схемы: JWT для аккаунта, X-API-KEY для proxy

JWTКлиент (аккаунт)
Authorization: Bearer <jwt>
Токен пользователя, выдаётся при логине. Используется для управления аккаунтом организации.
Загрузка документов, биллинг, управление ключом, статистика
X-API-KEYКлиент (proxy)
X-API-KEY: <key>
Ключ для proxy-запросов в ЕСУТД. Генерируется отдельно от JWT.
Отправка запросов в ЕСУТД через Smart Cargo

Методы API клиента

Регистрация, документы, биллинг, статистика, управление ключом

Все запросы ниже (кроме регистрации и входа) требуют заголовок Authorization: Bearer <jwt>
Регистрация и вход
Клиенты
Документы и статус
Биллинг
Подтверждение доступа
Каждая организация может иметь несколько активных ключей одновременно. Каждый ключ привязан к своему биллинговому аккаунту — списание идёт с него.
Управление X-API-KEY
Сотрудники