Comprobación individual en tiempo real

POST/v1/realtime/check/phone

Comprueba un número de forma síncrona. Una solicitud puede incluir varios productos en tiempo real; usa sus ID, no los slugs de productos por lotes.

Parámetros

Campo	Tipo	Requerido	Descripción
`identifier`	string	Sí	Un número E.164, por ejemplo +8613800138000.
`country`	string	No	Opcional para un E.164 completo; un número nacional requiere el código ISO de país correspondiente. — Códigos de país
`product_ids`	array	Sí	Lista de 1 a 10 ID de productos en tiempo real.

Elegir los productos a verificar

Los IDs de producto no se adivinan: léelos de GET /v1/products y toma el id de la entrada cuyo mode sea realtime. Los productos por lotes se direccionan por slug, así que un slug nunca funciona en este endpoint. La página de productos muestra los IDs en tiempo real con el prefijo # precisamente por esto.

Productos

Una llamada verifica un número contra hasta diez productos en tiempo real. Obtienes un único request_id, una entrada por producto en results y cada una se factura por separado, por lo que status puede devolver partial_succeeded. Más de diez IDs en una llamada se rechazan; la consola aplica el mismo límite.

Ejemplo de Respuesta

{
  "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
    }
  ]
}

Campos de la respuesta

Campo	Tipo	Descripción
`request_id`	string (UUID)	UUID que identifica este envío. Cítalo en las solicitudes de soporte.
`identifier`	string	El identificador que se verificó, devuelto tal cual.
`series`	string	`phone` o `email`.
`status`	string	`succeeded`, `partial_succeeded` o `failed`: se deriva de cuántos resultados se cobraron.
`request_status`	string	Estado interno del ciclo de vida de la solicitud.
`total_reserved`	number	Monto reservado antes de ejecutar las verificaciones.
`total_charged`	number	Total cobrado en todos los productos de la combinación.
`total_refunded`	number	Total reembolsado por los elementos que no se pudieron resolver.
`charged_amount`	number	Cargo neto. Siempre es igual a `total_charged`.
`refunded_amount`	number	Reembolso neto. Siempre es igual a `total_refunded`.
`replayed`	boolean	`true` cuando una repetición del Idempotency-Key devolvió un resultado almacenado.
`results`	array	Una entrada por cada producto solicitado, en el orden en que se solicitaron los productos.

`results[]`

Campo	Tipo	Descripción
`product_id`	integer	ID del producto de tiempo real del catálogo.
`product`	string	Slug del producto al que resuelve ese ID.
`result`	string	`valid`, `invalid` o `unknown`: si el identificador está registrado.
`cached`	boolean	`true` cuando el veredicto provino de la caché. Un acierto de caché igualmente se cobra.
`billing_status`	string	`charged` o `refunded`.
`charged_amount`	number	Importe cobrado por este producto.
`refunded_amount`	number	Importe reembolsado por este producto.
`checked_at`	string (ISO 8601)	Cuándo se produjo el veredicto, en UTC.
`error_code`	string \| null	Por qué no se pudo resolver el elemento, o `null` cuando tuvo éxito.

Ejemplo de 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]}'

Facturación y semántica

Cada producto usa el precio por consulta fijado para la solicitud, incluso con caché. Solo valid e invalid se cobran; unknown, los tiempos de espera y los elementos ocupados se reembolsan.

Un combo parcialmente correcto devuelve HTTP 200 con status=partial_succeeded; si todo falla, status=failed. Revisa billing_status y error_code de cada elemento.

Idempotency-Key admite hasta 191 bytes y se aplica por usuario. Tras un timeout o error 500, repite el contenido original con la misma clave. Los resultados se conservan 30 días de forma predeterminada.

error_code identifica fallos del proveedor, capacidad, plazo, caché o protección de concurrencia. Los elementos fallidos no se cobran.

Error

Endpoints	Significado / acción
`400`	Corrige el número, los productos o la clave; no hubo prepago.
`401`	Comprueba la clave, la cuenta y el acceso en tiempo real; no hubo prepago.
`402`	Saldo insuficiente; no se ejecuta ningún elemento.
`409`	Respeta Retry-After; una carga distinta no puede reutilizar la clave.
`429`	Espera el tiempo indicado en Retry-After; no hubo prepago.
`500`	El resultado es incierto. Repite con la clave original y no envíes otra clave.
`503`	La ruta, la caché o el limitador no están disponibles; inténtalo más tarde.