OpenAPI

Todos los endpoints de esta documentación también se publican como un documento OpenAPI 3.1 legible por máquina, de modo que puedes controlar tus herramientas desde el contrato en lugar de transcribir tablas a mano.

Copiar	URL	Notas
Documentación	https://docs.zelnum.com/openapi.yaml	Estable, en este dominio. Canónico para los lectores de este sitio.
Plataforma	https://app.zelnum.com/docs/openapi.yaml	Origen. La copia de la documentación es un espejo idéntico byte a byte de ese original.

Ambos archivos son el mismo documento. El espejo existe para que la especificación viva en el host que ya estás leyendo, en una ruta que las herramientas pueden encontrar.

Qué contiene el documento

Parte	Cantidad	Contenido
Servers	1	https://api.zelnum.com/api/v1
Paths	10	Los nueve endpoints documentados más el alias heredado de tiempo real
Tags	3	Common, Realtime, Bulk — la misma división que usa la navegación
Schemas	9	Cuerpos de solicitud y respuesta, incluida la envoltura de error
Esquemas de seguridad	2	X-API-Key y Authorization: Bearer

Los detalles a nivel de operación están en el propio documento: encabezados obligatorios, minItems/maxItems en los arreglos, enumeraciones para series, mode, status y billing_status, y la marca deprecated: true en POST /v1/realtime/detect.

Importar en herramientas de API

Postman — Import → File → openapi.yaml. Postman crea una colección con una variable de entorno para la URL base; define tu clave como encabezado X-API-Key a nivel de colección para que todas las solicitudes lo hereden.

Insomnia — Create → Import From → File, luego agrega X-API-Key como encabezado de colección.

Generadores de Bruno / HTTPie / curl — todos consumen OpenAPI 3.1 directamente:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

Generar un cliente con tipos

No hay SDK propio — la API es JSON simple sobre HTTPS, y un cliente generado suele encajar mejor que uno escrito a mano, porque sigue las convenciones de tu lenguaje.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

Los clientes generados leen la URL base y el esquema de seguridad del documento, así que lo único que aportas en tiempo de ejecución es tu clave API.

Tiempo real exige un encabezado que el generador no puede inventar

Idempotency-Key es un encabezado obligatorio en los endpoints de tiempo real, y un cliente generado lo expondrá como un parámetro de método que debes definir. Debe ser único por envío — consulta Idempotencia y reintentos.

Mantener el espejo fiel

El espejo sigue al origen; nunca se edita aquí. Como la divergencia entre un contrato publicado y su documentación es el fallo que esta página existe para prevenir, la copia se verifica contra el origen en lugar de darla por buena:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check necesita acceso a la red y deliberadamente no forma parte de la compilación del sitio — un despliegue no debe fallar porque el host de la plataforma tuvo un mal minuto. Lo que la compilación sí exige es la mitad offline del invariante: todo endpoint que describe esta documentación debe existir en el documento vendorizado, de modo que una página no puede documentar una operación que el contrato no tiene.

Siguiente

• Versionado y obsolescencia — qué significa para ti la marca deprecated en el endpoint heredado
• Formato de respuesta — la envoltura que comparten todos los endpoints