Endpoint de API

O que é um endpoint de API, na prática?

Pense em uma API como uma central de atendimento, que reúne vários setores. Para resolver cada assunto, você liga para um ramal diferente. O endpoint é esse ramal: um ponto de contato específico, criado para uma tarefa determinada.

Em uma API fiscal, por exemplo, pode haver um endpoint para enviar uma NF-e para emissão, outro para consultar se ela foi autorizada e outro para baixar o arquivo XML. O sistema que faz a integração, como um ERP ou uma plataforma de vendas, escolhe o endpoint de acordo com o que precisa fazer naquele momento.

Como funciona uma chamada a um endpoint?

Uma chamada combina algumas partes. A primeira é o endereço, formado por uma URL base, que é igual para toda a API, mais um caminho que identifica o recurso. A segunda é o método HTTP, que indica a intenção: GET costuma servir para consultar, POST para criar, PUT ou PATCH para alterar e DELETE para remover.

A requisição também leva cabeçalhos, nos quais normalmente vai a credencial de acesso, como uma API Key ou um Bearer token. Quando há dados para enviar, eles seguem no corpo da requisição, geralmente em formato JSON.

O endpoint devolve uma resposta com um código de status, que mostra se deu certo (por exemplo, 200 ou 201) ou se houve erro (como 400, 401 ou 500), acompanhado dos dados solicitados ou de uma mensagem explicando o problema.

Quais endpoints são comuns em uma API fiscal?

Embora cada fornecedor organize sua API de um jeito, alguns grupos de endpoints aparecem com frequência: emissão de documentos (NF-e, NFS-e, NFC-e, CT-e, MDF-e), consulta de status, cancelamento e outros eventos fiscais, download de XML e PDF, e listagem de documentos com filtros por data, empresa ou situação.

Também é comum haver endpoints administrativos, para cadastrar empresas emissoras, enviar certificados digitais e configurar dados como série e numeração. A documentação da API é o lugar onde cada endpoint é descrito, com seus parâmetros, exemplos de requisição e possíveis respostas.

Qual a diferença entre endpoint, API e URL?

A API é o conjunto completo de regras e funções que um sistema oferece para outros usarem. O endpoint é uma dessas funções, acessível em um endereço próprio. A URL é o endereço em si, que identifica onde o endpoint está.

Um mesmo endereço pode representar endpoints diferentes conforme o método usado. Por exemplo, enviar um GET para o caminho de notas pode listar documentos, enquanto um POST no mesmo caminho pode criar uma nova emissão. Por isso, endpoint costuma ser entendido como a combinação de método e caminho.

Por que existem endpoints diferentes para homologação e produção?

Muitas APIs fiscais oferecem dois ambientes: o de homologação, usado para testes, em que os documentos não têm validade jurídica, e o de produção, em que as notas são reais e geram efeitos fiscais. Cada ambiente pode ter uma URL base diferente ou ser selecionado por um parâmetro ou credencial específica.

Separar os ambientes evita que um teste gere uma nota verdadeira por engano. Antes de colocar uma integração no ar, o recomendado é validar todos os endpoints usados em homologação e só depois apontar o sistema para produção.

Que cuidados tomar ao integrar com endpoints fiscais?

A emissão fiscal depende de órgãos externos, como Secretarias da Fazenda e prefeituras, que podem demorar ou ficar indisponíveis. Por isso, muitos endpoints de emissão trabalham de forma assíncrona: recebem o pedido, devolvem um identificador e o resultado final é obtido depois, por consulta ou por notificação automática.

Também é importante definir tempo limite para as chamadas, repetir tentativas com intervalos crescentes em caso de falha temporária, evitar enviar o mesmo documento duas vezes e guardar as credenciais de acesso com segurança, nunca expostas no código de aplicativos ou páginas públicas.

Exemplos de Endpoint de API

• Um ERP envia uma requisição POST para o endpoint de emissão de NF-e com os dados da venda em JSON e recebe como resposta um identificador do documento e o status inicial de processamento.
• Uma plataforma de vendas consulta periodicamente, com GET, o endpoint de status de uma NFC-e até receber a confirmação de que ela foi autorizada.
• Um software de gestão chama o endpoint de download para obter o XML e o PDF de uma NFS-e já autorizada e anexá-los ao pedido do cliente.
• Durante os testes, a equipe de desenvolvimento usa os endpoints do ambiente de homologação para simular emissões e cancelamentos sem gerar documentos com validade fiscal.