Импорт сделок в ГЦК

Метод создает новые сделки ГЦК из списка российских телефонных номеров. Импорт выполняется как асинхронная операция.

Требования

• JWT содержит scope cabinet:deals:write;

• пользователь имеет право управлять сделками выбранного кабинета;

• cabinetId получен через External API;

• запрос содержит reason и уникальный Idempotency-Key.

Нормализация номеров

Запрос принимает от 1 до 1000 строк. Форматирующие символы игнорируются, дубликаты удаляются.

Поддерживаются десять цифр или одиннадцать цифр с первой 7 либо 8. Остальные значения отбрасываются. После нормализации должен остаться хотя бы один номер.

inputPhones показывает число строк во входном массиве. acceptedPhones показывает число корректных уникальных номеров после нормализации.

1. Запустите импорт

Замените 123456789 и телефоны на значения вашей тестовой среды. Не запускайте пример с фиктивными номерами в production-кабинете.

curl --include --request POST \
  'https://api.alitos.io/v1/external/gck/cabinets/123456789/deals/import-jobs' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
    "reason": "Импорт лидов из подтвержденной формы",
    "phones": [
      "+7 900 123-45-67",
      "8 (901) 234-56-78"
    ]
  }'

Создайте IDEMPOTENCY_KEY один раз для логической операции. Повтор потерянного HTTP ответа должен использовать тот же key и тот же payload.

PowerShell:

$env:IDEMPOTENCY_KEY = [guid]::NewGuid().ToString()

Bash с Node.js:

export IDEMPOTENCY_KEY="$(node -p 'crypto.randomUUID()')"

2. Прочитайте ответ 202 Accepted

HTTP/1.1 202 Accepted
Location: /v1/external/operations/71b8b090-1d0a-4aa4-b1f0-29ebc6b25b42
Retry-After: 2

{
  "operationId": "71b8b090-1d0a-4aa4-b1f0-29ebc6b25b42",
  "status": "queued",
  "statusUrl": "/v1/external/operations/71b8b090-1d0a-4aa4-b1f0-29ebc6b25b42",
  "created": true
}

created: false означает, что тот же идемпотентный запрос уже создал операцию.

3. Дождитесь завершения

curl \
  'https://api.alitos.io/v1/external/operations/71b8b090-1d0a-4aa4-b1f0-29ebc6b25b42' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Соблюдайте Retry-After и добавляйте небольшой jitter. Не опрашивайте операцию чаще одного раза в две секунды.

Статусы: queued, running, succeeded, failed.

Успешный результат

{
  "operationId": "71b8b090-1d0a-4aa4-b1f0-29ebc6b25b42",
  "operationKind": "deals.import",
  "status": "succeeded",
  "cabinetId": "123456789",
  "idempotencyKey": "0d88ec7d-d184-4f31-aa7c-9163391e2227",
  "reason": "Импорт лидов из подтвержденной формы",
  "progress": {
    "percent": 100,
    "stage": "completed",
    "completedItems": 2,
    "totalItems": 2
  },
  "result": {
    "cabinetId": "123456789",
    "inputPhones": 2,
    "acceptedPhones": 2,
    "importedDeals": 2,
    "failedPhones": 0,
    "verified": true,
    "importId": "48152"
  },
  "error": null,
  "createdAt": "2026-08-09T12:00:00Z",
  "updatedAt": "2026-08-09T12:00:08Z",
  "expiresAt": "2026-08-16T12:00:00Z"
}

failedPhones > 0 означает частичный результат на стороне ГЦК. Операция может иметь статус succeeded, потому что импорт завершился и итог был проверен.

Телефоны не возвращаются в summary и хранятся в очереди только в зашифрованном виде.

Ошибки и повторные запросы

Alitos ограничивает запрос 1000 элементами и не публикует счетчик внешней недельной квоты ГЦК. Если ГЦК отклоняет commit по своей политике, операция завершается ошибкой, которую нужно обрабатывать как upstream-отказ.

Операция и ее результат хранятся семь дней. Новый JWT из того же ключа подходит для polling, если содержит исходный scope.