O que é a NS NF-e API?
A NS NF-e API é uma aplicação de integração por onde outras aplicações podem realizar a emissão e gerenciamento de NF-es.
Diferentemente das aplicações tradicionais, onde os dados dos documentos são enviados para a aplicação de integração através de arquivos TXTs ou banco de dados, com a NS NF-e API os dados são enviados e recebidos através de requisições HTTPs que podem ser facilmente implementadas em qualquer linguagem de programação.
Uma API é uma aplicação que possui métodos consumíveis por outras aplicações, ou seja, é uma aplicação que possui métodos que podem ser acessados diretamente através do código de outras aplicações.
Dá-se o nome de Consumidora ou Cliente à aplicação que consome os métodos de uma API.
Informações enviadas e recebidas nas requisições
Dados de envio
Os dados de envio variam de acordo com o método que está sendo consumido. Veja a documentação de consumo da API para informações detalhadas de quais dados são enviados para cada método.
O formato de dados enviados é JSON, mas em alguns casos é possível enviar os dados também em XML ou TXT.
Dados recebidos
Toda requisição receberá como retorno algumas informações que podem ser classificadas em dois grupos: Status HTTP e Dados de Retorno.
Status HTTP
O status HTTP é enviado no cabeçalho da resposta e informa se a requisição foi realizada com sucesso ou se algum erro ocorreu. Este status é formado por um código e uma mensagem.
Por exemplo, se a requisição HTTP for realizada para o endereço errado o status HTTP terá código 404 e mensagem Não encontrado (Not Found). Se a requisição HTTP for realizada corretamente o status HTTP terá código 200 e mensagem OK.
As informações do Status HTTP não devem ser considerados como dados de resposta do método consumido. Estas informações informam apenas se a requisição HTTP foi realizada com sucesso ou não.
Veja na tabela abaixo os códigos de Status HTTP que podem ser retornados pela API:
| Código | Descrição | Quando Ocorre | Possui dados de retorno |
|---|---|---|---|
| 200 | OK | Sim | |
| 400 | Requisição mal formada | Quando a requisição está sendo realizada com dados montados de forma errada | Não |
| 401 | Não autorizado | Quando a aplicação consumidora tenta acessar algum recurso não autorizado | Não |
| 403 | Acesso negado | Quando o token de acesso informado é inválido | Não |
| 404 | Não encontrado | Quando a URL do método é inválida ou a informação requisitada não é encontrada | Sim (mas pode não conter caso o erro seja URL não existente) |
| 501 | Erro interno da API | Quando algum erro interno não previsto ocorre | Sim |
Dados de Retorno
Os dados de retorno são enviados no corpo da resposta e possuem as informações de resposta do método consumido. Estes dados variam de acordo com cada método consumido.
Dependendo de qual for o Status HTTP retornado, estas informações podem não existir. Por exemplo, se o status HTTP for 400 (Bad Request), o retorno conterá apenas o Status HTTP e não terá Dados de retorno. Por este motivo, é importante que a sua aplicação sempre valide o Status HTTP recebido antes de utilizar as informações dos Dados de Retorno para garantir que os mesmos existem.
Código e descrição do Retorno
Os dados de retorno possuem dois campos que indicam a situação do processamento realizado chamados status e motivo. Além destes campos, outros campos também estarão presentes e serão específicos para cada método da API. Veja a documentação de consumo da API para visualizar os campos retornados por cada método.
Os campos status e motivo informam o código de Status do Processamento e descrição literal do status de processamento, respectivamente.
O Status do Processamento é diferente do Status HTTP visto acima. Por exemplo, o consumo de um determinado método pode retorno Status HTTP 200, que indica que a comunicação com a API aconteceu de forma correta, e Status de Processamento -400, que indica que algum campo obrigatório não foi informado.
A tabela abaixo mostra os códigos de Status de Processamento que são comuns a todos os métodos. Demais códigos são específicos de cada método e estão documentados na página de consumo da API.
| Código | Descrição |
|---|---|
| 200 | OK |
| -400 | Campos obrigatórios não preenchidas |
| -401 | Usuário sem permissões para gerenciar documentos do contribuinte |
| -500 ou -999 | Erro interno da API |
Layout dos dados de integração
O layout padrão de integração para troca de informações é o JSON. No entanto, no método de emissão de NF-e é possível realizar o envio dos dados em XML ou TXT considerando o mesmo layout utilizado pela aplicação In House de integração da News Systems.
O JSON de integração deve ser montado seguindo o mesmo layout do arquivo TXT de emissão. Clique aqui para ver os padrões de layout do arquivo TXT.
Conversão do arquivo TXT para JSON
Exemplos dos dados do tomador do serviço informados no arquivo TXT:
Dados do ICMS de CST 00
N02|0|00|1|1500.00|17.00|255.00|
Veja agora como ficam os mesmos dados informados no padrão JSON:
// RETORNO DE UMA NOTA
"ICMS00": {
"orig": "0",
"CST": "00",
"modBC": "1",
"vBC": "1500.00",
"pICMS": "17.00",
"vICMS": "255.00"
}
O quadro abaixo mostra como ficará o XML gerado a partir destas informações:
<ICMS00>
<orig>0</orig>
<CST>00</CST>
<modBC>1</modBC>
<vBC>1500.00</vBC>
<pICMS>17.00</pICMS>
<vICMS>255.00</vICMS>
</ICMS00>
Fluxograma de comunicação
O fluxograma abaixo apresenta o fluxo de comunicação entre a Aplicação Cliente e a NS NF-e API em um processo completo de emissão de NF-e, que inicia com a geração dos dados da NF-e e envio para a API até a obtenção da DANFE para impressão:
