Referência da API¶
Contrato de cada adaptador: rotas, parâmetros e códigos HTTP.
Gerada, não escrita
Estas páginas são geradas a partir do código que atende as chamadas, e um teste de integração contínua falha enquanto elas divergirem dele. Se a referência e o comportamento discordarem, é bug. Reporte.
Os adaptadores não publicam OpenAPI em tempo de execução: não existe /openapi.json
nem /docs nos hosts de produção ou homologação. Este site é o único lugar onde publicamos
a referência.
O que a referência não responde¶
Os corpos não estão descritos aqui
Nas respostas, em todos os dialetos. Declaramos a resposta de sucesso como um objeto aberto, um mapa de chaves livres, sem campos nomeados. Fizemos isso de propósito. Os adaptadores devolvem os campos do provedor de origem na íntegra, e declarar um formato fechado faria o servidor ignorar tudo o que não estivesse na declaração. Preferimos repassar o que chega a documentar uma forma que nos obrigaria a podar a resposta.
Nas requisições, onde o manipulador lê o corpo por conta própria. Uma rota que declara um modelo publica o esquema inteiro na referência. Uma rota que recebe o pedido cru e lê o corpo sozinha não informa tipo nenhum ao gerador, e aparece sem corpo. Hoje isso vale para o endereço de token do ACBrAPI, que lê o formulário direto, e para a emissão do SmartNFCe, que recebe o XML pronto.
A consequência prática difere entre os dois casos. Nas respostas, um cliente gerado a partir desta referência não tem tipos, só mapas, em todos os dialetos. Nas requisições, os corpos declarados trazem os campos e o que é obrigatório. Para o significado de cada campo, e para as regras que o esquema não expressa, use as páginas de compatibilidade e de migração do seu dialeto.
A referência descreve a forma da chamada. Ela não descreve a semântica. Para saber por que um campo é ignorado, quando um status aparece, ou o que acontece quando a SEFAZ não responde, use: