TG-checkДокументация
REST API v1

TG-check API

Проверка телефонных номеров в Telegram с выгрузкой в XLSX и JSONL.

Базовый URLhttps://api.pro-checker.xyz

Ключ и первый запрос

  1. Получите ключ в боте

    В боте откройте Профиль → Запросить API. После одобрения заявки бот пришлёт ключ.

  2. Проверьте баланс

    В каждом запросе передавайте ключ из бота в заголовке Authorization: Bearer <API_KEY>.

    cURL
    curl -H "Authorization: Bearer <API_KEY>" "https://api.pro-checker.xyz/v1/balance"
    Python · httpx
    import httpx
    
    response = httpx.get(
        "https://api.pro-checker.xyz/v1/balance",
        headers={"Authorization": "Bearer <API_KEY>"},
        timeout=30,
    )
    response.raise_for_status()
    print(response.json())
    Пример ответа200 OK
    {
      "currency": "USD",
      "scale": 10000,
      "available_units": 12500,
      "request_id": "88024f94-ffac-46da-8830-49a20d8de744"
    }

    available_units / scale — остаток в долларах. В примере 12 500 / 10 000 = 1,25 USD.

Файл и стоимость

GET /v1/prices возвращает тарифы вашего кошелька и лимиты API.

cURL · тарифы и лимиты
curl -H "Authorization: Bearer <API_KEY>" "https://api.pro-checker.xyz/v1/prices"

Формат TXT

UTF-8, BOM допустим. Один российский номер на строку, 11 цифр с первой цифрой 7. API убирает пробелы по краям строки, пропускает пустые строки и оставляет первое вхождение каждого номера. Если в файле есть неверный номер, API отклоняет весь файл.

Лимиты

До 100 000 уникальных номеров и до 5 МиБ. Действующие лимиты указаны в limits.

API умножает ставку за номер на число уникальных номеров и округляет итог вверх до целой единицы баланса. Если в файле меньше 500 уникальных номеров, API рассчитывает стоимость за 500. По тарифу 0,55 USD за 1 000 номеров проверка 501 номера стоит 2 756 единиц баланса (0,2756 USD).

Создать проверку

POST /v1/checks принимает файл и тип проверки в форме multipart/form-data. Для новой проверки задайте новый Idempotency-Key, например UUID. В примере max_cost_units=3000 ограничивает стоимость проверки суммой 0,30 USD.

cURL
curl -H "Authorization: Bearer <API_KEY>" -H "Idempotency-Key: <IDEMPOTENCY_KEY>" -F "file=@numbers.txt;type=text/plain" -F "check_type=standard" -F "max_cost_units=3000" "https://api.pro-checker.xyz/v1/checks"
Python · httpx
import httpx

with open("numbers.txt", "rb") as source:
    response = httpx.post(
        "https://api.pro-checker.xyz/v1/checks",
        headers={
            "Authorization": "Bearer <API_KEY>",
            "Idempotency-Key": "<IDEMPOTENCY_KEY>",
        },
        files={"file": ("numbers.txt", source, "text/plain")},
        data={"check_type": "standard", "max_cost_units": "3000"},
        timeout=90,
    )
response.raise_for_status()
print(response.json())

Ответ 202 Accepted содержит check_id и status_url. На одном кошельке может быть только одна незавершённая проверка. Лимит общий для API и бота. API фиксирует цену при создании проверки и списывает средства после подтверждения старта проверки.

Если ответ на POST не пришёл, повторите запрос с тем же Idempotency-Key, файлом и параметрами. Если проверка уже создана, API вернёт её check_id.

Статус проверки

Подставьте check_id из ответа POST /v1/checks. Между запросами выдерживайте интервал из limits.poll_interval_seconds. Если Retry-After указывает более долгую паузу, дождитесь её окончания.

cURL
curl -H "Authorization: Bearer <API_KEY>" "https://api.pro-checker.xyz/v1/checks/<CHECK_ID>"
  • queued — проверка в очереди.
  • processing — идёт проверка. Ход обработки указан в counts.progress.
  • completed — проверка завершена. Для выгрузки используйте initial_export_id.
  • needs_review — обратитесь в поддержку и укажите check_id.
  • failed — проверка завершилась с ошибкой. Код ошибки указан в error.code, состояние оплаты — в billing_status.

Скачать результат

Первая выгрузка создаётся при завершении проверки. Подставьте initial_export_id вместо <EXPORT_ID>.

cURL · статус экспорта
curl -H "Authorization: Bearer <API_KEY>" "https://api.pro-checker.xyz/v1/exports/<EXPORT_ID>"

Пока выгрузка в статусе pending или preparing, опрашивайте её с тем же интервалом, что и проверку. При ready добавьте к базовому URL путь из files.jsonl.download_url или files.xlsx.download_url. Ссылка действует до expires_at.

cURL · скачать JSONL
curl --fail -H "Authorization: Bearer <API_KEY>" -o result.jsonl "https://api.pro-checker.xyz/v1/exports/<EXPORT_ID>/files/jsonl"

Поля JSONL и столбцы XLSX

Повторная выгрузка

