К содержимому

Импорт сделок в Архив

Обновлено

Импорт создаёт новые сделки из списка российских телефонных номеров. Это может потребоваться для передачи номеров на обработку КЦ. Он выполняется в фоне: запустите операцию, дождитесь завершения и проверьте итоговые счётчики. Изменение статусов существующих сделок — отдельный сценарий Alitos MCP; REST-импорт телефонов статусы не назначает.

Подготовьте данные и доступ

Нужны JWT со scope cabinet:deals:write и право пользователя управлять сделками выбранного кабинета. Для предварительного поиска кабинета через API дополнительно нужен cabinet:read. Получение JWT описано в авторизации.

Примеры используют Bash и curl. ALITOS_EXTERNAL_JWT — полученный JWT, CABINET_ID — точный cabinetId, выбранный при поиске кабинетов.

Передайте в phones от 1 до 1000 строк длиной 10–32 символа. Форматирующие символы игнорируются, дубликаты удаляются:

Вход

Нормализованное значение

9001234567

79001234567

8 (900) 123-45-67

79001234567

+7 900 123-45-67

79001234567

Поддерживаются десять цифр или одиннадцать с первой 7 либо 8. Некорректные номера отбрасываются; после нормализации должен остаться хотя бы один корректный номер. inputPhones — число входных строк, acceptedPhones — число корректных уникальных номеров.

1. Создайте ключ операции

Сформируйте Idempotency-Key один раз для нового импорта и сохраните его. Рекомендуемый формат — UUID. Следующая команда требует Node.js; если ключ формирует ваша интеграция, используйте его вместо этой команды:

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

При повторе не выполняйте генерацию заново. Повторный запрос должен сохранить тот же ключ, тело и reason — причину импорта.

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

Этот запрос создаёт сделки. Замените телефоны в примере своими тестовыми данными и используйте тестовый кабинет; не отправляйте фиктивные номера в production.

curl --include --request POST \
  "https://api.alitos.io/v1/external/gck/cabinets/${CABINET_ID}/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"]
  }'

Ответ 202 Accepted содержит заголовки Location, Retry-After и тело:

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

Сохраните свой operationId в OPERATION_ID. created: false означает, что точный повтор запроса вернул уже существующую операцию.

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

curl --include \
  "https://api.alitos.io/v1/external/operations/${OPERATION_ID}?view=compact" \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

При queued или running продолжайте ожидание. Соблюдайте Retry-After, добавляйте небольшую случайную задержку и не опрашивайте чаще раза в две секунды. При failed прочитайте error: HTTP 200 при опросе не означает успешный импорт.

4. Проверьте результат

После succeeded один раз запросите итог:

curl \
  "https://api.alitos.io/v1/external/operations/${OPERATION_ID}?view=compact&includeSummary=true" \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Пример объекта result внутри ответа:

{
  "cabinetId": "123456789",
  "inputPhones": 2,
  "acceptedPhones": 2,
  "importedDeals": 2,
  "failedPhones": 0,
  "verified": true,
  "importId": "48152"
}

Проверьте importedDeals, failedPhones и verified. При failedPhones > 0 результат частичный, хотя операция может иметь статус succeeded: импорт завершён, а его итог проверен. Импорт не создаёт страниц строк результата. Телефоны в итоговом объекте не возвращаются и хранятся в очереди только в зашифрованном виде.

Ошибки и повторы

При phones_required передайте хотя бы один корректный номер; при phones_limit_exceeded уменьшите набор. Каждый запрос в любом случае должен содержать не более 1000 входных строк.

Если ответ запуска потерян, повторите тот же POST с тем же ключом и телом. При временной HTTP-ошибке учитывайте retryable и Retry-After. Если сама операция уже завершилась с status: "failed", повтор с тем же ключом вернёт её снова, а не запустит новый импорт. Разберите error.code и фактический результат. При ambiguous_upstream_outcome сначала проверьте сделки в ГЦК; автоматически создавать новый ключ нельзя.

Счётчик недельной квоты ГЦК не публикуется. Если ГЦК отклоняет импорт по своей политике, операция завершается ошибкой. Остальные коды и действия клиента — в правилах операций и ошибок. Операция и результат хранятся семь дней. Для опроса подходит новый JWT из того же ключа с исходным scope, пока сохраняются права пользователя.