OpenAPI

O contrato da API do Conota é descrito em OpenAPI 3.

https://api.conota.dev/docs/json     # JSON
https://api.conota.dev/docs/yaml     # YAML

Essa especificação é a fonte da Referência da API e do Swagger UI — as duas páginas mostram o mesmo contrato, com apresentações diferentes.

Usos comuns

• importar no Postman;
• gerar clientes em várias linguagens;
• validar contratos em CI;
• alimentar ferramentas de documentação;
• dar contexto estruturado a ferramentas de desenvolvimento assistido por IA.

Gerando um cliente

npx @openapitools/openapi-generator-cli generate \
  -i https://api.conota.dev/docs/json \
  -g typescript-axios \
  -o ./cliente-conota

Cliente gerado não sabe de fluxo

Um SDK gerado sabe chamar POST /v1/nfe/emitir. Ele não sabe que a resposta é assíncrona, que completed não significa autorizada, nem que reenviar depois de um timeout pode duplicar a nota. Essa parte está aqui, neste portal.

A regra interna

Toda alteração de endpoint atualiza o OpenAPI na mesma entrega — porque o spec é gerado do próprio código da rota, não escrito à parte. Um endpoint publicado sem summary, description e exemplos adequados é tratado como documentação incompleta.