REST

O que significa REST na prática?

REST não é um programa nem uma linguagem. É um conjunto de regras e boas práticas para organizar a comunicação entre sistemas pela internet. Quando uma API segue essas regras, ela é chamada de API REST ou RESTful.

A ideia central é simples: tudo o que o sistema oferece é um recurso, como uma nota fiscal, uma empresa ou um certificado. Cada recurso tem um endereço (a URL) e pode ser consultado, criado, alterado ou removido usando os mesmos verbos do HTTP, o protocolo que os navegadores já usam para abrir páginas.

Como funciona uma API REST?

O sistema que quer algo (o cliente) envia uma requisição HTTP para um endereço da API, chamado endpoint. A requisição informa o método, que indica a intenção: GET para consultar, POST para criar, PUT ou PATCH para atualizar e DELETE para remover. Quando há dados a enviar, eles vão no corpo da requisição, normalmente em JSON.

O servidor processa o pedido e devolve uma resposta com um código de status e, se for o caso, um corpo com dados. Os códigos seguem um padrão: a faixa 200 indica sucesso, a faixa 400 indica erro do cliente (como dados inválidos ou falta de autenticação) e a faixa 500 indica falha no servidor.

Por exemplo, um ERP pode enviar um POST com os dados de uma venda para um endpoint de emissão de NF-e e, depois, fazer um GET no endereço daquela nota para saber se ela já foi autorizada.

Quais são os princípios de uma API REST?

Separação entre cliente e servidor: cada lado evolui de forma independente, desde que a forma de comunicação seja mantida. Comunicação sem estado (stateless): cada requisição carrega tudo o que é necessário para ser entendida, incluindo a autenticação, sem depender de conversas anteriores.

Interface uniforme: recursos identificados por URLs e manipulados pelos mesmos métodos padronizados, o que torna a API previsível. Há ainda a possibilidade de cache de respostas e a organização em camadas, permitindo usar gateways e balanceadores sem que o cliente perceba.

Qual a diferença entre REST e SOAP?

SOAP é um protocolo mais antigo e rígido, baseado em mensagens XML com envelopes e contratos formais. REST é um estilo mais leve e flexível, que aproveita diretamente os recursos do HTTP e costuma usar JSON, um formato mais fácil de ler e de gerar.

No mundo fiscal essa diferença aparece bastante: os web services da SEFAZ para NF-e, por exemplo, usam SOAP com XML assinado. Uma API fiscal REST pode receber os dados em JSON, montar o XML no padrão exigido, assiná-lo e conversar com os órgãos autorizadores, poupando o sistema do cliente dessa complexidade.

Por que REST é tão usado na emissão fiscal por API?

Porque praticamente toda linguagem de programação sabe fazer requisições HTTP e trabalhar com JSON. Isso reduz o tempo de integração de ERPs, plataformas de venda e marketplaces, que podem emitir NF-e, NFC-e, NFS-e, CT-e e MDF-e por uma interface única e padronizada.

O modelo também combina bem com fluxos assíncronos: o sistema envia o documento, recebe uma resposta imediata de que o pedido foi aceito e depois consulta o status ou recebe um webhook com o resultado, o XML e o PDF.

Exemplos de REST

• Um ERP envia um POST para o endpoint de NFC-e com os itens da venda em JSON e recebe como resposta um identificador do documento e o status inicial de processamento.
• Uma plataforma de serviços faz um GET no endereço de uma NFS-e específica para verificar se a prefeitura já autorizou a nota e obter o link do PDF.
• Um marketplace recebe o código de status 401 ao chamar a API porque a API Key enviada no header de autenticação estava expirada.
• Uma transportadora consulta, via GET com query parameters de data e status, a lista de MDF-e ainda não encerrados.