O que é a NS NFCom API
A NS NFCom API é uma aplicação de integração por onde outras aplicações podem realizar a emissão e gerenciamento de NFCom’s.
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 NFCom 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.
Veja em nossos exemplos de integração como implementar a comunicaçã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.
Dados de 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 consideradas 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 (mas pode não conter caso o erro seja URL não existente) |
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 |
|---|---|
| -400 | Campos obrigatórios não preenchidas |
| -500 ou -999 | Erro interno da API |
| 200 | ok |
| -401 | Usuário sem permissões para gerenciar documentos do contribuinte |
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 NFCom é possível realizar o envio dos dados também em XML considerando o mesmo layout definidos pelo Manual de Orientação do Contribuinte da Sefaz.
O JSON de integração deve ser montado seguindo o mesmo layout do XML de emissão.
Exemplo de geração de JSON
O quadro abaixo mostra um trecho do XML montado de acordo com o layout da Sefaz:
<?xml version="1.0" encoding="utf-8"?>
<NFCom xmlns="http://www.portalfiscal.inf.br/nfcom">
<infNFCom versao="1.00" Id="NFCom43240107364617000135620000000000011000000016">
<ide>
<cUF>43</cUF>
<tpAmb>2</tpAmb>
<mod>62</mod>
<serie>0</serie>
<nNF>2</nNF>
<cNF>0000001</cNF>
<cDV>6</cDV>
<dhEmi>2024-01-08T11:04:29-04:00</dhEmi>
<tpEmis>1</tpEmis>
<nSiteAutoriz>0</nSiteAutoriz>
<cMunFG>4303509</cMunFG>
<finNFCom>0</finNFCom>
<tpFat>0</tpFat>
<verProc>1.00</verProc>
</ide>
No quadro abaixo é possível ver o JSON montado com as mesmas informações acima:
{
"NFCom": {
"infNFCom": {
"versao": "1.00",
"ide": {
"cUF": "43",
"tpAmb": "2",
"mod": "62",
"serie": "0",
"nNF": "1",
"cNF": "0000001",
"cDV": "6",
"dhEmi": "2024-01-08T11:04:29-04:00",
"tpEmis": "1",
"nSiteAutoriz": "0",
"cMunFG": "4303509",
"finNFCom": "0",
"tpFat": "0",
"verProc": "1.00"
},