Platform API — контур для площадок продаж (маркетплейсы, партнёры). Префикс /v1/platform/, ключи bk_plt_*. Каталог кодов — deny by default (нужны catalog rules).
Для кого этот раздел
Для кого: IT маркетплейсов, аптечных сетей и партнёрских каналов продаж (например Ригла). Ключ bk_plt_* — только ваш каталог по правилам доступа (deny by default). Не видите настройки других площадок и внутренние данные проекта.
Логика работы с API
Жизненный цикл с точки зрения площадки: узнать о новых кодах (webhook или events/changes) → выдать покупателю (realize) → зафиксировать активацию (report-bulk). Основной метод синхронизации каталога — promo-codes/changes, не полный list.
Базовый URL
- Production:
https://api-external.promanta.ru - Локально:
http://localhost:7314
Аутентификация
Заголовок X-Api-Key: bk_plt_…. Platform id определяется ключом.
Ключ и webhook настраиваются в карточке площадки.
Формат запроса и ответа
Все методы — POST, JSON: { "meta": {}, "data": {} }. Ответ: success, data, meta (requestId, serverTime).
Методы по сценариям
0. Старт: профиль и webhook
Проверка ключа, catalog rules, статус webhook.
- Проверка API-ключа площадки —
POST /v1/platform/profile/get
1. Синхронизация каталога
Webhook incoming.completed или poll events/changes. Сводки — catalog/summary, метаданные партий — incoming/list.
- Список бизнес-событий (poll) —
POST /v1/platform/events/list - Новые поступления для площадки —
POST /v1/platform/incoming/list - Изменения в каталоге (delta-sync) —
POST /v1/platform/promo-codes/changes - Сводка каталога промокодов площадки —
POST /v1/platform/catalog/summary
2. Выдача промокода покупателю
Checkout: получить полный код → realize (привязка к площадке). Пакетные акции — realize-batch.
- Каталог промокодов для выдачи —
POST /v1/platform/promo-codes/list - Полный промокод перед выдаче клиенту —
POST /v1/platform/promo-codes/get - Реализация промокода на площадке —
POST /v1/platform/promo-codes/realize - Пакетная реализация промокодов —
POST /v1/platform/promo-codes/realize-batch
3. Погашение (активация)
После активации у покупателя — report-bulk (realized → redeemed).
- Пакетное погашение промокодов —
POST /v1/platform/usage/report-bulk
MCP
Те же операции доступны через MCP: /mcp/internal, /mcp/supplier, /mcp/platform с тем же ключом/JWT.
Пример запроса (smoke-test)
{
"meta": { "requestId": "smoke-001" },
"data": {}
}Пример ответа
{ "success": true, "data": { "platformId": "…", "name": "Ригла", "webhookConfigured": true, "catalogRulesCount": 3 } }cURL
curl -X POST "https://api-external.promanta.ru/v1/platform/profile/get" \
-H "Content-Type: application/json" \
-H "X-Api-Key: bk_plt_YOUR_KEY" \
-d '{"data": {}}'