Fluxo - Envio Normal da NF-e

A emissão da nota pode ser utilizada em diversos cenários como operação de saída para um consumidor final, saída para uma revenda, uma entrada, uma devolução, entre outras.

Algumas SEFAZes utilizam um modelo de emissão de notas síncrono e outras utilizam o modelo assíncrono:

• Síncrono: Neste modelo, a resposta é obtida na mesma chamada de envio;

• Assíncrono: Neste modelo, a chamada é feita, a SEFAZ levará um tempo para processar e então disponibilizará a resposta para consulta em outro método.

A tabela abaixo lista o modelo de emissão que cada UF adota:

Modelo	UFs
Síncrono	AM, CE, GO, MG, MS, MT, PE, PR, RS, SVAN, SVRS, SVC-AN e SVC-RS
Assíncrono	SP e BA

O fluxo demonstrado a seguir trata a emissão da nota dentro da integração com a InvoiSys.

APIs Essenciais 💡

• Envio da NF-e: /api/nfe/envio

• DANFE da NF-e: /api/nfe/getdanfe/{id}

APIs Opcionais 🥈

• Consulta do Documento por ID: /api/nfe/{id}

• DANFE da NF-e com Assinatura: /api/nfe/getdanfe

Etapas e suas APIs

Para uma melhor leitura do fluxo, separamos ele em algumas partes, porém você consegue vê-lo completo por aqui 📝.

1) Emissão da NF-e

Antes de iniciamos a emissão da nota, é necessário estar com um token de acesso válido, pois este será utilizado no cabeçalho da chamada da API de Envio. Tendo este em mãos, podemos partir para a emissão da nota.

Você irá gerar os dados da operação (Destinatário, Produtos, Pagamento, etc), os preencherá nos campos da nota, e fará a chamada diretamente em nossa API.

Assim que recebermos a chamada, o arquivo será validado por nós. Se estiver correto, geraremos o XML do documento, assinaremos o mesmo, e o transmitiremos a SEFAZ.

2) Retorno da chamada

Todo documento enviado para a SEFAZ gera um mensagem de retorno. Esta mensagem será recebida por nós, e em seguida retornaremos na mesma chamada da API juntamente com os dados do documento e suas respectivas ações. É com base nesse retorno que entendemos o que deve ser feito após a emissão da NF-e.

Nele existem algumas informações que podem ser interessantes você guardar, como a chaveDeAcesso e o id do documento criado em nossa base, pois elas são informações fundamentais em outras APIs.

Se você está emitindo em SP ou BA, por favor, veja o tópico referente ao retorno para o modelo assíncrono. Caso esteja emitindo nas demais UFs, confira o tópico a seguir.

2.1) Síncrono

Resumidamente, com base no retorno, podemos chegar a 3 cenários:

a) Autorização da NF-e; b) Rejeição na NF-e; c) Exceção na comunicação com a SEFAZ;

a) Autorização da NF-e

Para identificarmos que a operação foi um sucesso, nós iremos observar algumas tags e seus retornos:

• Tags do bloco acoes :

• corrigirDocumento : Retorno false.

• codigoStatusSEFAZ : Retorno 100 (Autorizado o uso da NF-e);

• documentoComErro : Retorno false.

A seguir temos um exemplo de autorização do documento

Response code: 201 Created

{
  "dadosDoDocumento": {
    "id": 32194,
    "chaveDeAcesso": "35210517921427000125550010000023511123412346",
    "dataHoraEmissao": "2021-05-12T15:14:49.5185408Z",
    "dataDeAutorizacao": null,
    "documentoComErro": false,
    "codigoStatusSEFAZ": "100",
    "descricaoStatusSEFAZ": "Autorizado o uso da NF-e",
    "protocoloSEFAZ": null,
    "urlConsultaViaQRCode": null,
    "urlConsultaViaChaveDeAcesso": null,
    "codigoMensagemSEFAZ": null,
    "descricaoMensagemSEFAZ": null
  },
  "acoes": {
    "corrigirDocumento": false,
    "cancelar": false,
    "enviarContingencia": false,
    "tentarNovamenteMaisTarde": false,
    "entrarEmContatoComSuporteImediatamente": false
  },
  "excecao": null
}

descrição doa campos do retorno:

"dadosDoDocumento": Grupo onde serão retornadas as informações da NF-e após processamento. 
   
     "id": ID gerado pela plataforma da Invoisys. O ID é único por nota, é necessário que a aplicação do integrador armazene esse dado pois o mesmo será utilizado em rotinas com outras APIs. 

    "chaveDeAcesso": Chave de acesso da NF-e.

    "dataHoraEmissao": Data e hora da emissão da NF-e.

    "dataDeAutorizacao": Data e hora de autorização de NF-e.

    "documentoComErro": Campo que indica se o documento está com erro.

    "codigoStatusSEFAZ": Código do status do documento de acordo com a SEFAZ. 

    "descricaoStatusSEFAZ": Descrição do status do documento de acordo com a SEFAZ.

    "protocoloSEFAZ": Protocolo da requisição na SEFAZ.

    "urlConsultaViaQRCode": URL para consulta do QR Code na SEFAZ (NFC-e).

    "urlConsultaViaChaveDeAcesso": URL de consulta da chave de acesso da NF-e na SEFAZ.

    "codigoMensagemSEFAZ": código da mensagem da SEFAZ do status do documento.

    "descricaoMensagemSEFAZ": Descrição da mensagem da SEFAZ do status do documento. 

