OpenAPI

O que é OpenAPI, em palavras simples?

Pense no OpenAPI como o manual técnico oficial de uma API, escrito em um formato padronizado. Em vez de um texto solto explicando como usar o serviço, existe um arquivo estruturado que lista cada endereço disponível (os endpoints), o que precisa ser enviado, o que volta como resposta e quais erros podem acontecer.

Esse arquivo é chamado de especificação ou documento OpenAPI. Como segue regras bem definidas, ele pode ser lido por pessoas e também processado automaticamente por programas, o que abre espaço para gerar documentação, testes e código a partir dele.

Para que serve o OpenAPI em uma API fiscal?

Em uma API fiscal, que emite documentos como NF-e, NFS-e, NFC-e, CT-e e MDF-e, os dados enviados são extensos e cheios de regras: emitente, destinatário, itens, tributos, transporte. Uma especificação OpenAPI mostra exatamente quais campos existem, quais são obrigatórios, que tipo de valor cada um aceita e qual é o formato da resposta.

Isso reduz tentativas e erros na integração. A equipe que mantém um ERP ou uma plataforma de vendas consegue entender o payload de emissão antes de escrever código, identificar a autenticação exigida e saber quais status e mensagens de rejeição esperar.

Como funciona um documento OpenAPI?

O documento é organizado em partes. Há informações gerais da API, a lista de caminhos (por exemplo, um caminho para criar uma nota e outro para consultar o status), os métodos HTTP aceitos em cada um, os parâmetros de consulta, o corpo da requisição e as respostas possíveis com seus códigos.

Os formatos dos dados costumam ser descritos com esquemas baseados em JSON Schema. Também há uma seção para definir os mecanismos de segurança, como API Key no cabeçalho ou Bearer token, indicando como cada chamada deve ser autenticada.

Qual a diferença entre OpenAPI e Swagger?

OpenAPI é o nome atual da especificação, ou seja, das regras para descrever a API. Swagger era o nome original dessa especificação e hoje designa principalmente um conjunto de ferramentas que trabalham com ela.

A mais conhecida é o Swagger UI, que transforma um arquivo OpenAPI em uma página interativa de documentação, na qual é possível ler os endpoints e até testar chamadas. Por isso, muita gente ainda usa as duas palavras como se fossem a mesma coisa.

Quais benefícios o OpenAPI traz para quem integra?

O principal benefício é ter uma fonte única e confiável sobre como a API se comporta. A partir da especificação é possível gerar automaticamente clientes em várias linguagens, como Java ou JavaScript, criar coleções para ferramentas de teste e validar se as requisições estão no formato certo antes de enviá-las.

Também facilita a manutenção: quando a API muda, a comparação entre versões da especificação mostra o que foi adicionado ou alterado. E, como o formato é estruturado, ferramentas de inteligência artificial e agentes conseguem interpretar a especificação para entender quais operações estão disponíveis.

O OpenAPI substitui o leiaute fiscal oficial?

Não. O OpenAPI descreve a interface da API do provedor, normalmente em JSON. O leiaute fiscal e os esquemas XML definidos pelos órgãos autorizadores, como a SEFAZ e as prefeituras, continuam valendo para o documento fiscal em si.

Na prática, a API recebe os dados no formato descrito pela especificação OpenAPI e se encarrega de convertê-los para o XML oficial exigido pelo autorizador. As regras fiscais, portanto, seguem existindo; o OpenAPI apenas documenta a porta de entrada.

Exemplos de OpenAPI

• Uma desenvolvedora de um ERP abre a especificação OpenAPI de uma API fiscal para descobrir quais campos são obrigatórios no envio de uma NFS-e e qual código de resposta indica que a nota foi recebida para processamento.
• Uma equipe gera automaticamente um cliente em JavaScript a partir do arquivo OpenAPI, evitando escrever à mão cada chamada para emitir NF-e, consultar status e baixar o XML.
• Um marketplace usa a especificação OpenAPI para validar o payload de emissão de NFC-e em seus testes automatizados, detectando campos com tipo errado antes de chegar ao ambiente de homologação.
• Um time técnico carrega o arquivo OpenAPI no Swagger UI para testar, no ambiente de homologação, a consulta de um documento fiscal usando sua API Key.