Registro de cambios

Esta página registra los cambios en la API y en esta documentación. Las entradas comienzan el 2026-09-19: todo lo que cambió antes de que existiera esta página no se enumera de forma retroactiva, así que considera una entrada ausente como «no registrado» en lugar de «no cambiado».

Cómo leerlo

Tipo	Significado
API	El servicio cambió — un endpoint, un campo, un límite.
Contrato	Cambió el documento OpenAPI publicado.
Documentación	Cambió la documentación. La API no se movió.
Corrección	La documentación había estado describiendo la API de forma incorrecta.

Las entradas de Corrección se señalan por separado a propósito. Describen un cambio en lo que leerías, no en lo que hace la API — así que nada de tu integración se rompe, pero cualquier cosa que hayas construido a partir de la descripción antigua puede estar mal.

2026-10-27 — Referencia de códigos de país

Documentación · Añadido

Una página de Códigos de país con búsqueda que lista todos los códigos ISO 3166-1 alfa-2 asignados oficialmente, enlazada desde los endpoints que reciben el campo country.

2026-09-19 — Documentación reestructurada, contrato publicado

Documentación · Añadido

Una sección de Referencia: OpenAPI, Versionado y obsolescencia, Estado y soporte, Seguridad y Glosario.
El documento OpenAPI 3.1 ya se publica en https://docs.zelnum.com/openapi.yaml, un espejo idéntico byte a byte de la copia de la plataforma, importable en Postman, Insomnia y generadores de clientes.
Ejemplos de cliente en Python, Node.js, PHP y Go para ambos modos de detección, junto a los ejemplos de cURL existentes. La navegación prometía ejemplos de SDK cuando solo existía cURL.
Tablas de respuesta campo por campo para los endpoints de comprobación en tiempo real, envío masivo, estado de tarea y resultado.
Dos guardas de compilación nuevas: la compilación ahora falla ante una tabla descuadrada en cualquier idioma, y concilia cada endpoint que nombra esta documentación con el documento OpenAPI vendorizado en ambas direcciones — un endpoint documentado que al contrato le falta, y una ruta del contrato que nadie documenta, son ambos fallos.

Contrato · Añadido

El propio documento OpenAPI: 10 rutas, 9 esquemas y deprecated: true en el POST /v1/realtime/detect heredado.

Documentación · Correcciones

El country masivo estaba documentado como obligatorio para todo envío. Es obligatorio para productos de teléfono y debe omitirse para productos de correo electrónico. Tal como estaba escrito, los nueve productos masivos de correo electrónico no se podían enviar — toda solicitud habría fallado la validación.
La regla de volumen masivo era incorrecta. Decía «1,000 a 2,000,000 de números por solicitud». La regla real es el mínimo propio del producto seleccionado — 500, 1,000 o 2,000 — hasta un máximo de plataforma de 2,000,000. La cifra antigua excluía once productos cuyo mínimo es 500.
El catálogo de errores enumeraba cuatro códigos que la API nunca devuelve. La página de documentación heredada de la plataforma nombra not_found, result_not_ready, result_expired y validation_failed; la implementación no emite ninguno de ellos, y esas respuestas no llevan ningún campo code. La tabla ahora enumera los 22 códigos que la API devuelve en realidad, y una segunda tabla documenta las condiciones sin código — con una advertencia para quien haya portado esas cuatro ramas.
Los ejemplos de respuesta omitían campos que la API devuelve en realidad. series, charged_amount y refunded_amount en las respuestas en tiempo real; idempotent_replay y recovery_pending en los envíos masivos; y diez contadores de progreso de tarea, incluidos submitted, prefiltered, deduped, stage, last_progress_at y failure_message.
Los límites de tasa nombraban el endpoint equivocado. La fila de tiempo real decía POST /v1/realtime/check/phone; el límite se aplica a POST /v1/realtime/check/{series}, incluido el correo electrónico.
Los encabezados de respuesta estaban descritos de forma incorrecta. La página de límites de tasa daba a entender que el conjunto completo de encabezados aparece en todas las respuestas. No es así: el depósito de tiempo real informa solo de X-RateLimit-Remaining en caso de éxito y nunca de X-RateLimit-Limit, y X-RateLimit-Reset aparece solo en un 429 general o de detección. La página ahora indica qué encabezado aparece dónde.
El modelo de claves estaba descrito de forma incorrecta. La página de seguridad afirmaba que una cuenta tiene una sola clave a la vez. Una cuenta puede tener varias claves activas, y la Consola las crea, regenera y elimina individualmente — por lo que es posible una rotación por etapas sin tiempo de inactividad, y regenerar in situ es la variante que no tiene solapamiento. GET /v1/api-key informa de la clave activa más reciente en lugar de un inventario, y su last_used se escribe como máximo una vez cada cinco minutos.
Los ID frente a los slugs estaban descritos de forma incorrecta. El glosario decía que un ID o un slug confundidos se rechazan como product_mode_not_supported. En los endpoints de tiempo real, product_ids se valida como un arreglo de enteros, así que un slug se rechaza antes como 400 invalid_realtime_request; 422 product_mode_not_supported es la respuesta del endpoint masivo ante un producto de tiempo real.
La página de formato de respuesta contradecía a la de saldo en cuanto a la moneda. Una decía «la moneda de facturación de la cuenta», la otra USD. Ahora ambas dicen USD, que es lo que dicen el contrato y el endpoint de saldo.
Se afirmaba una unidad de precio sin fuente. Lo masivo se describía como «con precio por cada 10,000 comprobaciones». El catálogo no expone ningún precio, así que la afirmación se eliminó en lugar de mantenerse.
Dos correcciones solo habían llegado a las páginas escritas a mano. La afirmación sobre la moneda y la de «por cada 10,000 comprobaciones» se corrigieron en las páginas en inglés y en chino simplificado, pero la tabla de cadenas que genera los otros siete idiomas aún las contenía, así que siete idiomas siguieron publicando ambas. También se corrigen en la tabla.
/examples/ era una página distinta en cada idioma. La página en inglés era un centro de navegación breve, mientras que las otras ocho mostraban un recorrido masivo de cinco pasos. El inglés ahora coincide con el recorrido, así que los nueve idiomas llevan el mismo contenido.

Documentación · Arreglos

Las tablas de parámetros perdieron silenciosamente su columna de descripción en los siete idiomas generados. Un auxiliar compartido emitía un encabezado de tres columnas para filas de cuatro celdas, y GFM descarta toda celda que supere el ancho del encabezado — así que en español, por ejemplo, el valor «Required» se mostraba bajo el encabezado «Description» y la descripción en sí desaparecía, en tres páginas de siete idiomas. El auxiliar ahora toma una forma de columna explícita y falla la compilación ante una fila descuadrada, y la guarda de la etapa dist vuelve a comprobar de forma independiente cada tabla renderizada en cada idioma.
Los idiomas generados mostraban en inglés los encabezados de columna de la tabla de productos, su nota y su línea de sincronización, y las comillas invertidas de la nota llegaban al navegador como caracteres literales. El texto del componente ahora proviene de la tabla de cadenas traducida, y una traducción ausente falla la compilación en lugar de recurrir a un valor de reserva.

Suscribirse a los cambios

Todavía no hay un canal de suscripción. Hasta que lo haya, la señal fiable es el contrato:

npm run openapi:check

en una tarea programada — termina con un código distinto de cero en cuanto el documento publicado difiere de la copia que vendorizaste. Consulta OpenAPI para las dos URL.