Bloco de Ações: 

O sistema Invoisys interpreta o retorno da SEFAZ e complementa com um "bloco de ações", exibindo ao sistema integrador diversas orientações para guiar os próximos passos da operação: 

  },
  "acoes": {
    "corrigirDocumento": false/true, Indica se o documento precisa ou não ser corrigido.

    "cancelar": false/true, Indica se o documento precisa ou não ser cancelado/Inutilizado.

    "enviarContingencia": false/true, Indica se será necessário emitir eo próximo documento em modo de contingência. 

    "tentarNovamenteMaisTarde": false/true, Indica se houve um timeout e será necessário tentar novamente mais tarde.

    "entrarEmContatoComSuporteImediatamente": false/true, erro desconhecido, necessário contatar o suporte. 
  },
  "excecao": Descrição de erro, caso tenha ocorrido uma exceção na requisição. 
}

Impressão da NF-e

Impressão da NF-e

Se a nota estiver autorizada, então podemos realizar a impressão do DANFE. Você pode utilizar nossa API de Impressão do DANFE ou, se preferir, utilizar o seu modelo de impressão.

Nós também possuímos uma API para obter o DANFE com a assinatura no canhoto. Você pode conferir os detalhes dela em: /api/nfe/getdanfe

Minha nota foi autorizada, mas estava com uma informação errada! 😓

Nesse caso, você pode fazer uma carta de correção (CC-e) indicando qual informação deverá ser alterada. Note que a CC-e não irá alterar nada no XML. Ela será um complemento para a NF-e e poderá ser impressa juntamente com o DANFE. Veja o embasamento legal aqui:

Cláusula décima quarta-A Após a concessão da Autorização de Uso da NF-e, de que trata a cláusula sétima, o emitente poderá sanar erros em campos específicos da NF-e, por meio de Carta de Correção Eletrônica - CC-e, transmitida à administração tributária da unidade federada do emitente, desde que o erro não esteja relacionado com:

I - as variáveis que determinam o valor do imposto tais como: base de cálculo, alíquota, diferença de preço, quantidade, valor da operação ou da prestação;

II - a correção de dados cadastrais que implique mudança do remetente ou do destinatário;

III - a data de emissão ou de saída.

b) Rejeição da NF-e

Alguns imprevistos ocorrem, e sua nota foi rejeitada pela SEFAZ, mas não se preocupe, pois te instruiremos como tratar uma rejeição.

Para identificarmos que foi uma rejeição, devemos observar se o campo:

• acoes: corrigirDocumento: Retorno true.

Se sim, então precisamos entender qual foi a rejeição. Para isso, podemos checar os seguintes blocos:

• dadosDoDocumento: codigoStatusSEFAZ: Retorno <código>;

• dadosDoDocumento: descricaoStatusSEFAZ: Retorno <descrição>.

No exemplo a seguir vemos uma nota que foi rejeitada por estar com um NCM inexistente:

Response code: 201 Created

{
  "dadosDoDocumento": {
    "id": 1121,
    "chaveDeAcesso": "35191117921427000125550010000000011123412343",
    "dataHoraEmissao": "2019-11-12T13:50:01.1774725Z",
    "dataDeAutorizacao": null,
    "documentoComErro": true,
    "codigoStatusSEFAZ": "778",
    "descricaoStatusSEFAZ": "Rejeição: Informado NCM inexistente [nItem: 1]",
    "protocoloSEFAZ": null,
    "urlConsultaViaQRCode": null,
    "urlConsultaViaChaveDeAcesso": null
  },
  "acoes": {
    "corrigirDocumento": true,
    "cancelar": false,
    "enviarContingencia": false,
    "tentarNovamenteMaisTarde": false,
    "entrarEmContatoComSuporteImediatamente": false
  },
  "excecao": null
}

Devemos então corrigir o documento e o reenviá-lo da mesma maneira que fizemos na primeira etapa do envio. Se tudo estiver certo com a nota, então a SEFAZ autorizará a mesma e poderemos prosseguir para a impressão do DANFE.

c) Exceção na comunicação com a SEFAZ

Sabemos que algumas vezes a SEFAZ pode estar intermitente ou até mesmo fora do ar, entretanto, em alguns casos a operação não pode parar.

Para isso existem alguns métodos para envio em contingência. Você pode conferir os detalhes em: Fluxo - Envio Contingência da NF-e.

2.2) Assíncrono

Para identificarmos que a emissão foi realizada, devemos observar se a tag a seguir:

• codigoStatusSEFAZ: Retorno 103.

• descricaoSEFAZ: Retorno Lote recebido com sucesso.

