TG-check API
Проверка телефонных номеров в Telegram с выгрузкой в XLSX и JSONL.
https://api.pro-checker.xyzКлюч и первый запрос
Получите ключ в боте
В боте откройте Профиль → Запросить API. После одобрения заявки бот пришлёт ключ.
Проверьте баланс
В каждом запросе передавайте ключ из бота в заголовке
Authorization: Bearer <API_KEY>.cURLcurl -H "Authorization: Bearer <API_KEY>" "https://api.pro-checker.xyz/v1/balance"Python · httpximport 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 -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 -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"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 -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 -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 --fail -H "Authorization: Bearer <API_KEY>" -o result.jsonl "https://api.pro-checker.xyz/v1/exports/<EXPORT_ID>/files/jsonl"Повторная выгрузка
Если срок скачивания истёк (expired или 410 export_expired), запросите новую выгрузку по тому же check_id. Задайте отдельный Idempotency-Key для запроса выгрузки. Ответ содержит export_id.
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]
}
| HTTP | code | Причина и действие |
|---|---|---|
| 400 или 401 | missing_header | При 400 добавьте Idempotency-Key к POST. При 401 добавьте Authorization: Bearer <API_KEY>. |
| 400 | duplicate_header, invalid_content_length | Уберите повторяющиеся заголовки. Проверьте Content-Length. |
| 400 | invalid_idempotency_key | Исправьте формат Idempotency-Key. |
| 400 | invalid_multipart, multipart_incomplete | Сформируйте форму multipart/form-data заново. Границы частей задаёт HTTP-клиент. |
| 401 | invalid_api_key | Передайте действующий ключ после Bearer в заголовке Authorization. |
| 403 | scope_denied | У ключа нет права доступа, указанного в описании метода. |
| 403 | network_denied | Обратитесь в поддержку и укажите request_id. |
| 404 | not_found | Путь, идентификатор или формат не найден. Проверки и выгрузки видны только интеграции, которая создала проверку. |
| 408 | upload_incomplete | Сервер не получил запрос целиком. Отправьте его повторно с тем же Idempotency-Key. |
| 409 | idempotency_conflict | Этот ключ уже использован с другими данными. Для повтора восстановите исходный файл и параметры. Для новой операции задайте новый ключ. |
| 409 | active_check | На кошельке уже есть незавершённая проверка. Дождитесь её завершения. |
| 409 | price_changed | Тариф изменился во время обработки запроса. Повторите запрос с тем же Idempotency-Key после паузы Retry-After. |
| 409 | price_limit_exceeded | Стоимость выше max_cost_units. Сверьте предел с тарифом из GET /v1/prices. |
| 409 | insufficient_balance | На кошельке не хватает средств для этой проверки. |
| 409 | check_not_completed | Выгрузка доступна после completed. Запросите статус проверки. |
| 409 | result_unavailable | Для этой проверки нет доступного результата для выгрузки. |
| 409 | export_not_ready | Запросите статус выгрузки. Скачивание доступно при ready. |
| 410 | export_expired | Срок скачивания истёк. Запросите новую выгрузку по тому же check_id. |
| 413 | body_too_large, file_too_large | Тело запроса или файл превышает лимит. Уменьшите размер файла. |
| 415 | content_encoding_unsupported | Отправьте тело без HTTP-сжатия. |
| 415 | multipart_required | Передайте файл и параметры в форме multipart/form-data. |
| 415 | txt_required | Для части file допустимы text/plain и application/octet-stream. |
| 422 | query_parameters_unsupported, invalid_query | Параметры в URL принимает только GET /v1/checks. Для этого метода проверьте limit и cursor. |
| 422 | invalid_cursor | Передайте next_cursor из предыдущего ответа без изменений. |
| 422 | invalid_fields, file_required, invalid_check_type, invalid_client_reference, invalid_max_cost, invalid_filename | Сверьте поля формы с описанием POST /v1/checks. |
| 422 | invalid_numbers | Исправьте строки из invalid_lines и проверьте число уникальных номеров по limits. |
| 422 | body_not_supported | Удалите тело запроса у POST /v1/checks/{check_id}/exports. |
| 422 | invalid_request | Проверьте формат идентификатора и параметры запроса. |
| 429 | poll_too_frequent | Увеличьте интервал между запросами статуса до limits.poll_interval_seconds. |
| 429 | rate_limit | Превышена частота запросов. Повторите запрос после паузы Retry-After. |
| 429 | daily_quota | Дневная квота исчерпана. Повторите запрос после её обновления. |
| 429 | upload_limit, export_limit, download_limit | Превышен лимит одновременных загрузок, выгрузок или скачиваний. Дождитесь завершения одной из операций. |
| 503 | artifact_missing | Файл выгрузки недоступен. Повторите скачивание. |
| 503 | Другой код или без кода | Сервис временно недоступен. Повторите запрос позже. Если ошибка повторяется, передайте в поддержку идентификатор запроса. |
При повторе учитывайте Retry-After, если он указан. Для POST используйте исходный Idempotency-Key и те же данные.