Documentación API

Autenticación

Todos los endpoints requieren una clave API en el header. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

Tu clave tiene 51 caracteres: el prefijo zn_ seguido de 48 caracteres aleatorios. Las claves emitidas anteriormente con el prefijo ck_ siguen siendo válidas.

Tu clave API está disponible en la Consola, dentro de «API Center». La clave en texto plano solo se muestra una vez al crearla; guárdala de inmediato.

Formato de Respuesta

Todos los endpoints devuelven JSON.

Ejemplo de respuesta en tiempo real

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

Ejemplo de respuesta por lotes

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

Consultar Saldo

Devuelve el saldo USD actual.

Ejemplo de Respuesta

json

{ "balance": "5.230000" }

GET /v1/products

Productos

Catálogo público de productos; no se necesita una clave API. Devuelve los productos activos en tiempo real y por lotes, sus series y las cantidades mínimas. Léalo antes de enviar una solicitud.

Ejemplo de Respuesta

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

Detalles de la clave API

Devuelve los metadatos de la clave API de la cuenta autenticada. La clave en texto plano nunca se devuelve.

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

La clave en texto plano se muestra una sola vez al crearla o rotarla; este endpoint solo devuelve un valor enmascarado.

Códigos de Error

En caso de error revisa el código HTTP y el campo message.

Cuerpo de error

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

Los errores de negocio siempre devuelven un code legible por máquina para que pueda ramificar programáticamente. Los parámetros inválidos (validación) y las rutas desconocidas devuelven el formato estándar de Laravel: { "message": "...", "errors": { ... } }. Valide las entradas antes de enviarlas.

Error

code	HTTP	Descripción
unauthorized	401	Falta la clave de API, no es válida o está inactiva.
account_banned	403	Cuenta suspendida. Contacte con soporte.
invalid_realtime_request	400	Solicitud en tiempo real malformada (p. ej., número sin prefijo internacional + cuando se omite country).
idempotency_key_required	400	Las solicitudes en tiempo real requieren el encabezado Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key inválido: 1-128 caracteres de letras, dígitos y . _ : -
idempotency_conflict	409	La misma Idempotency-Key se usó con un contenido de solicitud diferente.
request_in_progress	409	Una solicitud en tiempo real idéntica sigue procesándose. Reintente en breve (Retry-After: 1).
empty_input	422	El archivo subido no contiene filas utilizables.
product_not_found	422	El slug de producto enviado no existe o está inactivo.
product_mode_not_supported	422	Este endpoint no acepta este modo de producto (los productos en tiempo real no van a endpoints masivos).
invalid_country	422	El producto no admite el país enviado.
too_few_numbers	422	El envío está por debajo del mínimo del producto.
too_many_numbers	422	El envío supera el máximo de la plataforma.
insufficient_balance	402	Saldo insuficiente. Recargue y reintente.
realtime_disabled	403	La detección en tiempo real no está habilitada para esta cuenta.
realtime_rate_limited	429	Límite de solicitudes en tiempo real superado. Respete retry_after.
product_pricing_unavailable	503	El precio de este producto aún no está configurado. Contacte con soporte.
detection_capacity_unavailable	503	No hay capacidad de detección disponible ahora mismo. Reintente más tarde.
realtime_route_unavailable	503	No hay ruta en tiempo real disponible. Reintente más tarde.
realtime_fact_cache_unavailable	503	Una dependencia en tiempo real no está disponible temporalmente. Reintente más tarde.
realtime_rate_limiter_unavailable	503	El limitador de solicitudes no está disponible temporalmente. Reintente más tarde.
not_found	404	task_id no existe o pertenece a otra cuenta.
result_not_ready	422	La tarea no ha terminado o todavía no se ha generado su archivo de resultados.
result_expired	404	El archivo de resultados ha caducado, falta o no está disponible.
validation_failed	422	Verifique campos obligatorios, formato de números y tipo de archivo.
internal_error	500	Error interno del servidor. Es seguro reintentar con la misma Idempotency-Key.

Límites de solicitudes

Las solicitudes a la API se limitan por clave de API y por grupo de endpoints:

Endpoints	Límite
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 solicitudes / minuto por clave de API (120 / minuto por IP)
Rutas: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 solicitudes / minuto por clave de API (30 / minuto por IP)
Rutas: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket por clave de API: ráfaga 60, recarga 1/s (≈60 / minuto sostenido); por cuenta: ráfaga 120, recarga 2/s. La capa de IP permite 180 / minuto. Cada respuesta incluye el encabezado X-RateLimit-Remaining.

Al superar un límite, la API responde 429 con el encabezado Retry-After (las respuestas en tiempo real también incluyen el campo retry_after). Deténgase el número de segundos indicado y reanude con retroceso exponencial.

POST /v1/realtime/check/{series}

Comprobación individual en tiempo real

Comprueba de forma síncrona un número de teléfono o una dirección de correo. Una solicitud puede incluir varios productos en tiempo real de la misma serie; usa sus ID, no los slugs de productos por lotes.

Idempotency-Key es obligatorio. Repetir la misma solicitud con la misma clave no duplica el cobro; cambiar el contenido devuelve 409. cached=true indica un resultado reutilizado.

Parámetros

Campo	Tipo	Requerido	Descripción
series	path	Sí	Serie: phone o email; debe coincidir con la serie del producto en tiempo real seleccionado.
identifier	string	Sí	Un identificador: un número E.164 o una dirección de correo válida.
country	string	No	Solo para teléfonos: opcional con E.164 completo; un número nacional requiere el código ISO correspondiente. Déjalo vacío para correo.
product_ids	array<int>	Sí	Lista de 1 a 10 ID de productos en tiempo real.

Ejemplo de Respuesta

json

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

Ejemplo de cURL

bash

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":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

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.

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

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

El endpoint de compatibilidad POST /v1/realtime/detect se conserva temporalmente para clientes antiguos. Las integraciones nuevas deben usar /v1/realtime/check/phone o /v1/realtime/check/email.

Productos · Individual (tiempo real)

Los productos en tiempo real se seleccionan por ID de producto y serie; no use slugs de productos por lotes.

Nombre del producto	Series	Identificador	Mínimo
Verificación de números de Amazon	`phone`	`#53`	1
Verificación de correo electrónico de Amazon	`email`	`#54`	1
Verificación de números de Apple ID	`phone`	`#57`	1
Verificación de correo electrónico de Apple ID	`email`	`#58`	1
Verificación de números de BAND	`phone`	`#60`	1
Verificación de números de Facebook	`phone`	`#51`	1
Verificación de correo electrónico de Facebook	`email`	`#52`	1
Verificación de números de Instagram	`phone`	`#48`	1
Verificación de correo electrónico de Instagram	`email`	`#49`	1
Verificación de números de Microsoft	`phone`	`#59`	1
Verificación de números de Telegram	`phone`	`#50`	1
Verificación de números de Viber	`phone`	`#55`	1
Verificación de números de WhatsApp	`phone`	`#47`	1
Verificador de números de teléfono de X	`phone`	`#61`	1

POST /v1/detect

Detección (Array de Números)

Envía una lista de teléfonos o correos para una detección masiva asíncrona. El coste se retiene y se reembolsa lo no procesado.

El mínimo depende del producto y el máximo de la plataforma es 2.000.000. Omite country para email; es obligatorio para teléfono.

HTTP 202 Accepted

Parámetros

Campo	Tipo	Requerido	Descripción
product	string	Sí	Slug del producto. Consulte la lista de productos.
country	string	Obligatorio para teléfonos; omítalo para correo electrónico	Código de país ISO 3166-1 de dos letras. Obligatorio para teléfonos; omítelo para emails.
phones	array	Sí	Array de teléfonos o correos; el mínimo depende del producto y el máximo es 2.000.000.

Ejemplo de Respuesta

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

Detección (Subir Archivo)

Sube un archivo TXT o CSV para detección masiva, un teléfono o correo por línea, máximo 50 MB.

HTTP 202 Accepted

Parámetros

Content-Type: multipart/form-data

Campo	Tipo	Requerido	Descripción
product	string	Sí	Slug del producto
country	string	Obligatorio para teléfonos; omítalo para correo electrónico	Código ISO obligatorio para teléfonos; omítelo para emails.
file	file	Sí	Archivo TXT o CSV, un teléfono o email por línea, máximo 50 MB.

