Проверка одного номера в реальном времени

POST/v1/realtime/check/phone

Синхронная проверка одного номера. В запросе можно выбрать несколько продуктов реального времени по ID; slug пакетных продуктов не используется.

Параметры

Поле	Тип	Обязательно	Описание
`identifier`	string	Да	Один номер в формате E.164, например +8613800138000.
`country`	string	Нет	Для полного E.164 необязательно; для национального номера нужен соответствующий ISO-код страны. — Коды стран
`product_ids`	array	Да	Массив из 1–10 ID продуктов реального времени.

Выбор продуктов для проверки

Идентификаторы продуктов не угадывают: возьмите id записи с mode = realtime из GET /v1/products. Пакетные продукты адресуются по slug, поэтому slug на этой ручке никогда не сработает. В списке продуктов идентификаторы реального времени показаны с префиксом # именно поэтому.

Продукты

Один запрос проверяет один номер по десяти продуктам реального времени. Вы получите один request_id, по одной записи на продукт в results, и каждая тарифицируется отдельно, поэтому status может вернуть partial_succeeded. Больше десяти идентификаторов в запросе отклоняется; в консоли тот же лимит.

Пример ответа

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

Поля ответа

Поле	Тип	Описание
`request_id`	string (UUID)	UUID, идентифицирующий эту отправку. Указывайте его в обращениях в поддержку.
`identifier`	string	Идентификатор, который проверялся, возвращённый в ответе.
`series`	string	`phone` или `email`.
`status`	string	`succeeded`, `partial_succeeded` или `failed` — зависит от того, сколько результатов было списано.
`request_status`	string	Внутреннее состояние жизненного цикла запроса.
`total_reserved`	number	Сумма, зарезервированная до выполнения проверок.
`total_charged`	number	Всего списано по всем продуктам в комбинации.
`total_refunded`	number	Всего возвращено за позиции, которые не удалось обработать.
`charged_amount`	number	Итоговое списание. Всегда равно `total_charged`.
`refunded_amount`	number	Итоговый возврат. Всегда равно `total_refunded`.
`replayed`	boolean	`true`, если повтор с Idempotency-Key вернул сохранённый результат.
`results`	array	По одной записи на каждый запрошенный продукт, в порядке запроса продуктов.

`results[]`

Поле	Тип	Описание
`product_id`	integer	ID realtime-продукта из каталога.
`product`	string	Slug продукта, которому соответствует этот ID.
`result`	string	`valid`, `invalid` или `unknown` — зарегистрирован ли идентификатор.
`cached`	boolean	`true`, если вердикт взят из кеша. Попадание в кеш всё равно списывается.
`billing_status`	string	`charged` или `refunded`.
`charged_amount`	number	Сумма, списанная за этот продукт.
`refunded_amount`	number	Сумма, возвращённая за этот продукт.
`checked_at`	string (ISO 8601)	Когда был получен вердикт, в UTC.
`error_code`	string \| null	Причина, по которой позицию не удалось обработать, или `null` при успехе.

Пример cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50]}'

Биллинг и семантика

Каждый продукт использует зафиксированную цену за проверку, включая попадание в кэш. valid и invalid оплачиваются; unknown, тайм-аут и занятые элементы возвращаются.

Частично успешная комбинация возвращает HTTP 200 и status=partial_succeeded; при полном сбое — status=failed. Проверяйте billing_status и error_code каждого элемента.

Idempotency-Key ограничен 191 байтом и действует для пользователя. После тайм-аута или 500 повторите исходные данные с исходным ключом. Результаты хранятся 30 дней по умолчанию.

error_code указывает на сбой провайдера, лимита канала, срока, кэша или защиты конкуренции. Ошибочные элементы не оплачиваются.

Ошибка

Эндпоинты	Значение / действие
`400`	Исправьте номер, продукты или ключ; предоплаты не было.
`401`	Проверьте ключ, состояние аккаунта и доступ; предоплаты не было.
`402`	Недостаточно средств; комбинация не запускается.
`409`	Повторите после Retry-After; другой запрос не может использовать тот же ключ.
`429`	Подождите время Retry-After; предоплаты не было.
`500`	Результат неясен. Повторите с исходным ключом, не создавая новый.
`503`	Маршрут, кэш или лимитер недоступен; повторите позже.