OpenAPI

Todo endpoint desta documentação também é publicado como um documento OpenAPI 3.1 legível por máquina, para que você possa orientar as ferramentas a partir do contrato em vez de transcrever tabelas manualmente.

Cópia	URL	Observações
Documentação	https://docs.zelnum.com/openapi.yaml	Estável, neste domínio. Canônico para os leitores deste site.
Plataforma	https://app.zelnum.com/docs/openapi.yaml	Upstream. A cópia da documentação é um espelho idêntico byte a byte.

Os dois arquivos são o mesmo documento. O espelho existe para que a especificação fique no host que você já está lendo, em um caminho que as ferramentas conseguem encontrar.

O que o documento contém

Parte	Quantidade	Conteúdo
Servers	1	https://api.zelnum.com/api/v1
Paths	10	Os nove endpoints documentados mais o alias legado de tempo real
Tags	3	Common, Realtime, Bulk — a mesma divisão usada pela navegação
Schemas	9	Corpos de requisição e resposta, incluindo o envelope de erro
Esquemas de segurança	2	X-API-Key e Authorization: Bearer

Os detalhes em nível de operação estão no próprio documento: cabeçalhos obrigatórios, minItems/maxItems em arrays, enums para series, mode, status e billing_status, e o sinalizador deprecated: true em POST /v1/realtime/detect.

Importar para ferramentas de API

Postman — Import → File → openapi.yaml. O Postman cria uma coleção com uma variável de ambiente para a URL base; defina sua chave como um cabeçalho X-API-Key no nível da coleção para que toda requisição a herde.

Insomnia — Create → Import From → File, depois adicione X-API-Key como um cabeçalho da coleção.

Geradores de Bruno / HTTPie / curl — todos consomem o OpenAPI 3.1 diretamente:

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

Gerar um cliente tipado

Não há SDK próprio — a API é JSON simples sobre HTTPS, e um cliente gerado costuma se adequar melhor do que um escrito à mão, porque segue as convenções da sua linguagem.

# 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

Os clientes gerados leem a URL base e o esquema de segurança do documento, então a única coisa que você fornece em tempo de execução é a sua chave de API.

Tempo real exige um cabeçalho que o gerador não consegue inventar

Idempotency-Key é um cabeçalho obrigatório nos endpoints de tempo real, e um cliente gerado o exporá como um parâmetro de método que você precisa definir. Ele deve ser exclusivo por envio — consulte Idempotência e novas tentativas.

Mantendo o espelho confiável

O espelho segue o upstream; nunca é editado aqui. Como a divergência entre um contrato publicado e sua documentação é exatamente a falha que esta página existe para evitar, a cópia é verificada em relação ao upstream em vez de ser simplesmente aceita:

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

openapi:check precisa de acesso à rede e deliberadamente não faz parte do build do site — uma implantação não deve falhar porque o host da plataforma teve um minuto ruim. O que o build realmente exige é a metade offline do invariante: todo endpoint descrito nesta documentação deve existir no documento vendorizado, para que uma página não possa documentar uma operação que o contrato não possui.

A seguir

• Versionamento e descontinuação — o que o sinalizador deprecated no endpoint legado significa para você
• Formato da resposta — o envelope que todo endpoint compartilha