Supplier API — контур для ERP/интеграций поставщиков промокодов. Префикс /v1/supplier/, ключи bk_sup_*.
Для кого этот раздел
Для кого: IT и ERP поставщиков промокодов (Промомед, Эркафарм и др.). Ключ bk_sup_* привязан к одному юрлицу — видны только ваши поступления и ваши коды. Партнёры и площадки этот контур не используют.
Логика работы с API
Типовой цикл интеграции: ночью ERP выгружает файл с новыми кодами (create → upload-url → import), днём сверяет историю (incoming/list) и отправляет активации покупателей (usage/report-bulk). Между import и completed — poll incoming/get каждые 10–30 сек.
Базовый URL
- Production:
https://api-external.promanta.ru - Локально:
http://localhost:7314
Аутентификация
Заголовок X-Api-Key: bk_sup_…. Supplier id определяется ключом.
Ключ создаётся в карточке поставщика в разделе «Промокоды».
Формат запроса и ответа
Все методы — POST, JSON: { "meta": {}, "data": {} }. Ответ: success, data, meta (requestId, serverTime).
Методы по сценариям
0. Старт: проверка ключа
Smoke-test после выдачи ключа в карточке поставщика.
- Проверка API-ключа поставщика —
POST /v1/supplier/profile/get
0.1. Товары поставщика
Справочник только ваших SKU. Создайте товар → передайте productId в поставку.
- Список товаров поставщика —
POST /v1/supplier/products/list - Карточка товара поставщика —
POST /v1/supplier/products/get - Создание товара поставщика —
POST /v1/supplier/products/create
1. Новая поставка кодов
Два пути: файл (create → upload-url → import) или JSON (codes/bulk-create one-shot / чанки). После completed — webhook и/или poll incoming/get.
- Создание новой поставки кодов —
POST /v1/supplier/incoming/create - Ссылка для загрузки файла поставщиком —
POST /v1/supplier/incoming/upload-url - Запуск импорта файла поставщика —
POST /v1/supplier/incoming/import - Загрузка поставки промокодов (JSON) —
POST /v1/supplier/incoming/codes/bulk-create - Статус импорта поступления —
POST /v1/supplier/incoming/get
2. История и сводки
Сверка с ERP: что отправляли, сколько кодов принято, остатки по статусам.
- История поступлений поставщика —
POST /v1/supplier/incoming/list - Сводка промокодов по статусам —
POST /v1/supplier/promo-codes/summary
3. Поиск и проверка кода
Список с маской для массовых данных; полный код — только для support (audit).
- Список промокодов поставщика —
POST /v1/supplier/promo-codes/list - Полное значение промокода —
POST /v1/supplier/promo-codes/get
4. Активации у покупателя
Пакетный отчёт «код активирован у нас» → статус redeemed в PROMANTA. До 1000 строк, Idempotency-Key обязателен.
- Сообщение об активации одного кода —
POST /v1/supplier/usage/report - Пакетное сообщение об активации кодов —
POST /v1/supplier/usage/report-bulk
MCP
Те же операции доступны через MCP: /mcp/internal, /mcp/supplier, /mcp/platform с тем же ключом/JWT.
Пример запроса (smoke-test)
{
"meta": { "requestId": "smoke-001" },
"data": {}
}Пример ответа
{ "success": true, "data": { "supplierId": "c219ef09-…", "name": "Промомед", "inn": "7701234567", "isActive": true } }cURL
curl -X POST "https://api-external.promanta.ru/v1/supplier/profile/get" \
-H "Content-Type: application/json" \
-H "X-Api-Key: bk_sup_YOUR_KEY" \
-d '{"data": {}}'