O que é a NS NFC-e API
A NS NFC-e API é uma aplicação de integração por onde outras aplicações podem realizar a emissão e gerenciamento de NFC-es – Nota Fiscal de Consumidor Eletrônica.
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 NFC-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.
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 (enviado para a API)
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, sendo alguns casos é possível enviar os dados também em XML ou TXT conforme documentação específica do método.
Informações de cabeçalho
Em todas as requisições realizadas para a API obrigatoriamente deverão ser enviadas no cabeçalho as seguintes informações:
| Campo | Descrição |
|---|---|
| X-AUTH-TOKEN | Token de identificação da Software House |
Dados recebidos (retornados pela API)
Toda a requisição terá em sua resposta os campos status e motivo que conterão o código de status de processamento e a descrição literal deste código, respectivamente.
Além destas informações, cada método da API poderá retornar outras informações específicas.
Códigos e descrição de Retornos Padrão
Cada método da API possui códigos de status de processamento específicos que estão documentados no quadro de códigos de retorno na página de consumo do método.
Além dos códigos específicos existem também códigos padrões que podem ser retornados por todos os métodos conforme quadro abaixo:
| Código | Descrição | Observação |
|---|---|---|
| -999 | Erro interno ao realizar a requisição | O campo motivo conterá maiores informações sobre o erro ocorrido |
| -997 | Campos obrigatórios não informados | A mensagem conterá também os campos obrigatórios que não foram preenchidos |
| -996 | Você não possui permissões para gerenciar os documentos do CNPJ | CNPJ do contribuinte não está vinculado a Software House do Token de Identificação enviado em X-AUTH-TOKEN |
| -995 | Documento inválido de acordo com a validação contra o XSD |
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 NFC-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 NS Tecnologia.
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 de medicamentos informados no arquivo TXT:
Dados de totais
K|123|1|2016-12-13|2017-12-13|50
Veja agora como ficam os mesmos dados informados no padrão JSON:
"med": {
"nLote": "123",
"qLote": "1",
"dFab": "2016-12-13",
"dVal": "2017-12-13",
"vpmc": "50"
}
O quadro abaixo mostra como ficará o XML gerado a partir destas informações:
<med>
<nLote>123</nLote>
<qLote>1</qLote>
<dFab>2016-12-13</dFab>
<dVal>2017-12-13</dVal>
<vpmc>50</vpmc>
</med>