Пакетная реализация промокодов

Массовая выдача кодов (email-рассылка, корпоративная акция).

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

Массовая выдача кодов (email-рассылка, корпоративная акция). До 100 кодов за запрос, частичный успех допустим.

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

B2B рассылка, промо-кампании с фиксированным списком codeId.

Эндпоинт

POST /v1/platform/promo-codes/realize-batch

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

Scope: platform:codes:realize

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

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

{
  "meta": { "requestId": "optional-uuid" },
  "data": { "items": [{ "codeId": "uuid-1", "externalRef": "order-1" }], "batchRef": "campaign-summer-2026" }
}

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

{
  "success": true,
  "data": {
    "summary": { "total": 1, "accepted": 1, "rejected": 0 },
    "results": [{ "codeId": "uuid-1", "success": true, "status": "realized" }]
  }
}

Ошибки

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

cURL

curl -X POST "https://api-external.promanta.ru/v1/platform/promo-codes/realize-batch" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-001" \
  -d '{"data": { "items": [{ "codeId": "uuid-1", "externalRef": "order-1" }], "batchRef": "campaign-summer-2026" }}'