Загрузка поставки промокодов (JSON)

Альтернатива файловому контуру (upload-url → import): ERP отправляет коды сразу в JSON.

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

Когда поставщику неудобно выгружать Excel — коды уже есть в ERP как массив. Метод создаёт (или использует) поступление и вставляет коды на склад PROMANTA синхронно. При finalize: true статус → completed и срабатывает webhook incoming.completed.

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

Одна поставка ≤ 500 кодов — один запрос без incomingId (создастся draft).
Больше 500 — сначала incoming/create, затем несколько bulk-create с finalize: false, последний — с finalize: true и/или totalExpected.
Не нужен signed URL и разбор маски файла.

Эндпоинт

POST /v1/supplier/incoming/codes/bulk-create

Аутентификация: X-Api-Key (префикс bk_sup_). supplierId / projectId в body не передаются.

Scope: supplier:incoming:write

Idempotency-Key: обязателен (заголовок).

Поля data

codes (обяз.) — массив строк или объектов, max 500
incomingId — UUID поступления; если нет — создаётся draft
documentNumber, documentDate, importMaskId, productId, notes — при автосоздании; productId только свой товар
options.finalize — default true
options.totalExpected — ожидаемый итог при загрузке чанками

Элемент codes: строка "QUEEN14-XX" или объект с code / codeDisplay / codeNormalized, опционально validFrom, validUntil, productName, productLine, designVariant, codeType, productId, externalRef, rawMetadata.

Нормализация: trim, uppercase, без пробелов (как при file import). Дубликаты по code_hash пропускаются.

Пример запроса (one-shot)

{
  "meta": { "requestId": "sup-json-001" },
  "data": {
    "documentNumber": "PM-2026-07-API-001",
    "documentDate": "2026-07-14",
    "codes": [
      "QUEEN14-48AMU",
      { "code": "QUEEN14-49BNX", "validUntil": "2026-12-31", "productLine": "QUEEN14" }
    ],
    "options": { "finalize": true }
  }
}

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

{
  "success": true,
  "data": {
    "incomingId": "f47ac10b-…",
    "createdIncoming": true,
    "status": "completed",
    "batch": { "submitted": 2, "valid": 2, "inserted": 2, "duplicates": 0, "insertedAvailable": 2, "insertedExpired": 0 },
    "counters": { "totalRows": 2, "insertedRows": 2, "insertedAvailable": 2, "duplicateRows": 0 },
    "finalized": true
  }
}

Ошибки

VALIDATION_ERROR — пустой/слишком большой codes, нет маски при автосоздании
INVALID_STATE — поступление уже completed/cancelled
RESOURCE_NOT_FOUND — чужой или несуществующий incomingId
RATE_LIMIT_EXCEEDED (429)

cURL

curl -X POST "https://api-external.promanta.ru/v1/supplier/incoming/codes/bulk-create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bk_sup_YOUR_KEY" \
  -H "Idempotency-Key: bulk-json-001" \
  -d '{"data":{"documentNumber":"PM-API-1","codes":["QUEEN14-48AMU"],"options":{"finalize":true}}}'