Документация API

Подключение API

1. Попросите поддержку открыть для вас аккаунт.
2. Сообщите поддержке нужные услуги, ваш аккаунт и исходящие IP ваших серверов.
3. После этого мы выдадим API-ключ и полное руководство по интеграции. Ключи действуют от 1 до 730 дней, к каждому ключу можно привязать до 32 исходящих IP.

Основные правила

Аутентификация

Передавайте Authorization: Bearer <API-ключ> в каждом запросе

User-Agent

Обязателен. Запросы без него блокирует Cloudflare (error 1010)

Формат

Запросы и ответы в JSON, кодировка UTF-8, кроме загрузки файлов

Время

Временные метки UTC Unix в миллисекундах

Суммы

До восьми знаков после запятой. Используйте десятичный тип и не округляйте до двух знаков

Порядок интеграции

1. Получите список услуг и проверьте баланс. Сохраните нужный productId.
2. Прочитайте заявление об использовании данных и примите его, если ещё не сделали этого.
3. Загрузите файл с номерами и сохраните полученный fileId.
4. Получите расчёт стоимости по productId и fileId. Проверьте количество, цену за единицу и итоговую сумму.
5. Создайте и сохраните ключ идемпотентности, затем оформите заказ. Сумма будет списана с баланса.
6. Настройте вебхук для уведомлений о смене статуса и каждые 5–10 минут сверяйтесь через updatedSince, чтобы ничего не пропустить.
7. Когда заказ завершится, получите список файлов результатов, скачайте каждый и проверьте его sha256. Неуспешные файлы тоже скачайте.

Пример на curl

Замените плейсхолдеры реальными значениями. Полный список параметров расчёта и заказа — в руководстве, которое вы получите вместе с доступом.

1. Укажите ключ и получите список услуг

   Копировать

   export CHECKIM_TOKEN='замените на API-ключ от поддержки'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. Загрузите файл с номерами

   Копировать

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. Получите расчёт стоимости

   Копировать

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. Оформите заказ

   Копировать

   # Списывает средства с баланса. При повторной попытке не меняйте ключ идемпотентности и тело запроса.
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. Получите заказ или сверьтесь по времени изменения

   Копировать

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. Получите список результатов, скачайте их и проверьте sha256

   Копировать

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

Эндпоинты

Список заказов и сверка

• Заказы выводятся от новых к старым. Если на странице есть nextCursor, передайте его как cursor, чтобы получить следующую; постраничный вывод по курсору не пропускает и не повторяет заказы, даже когда появляются новые.
• Фильтруйте по status и времени создания (createdFrom, createdTo, миллисекунды UTC) или найдите заказ по clientOrderId.
• updatedSince возвращает только заказы, статус которых изменился после этого момента, от самого раннего изменения. Регулярно запрашивайте его — тогда пропущенный вебхук не приведёт к потере статуса.

Скачивание результатов

• У каждого файла в списке результатов есть sha256. ETag при скачивании — то же значение, сверьте его после загрузки.
• Запросы с Range позволяют докачать файл. Сначала убедитесь, что sha256 не изменился; если изменился, файл пересобран и его нужно скачать целиком заново.
• Если у вас уже есть полный файл, отправьте If-None-Match: при отсутствии изменений вернётся 304 без тела.
• Для крупных заказов с выдачей частями готовые части появляются в списке ещё во время выполнения; итоговый файл после завершения — основной.
• В услугах с аватарами (расширенная проверка и проверка пола и возраста в Telegram и WhatsApp) столбец avatar в CSV результата содержит подписанную ссылку на изображение, которую можно открыть прямым GET-запросом в течение срока хранения результатов (без заголовка Authorization; поддерживается If-None-Match).

Вебхуки

• Когда меняется статус заказа, оформленного через API, мы отправляем событие методом POST на ваш HTTPS-адрес. Нужно право webhook:manage.
• Каждое событие содержит заголовок CheckIM-Signature (t=метка времени,v1=подпись). Проверяйте его через HMAC-SHA256 от «t.исходное тело запроса» с вашим секретом подписи.
• Любой ответ 2xx считается доставкой; при ошибке делается 9 повторных попыток примерно за 2 дня. Одно событие может прийти несколько раз, поэтому убирайте дубли по его id.
• Запросы приходят с фиксированного IP 34.21.195.36, можно разрешить только его.

Статусы заказа

Лимиты и примечания

• По умолчанию не более 1 200 запросов в минуту с одного исходящего IP, 240 — на аккаунт и 120 — на ключ. Заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset показывают, сколько запросов осталось в текущей минуте.
• Расчёт стоимости и загрузка выполняются долго, поэтому на аккаунт одновременно допускается не более 3 таких запросов. Остальные получают 429 TOO_MANY_CONCURRENT_REQUESTS.
• При ответе 429 или 503 подождите столько секунд, сколько указано в Retry-After, и повторите тот же запрос.
• Тестовой среды нет. Каждый заказ оплачивается по-настоящему.
• Тайм-аут при опросе не означает, что заказ не оформлен. Прежде чем заказывать повторно, найдите заказ по orderId или clientOrderId.

Частые ошибки

Ошибки содержат code, requestId, message и необязательное detail.field. Обрабатывайте их по code; message приходит на одном из 9 языков согласно Accept-Language и предназначено только для показа.