Если срок скачивания истёк (expired или 410 export_expired), запросите новую выгрузку по тому же check_id. Задайте отдельный Idempotency-Key для запроса выгрузки. Ответ содержит export_id.

cURL
curl -X POST -H "Authorization: Bearer <API_KEY>" -H "Idempotency-Key: <EXPORT_REQUEST_KEY>" "https://api.pro-checker.xyz/v1/checks/<CHECK_ID>/exports"

Методы API

Параметры в URL принимает только GET /v1/checks. Идентификатор запроса передаётся в заголовке X-Request-ID.

GET /v1/balance Остаток кошелька

Доступ balance:read · Ответ 200 OK

available_units — доступный остаток в единицах баланса, целое неотрицательное число. currency всегда USD, scale — 10000. Пример ответа

GET /v1/prices Тарифы и лимиты

Доступ prices:read · Ответ 200 OK

В prices.standard и prices.full поле per_number_units — ставка за номер, например 6 или "5.5". Целая ставка передаётся числом, дробная — строкой. per_1000_units — ставка за 1 000 номеров, всегда целое число. Как и в ответе с балансом, currency содержит USD, а scale — 10000.

  • limits.min_numbers и limits.max_numbers — допустимое число уникальных номеров.
  • limits.min_billed_numbers — минимальный оплачиваемый объём, 500 номеров.
  • limits.max_input_bytes — максимальный размер файла в байтах.
  • limits.country — регион номеров, RU.
  • limits.poll_interval_seconds — минимальный интервал между запросами статуса проверки или выгрузки.
POST /v1/checks Создать проверку

Доступ checks:write · Ответ 202 Accepted

Idempotency-Key обязателен. Допустимо от 1 до 128 символов A–Z, a–z, 0–9, _ и -.

Поля multipart/form-data

  • file — один файл TXT. Имя с расширением .txt занимает до 255 байт в UTF-8. Для файла можно указать text/plain или application/octet-stream.
  • check_type — standard или full. В режиме full к базовым полям добавляются пол, возраст и признак заморозки аккаунта.
  • client_reference — идентификатор проверки в вашей системе. Необязательное поле, от 1 до 128 символов.
  • max_cost_units — необязательный предел стоимости в единицах баланса. Передаётся строкой из 1–13 десятичных цифр со значением от 0 до 1 000 000 000 000 включительно.

Имя файла и client_reference не могут содержать символы U+0000–U+001F. Лишние и повторяющиеся поля отклоняются. Максимальный размер всего тела запроса — 6 МиБ.

Ответ содержит объект проверки и request_id. Заголовок Location содержит тот же путь, что и status_url. Retry-After указывает паузу перед запросом статуса в секундах.

Объект проверки

  • check_id — UUID проверки. status_url — путь для запроса статуса.
  • check_type, filename, client_reference — выбранный режим, имя файла и идентификатор из запроса. Если client_reference не передан, API вернёт null.
  • counts содержит количество номеров на входе (input), уникальных (unique), повторов (duplicates), строк в результате (returned) и обработанных номеров (progress). Первые четыре значения могут быть null.
  • billed_count — оплачиваемое число номеров. rate_units и cost_units — ставка за номер и итоговая стоимость в единицах баланса. В billing_status возможны not_charged (списания не было), charged (средства списаны) и refunded (средства возвращены).
  • status — статус проверки. created_at и finished_at — время создания и завершения. initial_export_id — UUID первой выгрузки. При сбое error содержит поле code.

billed_count, finished_at, initial_export_id и error могут быть null.

GET /v1/checks История проверок

Доступ checks:read · Ответ 200 OK

limit задаёт размер страницы от 1 до 100 записей. По умолчанию возвращается до 50. Для следующей страницы передайте next_cursor из ответа как cursor. На последней странице next_cursor равен null.

items — массив объектов проверки. request_id относится ко всему ответу.

GET /v1/checks/{check_id} Статус проверки

Доступ checks:read · Ответ 200 OK

API возвращает объект проверки с текущими значениями полей и request_id.

POST /v1/checks/{check_id}/exports Запросить новую выгрузку

Доступ results:read · Ответ 202 Accepted

Запрос без тела. Укажите check_id проверки в статусе completed с доступным результатом и передайте Idempotency-Key. При повторе используйте тот же ключ.

Ответ содержит export_id, status_url и request_id. Если выгрузка этой проверки уже в очереди или готовится, API вернёт её export_id. Заголовок Location содержит путь запроса статуса, Retry-After — паузу перед опросом.

GET /v1/exports/{export_id} Статус выгрузки и файлы

Доступ results:read · Ответ 200 OK

В ответе указаны export_id, check_id и request_id.

  • pending — выгрузка в очереди.
  • preparing — файлы готовятся.
  • ready — файлы доступны для скачивания.
  • failed — не удалось подготовить выгрузку. Причина указана в error.code.
  • expired — срок скачивания истёк.

При ready поле expires_at указывает, до какого времени можно скачать результат. Поля files.xlsx и files.jsonl описывают файлы.

  • bytes — размер в байтах.
  • rows — число строк результата.
  • sha256 — контрольная сумма из 64 строчных шестнадцатеричных символов.
  • schema_version — версия формата, 1.
  • download_url — относительный путь для скачивания.