Ela sinaliza que a nossa solicitação foi aceita para processamento da SEFAZ. A seguir temos um exemplo de retorno da chamada assíncrona.

Response code: 201 Created

{
  "dadosDoDocumento": {
    "id": 1309,
    "chaveDeAcesso": "35191107544236000138550020000010111123412349",
    "dataHoraEmissao": "2019-11-06T15:11:47.4225812Z",
    "dataDeAutorizacao": null,
    "documentoComErro": false,
    "codigoStatusSEFAZ": "103",
    "descricaoStatusSEFAZ": "Lote recebido com sucesso",
    "protocoloSEFAZ": null,
  },
  "acoes": {
    "corrigirDocumento": false,
    "cancelar": false,
    "enviarContingencia": false,
    "tentarNovamenteMaisTarde": false,
    "entrarEmContatoComSuporteImediatamente": false
  },
  "excecao": null
}

Após termos o retorno da chamada, como falamos anteriormente, é importante armazenar o id e a chaveDeAcesso do documento, pois os utilizaremos para consultarmos o status da nota.

Consultando o status da nota

Para sabermos qual o status da nota, podemos utilizar a API de Consulta por ID. No retorno da chamada, verificaremos os campos statuse descricaoSEFAZ para identificarmos o status atual do documento

https://api.invoisys.com.br/api/nfe

GET No ambiente Sandbox: https://sandbox-api.invoisys.com.br /api/nfe/{id}:

Consulta de NF-e por ID

Path Parameters

Name	Type	Description
"id"	integer	Id do do documento

200

Exemplo

 "statusSEFAZ": "100",
 "descricaoSEFAZ": "Autorizado o uso da NF-e",

a) Autorização da NF-e

Para identificarmos que a operação foi um sucesso, nós iremos observar algumas tags e seus retornos:​

• status: key : Retorno 0;

• status: value : Retorno "Autorizado".

• statusSEFAZ: Retorno <código>;

• descricaoSEFAZ: Retorno <descrição>.

Response code: 200 OK

{
  "id": 1309,
  "createDate": "2019-11-06T15:11:47.673",
  "modifyDate": "2019-11-06T15:11:49.93",
  "chaveDeAcesso": "35191107544236000138550000000010111123412349",
  "codigoAleatorioNF": 12341234,
  ...
  "serie": 2,
  "numero": 1011,
  "dataHoraEmissao": "2019-11-06T15:11:47.423",
  ...
  "erro": false,
  "statusSEFAZ": "100",
  "descricaoSEFAZ": "Autorizado o uso da NF-e",
  ...
  "protocoloDeAutorizacao": "135190008010450",
  "status": {
    "key": 0,
    "value": "Autorizado"
  },
  ...
}

b) Rejeição da NF-e

Caso a nota tenha sido rejeitada pela SEFAZ, podemos checar pelos campos do bloco de ações abaixo:

• status: key: Retorno 3;

• status: value: Retorno erro;

• erro: Retorno true.

• corrigirDocumento : Retorno true.

Se sim, para podermos identificar qual foi a rejeição, verifique os campos no grupo "dadosDoDocumento" abaixo, onde constam o código retornado pela SEFAZ, junto de sua descrição:

• statusSEFAZ: Retorno <código>;

• descricaoSEFAZ: Retorno <descrição>.

Abaixo temos um exemplo de retorno para uma nota com rejeição:

Response code: 200 OK

{
  "id": 1310,
  "createDate": "2019-11-06T16:14:10.59",
  "modifyDate": "2019-11-06T16:14:12.24",
  "chaveDeAcesso": "35191107544236000138550020000010121123412346",
  "codigoAleatorioNF": 12341234,
  ...
  "serie": 2,
  "numero": 1012,
  "dataHoraEmissao": "2019-11-06T16:14:10.363",
  ...
  "erro": true,
  "statusSEFAZ": "778",
  "descricaoSEFAZ": "Rejeição: Informado NCM inexistente [nItem:1]",
  ...
  "status": {
    "key": 3,
    "value": "Erro"
  },
  ...
}

Devemos então corrigir o documento e o reenviá-lo na mesma numeração, da mesma maneira que fizemos na primeira etapa do envio.

c) Lote Recebido

Um documento pode ser consultado antes dele ser processado pela SEFAZ. Os campos a serem observados são:

• status: key: Retorno 6;

• status: value: Retorno Aguardando Consulta Lote.

Response code: 200 OK

{
  "id": 1310,
  "createDate": null,
  "modifyDate": null,
  "chaveDeAcesso": null,
  "codigoAleatorioNF": null,
  ...
  "serie": 2,
  "numero": 1012,
  "dataHoraEmissao": "2019-11-06T16:14:10.363",
  ...
  "erro": null,
  "statusSEFAZ": null,
  "descricaoSEFAZ": null,
  ...
  "status": {
    "key": 6,
    "value": "Aguardando Consulta Lote"
  },
  ...
}

Quando isto ocorrer, devemos realizar novamente a rotina de consulta após um período de tempo, para verificar o status do documento.

Terminamos esta etapa 😁. Para seguir, basta selecionar a card abaixo.