Ejemplo de Respuesta

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "idempotent_replay": false,
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{token}

Estado de Tarea

Consulta cada 3–5 segundos hasta completed o failed.

Ejemplo de Respuesta

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Estado de Tarea

status	Descripción
pending	En cola, esperando recursos.
processing	La detección está en curso.
completed	Completado. El resultado está listo para descargar.
failed	La ejecución falló.

GET /v1/tasks/{token}/result

Obtener URL de Descarga

Obtén el enlace de descarga del resultado. Los archivos se conservan 7 días por defecto (configurable mediante result_retention_days).

Ejemplo de Respuesta

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

Descargar resultado

Descarga el archivo de resultados de una tarea completada mientras siga dentro del periodo de conservación.

Ejemplo de Respuesta

Content-Type: application/zip (or text/csv for a single result).

Este endpoint transmite un archivo en lugar de JSON. Devuelve 404/422 si la tarea no está lista, ha caducado, no está disponible o pertenece a otra cuenta.

Productos · Por lotes (asíncrono)

Usa el slug en el campo product al crear una tarea.

Nombre del producto	Identificador	Mínimo
Verificación de números de Amazon	`amazonValid`	500
Verificación de correo electrónico de Amazon	`amazonEmailValid`	1000
Verificación de números de Apple ID	`appleidValid`	2000
Verificación de correo electrónico de Apple ID	`appleidEmailValid`	1000
Verificación de números de BAND	`bandValid`	500
Verificación de números de Binance	`binanceValid`	2000
Verificación de correo electrónico de Binance	`binanceEmailValid`	2000
Verificación de números de CoinW	`coinwValid`	2000
Verificación de correo electrónico de CoinW	`coinwEmailValid`	2000
Verificación de números de Facebook	`fbValid`	500
Verificación de correo electrónico de Facebook	`fbEmailValid`	1000
Verificación de números de HTX	`htxValid`	1000
Verificación de correo electrónico de HTX	`htxEmailValid`	2000
Verificación de números de iMessage	`imessageValid`	2000
Verificación de números de Instagram	`insValid`	500
Verificación de correo electrónico de Instagram	`insEmailValid`	1000
Verificación de números de KuCoin	`kucoinValid`	1000
Verificación de correo electrónico de KuCoin	`kucoinEmailValid`	2000
Edad y género en LINE	`lineGender`	2000
Verificación de números de LINE	`lineValid`	2000
Perfil completo de Linkedin	`linkedinGender`	2000
Verificación de números de Linkedin	`linkedinValid`	2000
Verificación de números de Microsoft	`microsoftValid`	500
Comprobación de compatibilidad con RCS	`rcsValid`	1000
Verificación de números de Signal	`signalValid`	2000
Verificación de números de Snapchat	`snapchatValid`	500
Perfil completo de Telegram	`tgGender`	500
Verificación de números de Telegram	`tgValid`	1000
Actividad de Telegram	`tgActive`	500
Búsqueda de nombre de usuario de TikTok	`tiktokUsername`	2000
Verificación de números de Viber	`viberValid`	1000
Actividad de Viber	`viberActive`	1000
Perfil completo de WhatsApp	`waGender`	1000
Verificación de números de WhatsApp	`waValid`	1000
Detalles de actividad de WhatsApp	`waActive`	500
Verificador de números de teléfono de X	`twitterValid`	2000
Verificación de correo electrónico de X	`twitterEmailValid`	2000
Edad y género en Zalo	`zaloGender`	500
Verificación de números de Zalo	`zaloValid`	2000
Filtro de actividad en Internet	`live-activity-filter`	2000
Verificación del estado del número	`phone-status-check`	2000
Móvil encendido/apagado	`phone-onoff-check`	1500
Detección de modelo de teléfono	`phone-model-detection`	500
Consulta HLR	`hlr-lookup`	2000

Ejemplos

Copia y ejecuta los ejemplos cURL reemplazando YOUR_KEY_HERE.

1. Consultar saldo

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. Enviar detección

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. Subir archivo

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. Consultar estado de tarea

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. Obtener URL de descarga

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"