GET /v1/exports/{export_id}/files/{format} Скачать XLSX или JSONL

Доступ results:read · Ответ 200 OK с содержимым файла

Подставьте xlsx или jsonl вместо {format}. Оба файла содержат одни и те же строки результата.

JSONL · application/x-ndjson

Один объект на строку. Все значения, включая user_id, передаются строками. Отсутствующее значение представлено пустой строкой.

  • standard — phone, user_id, username, last_online, first_name, last_name, premium.
  • full — те же поля плюс gender, age и frozen.

XLSX · application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Данные находятся на листе Results. Столбцы идут в следующем порядке.

  • standard — Phone, UserID, Username, Last online, First name, Last name, Premium.
  • full — Phone, UserID, Username, First name, Last name, Gender, Age, Last online, Premium, Frozen.

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

Сначала проверьте HTTP-статус. Если в теле application/problem+json есть поле code, уточните причину по таблице. В кратком ответе есть только type, title и status. Для обращения в поддержку возьмите идентификатор из заголовка X-Request-ID или поля request_id, если оно есть.

В примере ошибка во второй строке TXT. Поле invalid_lines содержит до 20 номеров строк.

{
  "type": "urn:tg-check:problem:invalid_numbers",
  "title": "invalid numbers",
  "status": 422,
  "code": "invalid_numbers",
  "request_id": "00000000-0000-4000-8000-000000000001",
  "invalid_lines": [2]
}
HTTPcodeПричина и действие
400 или 401missing_headerПри 400 добавьте Idempotency-Key к POST. При 401 добавьте Authorization: Bearer <API_KEY>.
400duplicate_header, invalid_content_lengthУберите повторяющиеся заголовки. Проверьте Content-Length.
400invalid_idempotency_keyИсправьте формат Idempotency-Key.
400invalid_multipart, multipart_incompleteСформируйте форму multipart/form-data заново. Границы частей задаёт HTTP-клиент.
401invalid_api_keyПередайте действующий ключ после Bearer в заголовке Authorization.
403scope_deniedУ ключа нет права доступа, указанного в описании метода.
403network_deniedОбратитесь в поддержку и укажите request_id.
404not_foundПуть, идентификатор или формат не найден. Проверки и выгрузки видны только интеграции, которая создала проверку.
408upload_incompleteСервер не получил запрос целиком. Отправьте его повторно с тем же Idempotency-Key.
409idempotency_conflictЭтот ключ уже использован с другими данными. Для повтора восстановите исходный файл и параметры. Для новой операции задайте новый ключ.
409active_checkНа кошельке уже есть незавершённая проверка. Дождитесь её завершения.
409price_changedТариф изменился во время обработки запроса. Повторите запрос с тем же Idempotency-Key после паузы Retry-After.
409price_limit_exceededСтоимость выше max_cost_units. Сверьте предел с тарифом из GET /v1/prices.
409insufficient_balanceНа кошельке не хватает средств для этой проверки.
409check_not_completedВыгрузка доступна после completed. Запросите статус проверки.
409result_unavailableДля этой проверки нет доступного результата для выгрузки.
409export_not_readyЗапросите статус выгрузки. Скачивание доступно при ready.
410export_expiredСрок скачивания истёк. Запросите новую выгрузку по тому же check_id.
413body_too_large, file_too_largeТело запроса или файл превышает лимит. Уменьшите размер файла.
415content_encoding_unsupportedОтправьте тело без HTTP-сжатия.
415multipart_requiredПередайте файл и параметры в форме multipart/form-data.
415txt_requiredДля части file допустимы text/plain и application/octet-stream.
422query_parameters_unsupported, invalid_queryПараметры в URL принимает только GET /v1/checks. Для этого метода проверьте limit и cursor.
422invalid_cursorПередайте next_cursor из предыдущего ответа без изменений.
422invalid_fields, file_required, invalid_check_type, invalid_client_reference, invalid_max_cost, invalid_filenameСверьте поля формы с описанием POST /v1/checks.
422invalid_numbersИсправьте строки из invalid_lines и проверьте число уникальных номеров по limits.
422body_not_supportedУдалите тело запроса у POST /v1/checks/{check_id}/exports.
422invalid_requestПроверьте формат идентификатора и параметры запроса.
429poll_too_frequentУвеличьте интервал между запросами статуса до limits.poll_interval_seconds.
429rate_limitПревышена частота запросов. Повторите запрос после паузы Retry-After.
429daily_quotaДневная квота исчерпана. Повторите запрос после её обновления.
429upload_limit, export_limit, download_limitПревышен лимит одновременных загрузок, выгрузок или скачиваний. Дождитесь завершения одной из операций.
503artifact_missingФайл выгрузки недоступен. Повторите скачивание.
503Другой код или без кодаСервис временно недоступен. Повторите запрос позже. Если ошибка повторяется, передайте в поддержку идентификатор запроса.

При повторе учитывайте Retry-After, если он указан. Для POST используйте исходный Idempotency-Key и те же данные.