Fluxo - Envio Normal da NF-e

A emissão de notas fiscais pode ser realizada em diferentes cenários, como operações de saída para o consumidor final, saída para revenda, entradas, devoluções, entre outros. As Secretarias de Fazenda (SEFAZ) adotam dois modelos de emissão de notas fiscais:

• Síncrono: A resposta é obtida imediatamente na mesma chamada de envio.

• Assíncrono: A SEFAZ processa a solicitação e, após um tempo, disponibiliza a resposta para consulta em uma chamada posterior.

A tabela abaixo detalha o modelo de emissão adotado por cada unidade federativa (UF):

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

• Obter o DANFE da NF-e: /api/nfe/obterpdf

APIs Opcionais 🥈

• Consulta do Documento por Chave de Acesso: /api/nfe/getbychavesSTD/{chave}

• Obter o XML da NF-e: /api/nfe/obterxml

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, Impostos, Pagamento, etc), os preencherá nos campos da nota, e fará a chamada diretamente em nossa API.

Assim que recebermos a chamada, validaremos o arquivo. Se estiver correto, geraremos o XML do documento, totalizaremos os valores dos itens e impostos, e criaremos a chave de acesso, caso não tenha sido enviada. Por fim, assinaremos o arquivo para transmiti-lo à 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

• descricaoStatusSEFAZ: Retorno Autoriza 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,
  },
  "acoes": {
    "corrigirDocumento": false,
    "cancelar": false,
    "enviarContingencia": false,
    "tentarNovamenteMaisTarde": false,
    "entrarEmContatoComSuporteImediatamente": false
  },
  "excecao": null
}

Descrição dos 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.

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:

• acoes: corrigirDocumento: Retorno true;

• dadosDoDocumento: documentoComErro: 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,
    "urlConsultaViaQRCode": null,
    "urlConsultaViaChaveDeAcesso": 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 a chaveDeAcesso e, opcionalmente, oiddo 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 Chave de Acesso. No retorno da chamada, verificaremos os campos statuse descricaoSEFAZ para identificarmos o status atual do documento.

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.

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.