Пакетное сообщение об активации кодов

Поставщик сообщает PROMANTA: «покупатель активировал код у нас» → статус redeemed.

Зачем нужен метод

Поставщик сообщает PROMANTA: «покупатель активировал код у нас» → статус redeemed. Обычно nightly файл из ERP или webhook из биллинга.

Когда использовать

Раз в сутки после закрытия активаций; до 1000 строк за запрос; Idempotency-Key обязателен.

Эндпоинт

POST /v1/supplier/usage/report-bulk

Аутентификация: API-ключ в заголовке X-Api-Key (префикс bk_sup_). projectId и actor id в body не передаются — берутся из ключа.

Scope: supplier:usage:write

Idempotency-Key: обязателен (заголовок). Повтор с тем же ключом вернёт кэшированный ответ.

Пример запроса

{
  "meta": { "requestId": "optional-uuid" },
  "data": {
  "items": [
    { "codeNormalized": "queen14-48amu", "redeemedAt": "2026-07-13T09:30:00Z", "externalRef": "act-998877" }
  ],
  "options": { "allowDirectRedeemFromAvailable": false }
}
}

Пример ответа

{
  "success": true,
  "data": {
    "summary": { "total": 1, "accepted": 1, "rejected": 0, "alreadyRedeemed": 0 },
    "results": [
      { "codeNormalized": "queen14-48amu", "success": true, "newStatus": "redeemed" }
    ]
  }
}

Ошибки

UNAUTHORIZED / ACCESS_DENIED — нет доступа
VALIDATION_ERROR — некорректное тело
NOT_FOUND — сущность не найдена
RATE_LIMIT_EXCEEDED (429) — превышен лимит

cURL

curl -X POST "https://api-external.promanta.ru/v1/supplier/usage/report-bulk" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-001" \
  -d '{"data": {   "items": [     { "codeNormalized": "queen14-48amu", "redeemedAt": "2026-07-13T09:30:00Z", "externalRef": "act-998877" }   ],   "options": { "allowDirectRedeemFromAvailable": false } }}'