Tudo sobre API em 3 Simples Passos

As APIs oferecem uma forma de comunicação que não depende de uma linguagem específica para utilizá-la, basta através de sua linguagem de programação realizar a comunicação acessando as URLs fornecidas para acesso a API.

Outro fator importante é entender a regra de negócio para realizar essa comunicação, deixando mais claro o tratamento de exceções e o processo de emissão. Sabendo disso, o processo de Autorização na API de NFe possui 3 passos para facilitar a comunicação de qualquer linguagem que você possa utilizar, sendo eles o envio dos dados, consulta do status do processamento e/ou download do documento.

Confira nosso fluxograma:

Passo 1

Neste primeiro passo, como pode ser visto no fluxograma, são enviados os dados como como o token, o content-type e conteúdo da nota, então a API retornará o código 200 que indicará se a emissão ocorreu corretamente ou outro código(diferente de 200) caso haja algum erro. Se não houver erro na emissão retornará junto o nsNRec.

É importante guardar o nsNRec, pois ele é um registro único em nosso servidor usado para identificar a nota enviada.

Exemplo Retorno com Sucesso:

{ "status": 200, "motivo": "NF-e enviada para Sefaz", "nsNRec": "1438"}

Exemplo de Retorno com Rejeição:

{ "status": -2, "motivo": "NFe invalido de acordo com a validacao contra schema", "erros": [ "cvc-pattern-valid: Value '9618000' is not facet-valid with respect to pattern '[0-9]{8}' for type '#AnonType_CEPTEndereco'.", "O campo 'CEP' foi preenchido incorretamente com o valor '9618000'. Este campo deve ser preenchido com numeros e conter exatamente 8 caracteres." ]}

Como comentado acima, no momento que você receber o retorno é necessário realizar a leitura da tag “status”. Caso ela seja diferente de 200, é porque aconteceu algum erro, neste caso não é necessário seguir para o passo 2, pois é preciso corrigir o que ocorreu e reenviar as informações para obter o status de 200 e poder realizar a consulta do status do processamento. Caso o retorno tenha vindo com sucesso, é necessário ler a “nsNRec” e guardar este número em seu banco de dados, pois esta é a identificação da nota em nossa API, e serve também para consulta-la em qualquer necessidade.

Passo 2

Com o nsNRec em mãos você irá realizar a consulta do processamento da nota. Para a consulta será enviada na requisição o token, o cnpj do emitente e o nsNRec da nota que deseja consultar o status para saber se a mesma foi autorizada ou não na API. Caso o retorno desta requisição seja o código 200 é porque a consulta foi realizada com sucesso, agora é só ler a tag “chNFe” e “nProt” para guardar em seu banco de dados a chave e o protocolo de autorização da nota.

Exemplo Retorno com Sucesso:

{

"status": 200, "motivo": "Consulta realizada com sucesso", "chNFe": "43161107364617000135550000000099461000094833", "cStat": 100, "nProt": "143160001491309", "xMotivo": "Autorizado o uso da NF-e", "dhRecbto": "2016-11-21T11:19:42", "xml": "<?xml version="1.0" encoding="utf-8"?><nfeProc versao="3.10" xmlns="http://www.portalfiscal.inf.br/nfe"><NFe>...</NFe><protNFe versao="3.10">...</protNFe></nfeProc>"}

Exemplo de Retorno com Rejeição:

{ "status": -2, "motivo": "Nao foi possivel carregar o status da NF-e", "erro": { "cStat": 0, "xMotivo": "Documento não localizado em nosso banco de dados" }}

Se o retorno da requisição da consulta do status for diferente de 200 é porque aconteceu alguma rejeição na nota, neste caso é necessário ler a tag “erro” e salvar as informações das tags “cStat” e “xMotivo”. Para poder exibir a rejeição e ajustar o erro que retornou, neste caso o processo de emissão pode ser encerrado por aqui, pois a nota não foi autorizada, então não poderá ser possível realizar o download do pdf. Depois de ajustar os dados da NFe, é necessário reenviar os dados, começando do passo 1.

Passo 3

Se após a consulta for confirmada a autorização da nota, pode-se seguir para o terceiro passo onde será possível baixar os arquivos XML, JSON e PDF da nota. Para download é necessário enviar o token, a chave da nota, o tipo de ambiente e o tipo de download (X para XML, P para PDF, J para JSON ou XPJ para ambos) e a API retornará o XML do arquivo e a base64 do arquivo PDF.

Exemplo Retorno com Sucesso:

{ "status": 200, "motivo": "Consulta realizada com sucesso",, "chNFe": "44444444444444444444444444444444444444444444", "xml": "<?xml version="1.0" encoding="utf-8"?><nfeProc versao="3.10" xmlns="http://www.portalfiscal.inf.br/nfe"><NFe>...</NFe><protNFe versao="3.10">...</protNFe></nfeProc>", "pdf: "JVBERi0xLjQKJeLjz..."}

Exemplo de Retorno com Rejeição:

{
“status”: -500,
“motivo”: “javax.imageio.IIOException: Error reading PNG image data”
}

Este material foi criado com a intenção de ajudar você a integrar com nossa API de forma mais intuitiva e segura, tratando todos os possíveis erros inesperados.

Estes 3 passos podem ser realizados de maneira automatizada, onde será necessário apenas um clique no botão de enviar dados pelo seu sistema, e a nota autorizada será exibida na tela para o seu cliente caso seja Autorizada. Em nossos exemplos temos o código pronto em diversas linguagens que poderá lhe auxiliar na integração.

Com a API o processo de emissão ficou muito mais rápido e prático, dispensando a necessidade de instalar outros programas ou utilizar recursos de hardware e software do computador, sem falar de outros recursos e benefícios que a API proporciona.

Até a próxima!

Autores: Luan Borges e Max Ferraz

PS: Venha fazer parte de um time de empreendedores que tem feito diferença no mercado com a inovação e agilidade que nossos produtos trazem para junto de sua empresa. Veja os testemunhos e comprove! Acesse http://nstecnologia.com.br/depoimentos