Guias de pagamento do DIFAL: conceitos
A NFE.io gera a guia de pagamento do ICMS devido à UF de destino de uma NF-e autorizada. Esse valor é o campo vICMSUFDest do total da NF-e, conhecido como DIFAL. Você pede a guia pela API. O resultado chega por webhook, com o PDF e a linha digitável. Você também pode consultar a guia pelo id.
Para fazer o pedido, veja Solicitar a guia do DIFAL pela API.
1. Que guia é gerada
O tipo de guia depende da UF do destinatário da NF-e (dest/enderDest/UF):
| UF de destino | Guia | Onde a guia é gerada |
|---|---|---|
| ES | DUA, com a descrição "DUA Difal" | SEFAZ-ES |
| SP | Não suportada: o pedido é recusado | — |
| Demais UFs | GNRE | Portal GNRE |
Na GNRE, a NFE.io monta uma guia com um item:
- código de receita
100102; - valor igual ao
vICMSUFDestda NF-e; - mês e ano de referência iguais aos da data de vencimento da guia.
O documento de origem e os campos extras da GNRE seguem as regras de cada UF. A NFE.io aplica essas regras automaticamente.
No DUA do Espírito Santo, o valor também é o vICMSUFDest, e o mês de referência é o mês de emissão da NF-e.
O ambiente da guia segue o ambiente da NF-e (tpAmb). Uma NF-e de homologação gera uma guia de homologação.
2. Requisitos da NF-e
A NFE.io recusa o pedido, sem criar a guia, quando a NF-e:
- não é interestadual (UF do emitente igual à UF do destinatário);
- não tem
vICMSUFDestmaior que zero; - tem destino em SP;
- tem destino no ES e o nome do município do destinatário (
xMun) não está na lista de municípios do ES (veja a nota abaixo); - só na GNRE: não tem itens, endereço completo do emitente (
xLgr,nro,xBairro,xMun,UF) ou CNPJ/CPF do emitente; - tem CNPJ ou CPF do emitente ou do destinatário com caracteres que não são letras ou números.
A lista completa de mensagens de recusa está em Solicitar a guia do DIFAL pela API.
A NFE.io compara o xMun do destinatário, em letras maiúsculas, com uma lista de nomes de municípios do ES escritos sem acento. Um nome com acento, como Vitória, não é encontrado e o pedido é recusado com a mensagem Invalid city VITÓRIA for Espirito Santo.
3. Etapas do processamento
O pedido é assíncrono. A API responde com o id da guia. A geração continua em segundo plano:
- Pedido aceito. A NFE.io valida a NF-e e monta os dados da guia.
- Transmissão. A NFE.io envia os dados ao Portal GNRE ou à SEFAZ-ES.
- Consulta do resultado. A NFE.io consulta o resultado até a guia ficar pronta.
- Notificação. A NFE.io envia o webhook
tax_payment_formcom o desfecho.
Cada guia tem um status. A consulta por id devolve o status atual. A tabela mostra os status e o webhook de cada desfecho:
| Status | Significado | Webhook |
|---|---|---|
Created | Registro inicial. No pedido pela API, a guia já é gravada como Prepared. | — |
Prepared | Pedido aceito e dados da guia montados. | — |
Transmitted | Dados recebidos pelo Portal GNRE ou pela SEFAZ-ES, com número de recibo. | — |
Generated | Guia gerada, com PDF e linha digitável. | created_successfully |
Error | O portal ou a SEFAZ recusou a guia, ou a comunicação falhou. | creation_failed |
ErrorNotNeeded | A guia não é necessária (veja a seção 4). | creation_not_needed |
Enquanto o Portal GNRE informa que a guia ainda está em processamento, a NFE.io consulta de novo a cada 10 segundos, até 100 vezes.
Em geral, uma falha de comunicação com o Portal GNRE ou com a SEFAZ-ES não gera nova tentativa: a guia termina em Error e você recebe creation_failed. Algumas falhas inesperadas geram nova tentativa automática.
A falha pode acontecer depois da transmissão, na consulta do resultado. Nesse caso, a guia pode já existir no Portal GNRE ou na SEFAZ-ES, mesmo com creation_failed. Um novo pedido gera outra guia para a mesma NF-e. Antes de pedir de novo, fale com o suporte e informe o id da guia.
Confirme que o webhook está cadastrado para os eventos tax_payment_form. Se estiver, fale com o suporte e informe o id da guia.
4. Quando a guia não é necessária
A guia termina em ErrorNotNeeded e você recebe creation_not_needed nestes casos:
reasonCode | Motivo |
|---|---|
1 (BelowMinimalValue) | O Portal GNRE recusou a guia porque o valor está abaixo do mínimo que a UF aceita. |
0 (Undefined) | O valor total a recolher da guia é zero. |
O valor mínimo é definido pela UF de destino e informado pelo Portal GNRE. A NFE.io não guarda essa tabela.
O motivo BelowMinimalValue só ocorre na GNRE. O DUA do Espírito Santo não tem esse desfecho.
5. O que o produto não faz
- Não gera a guia na emissão da NF-e. Nada no fluxo de emissão da NF-e chama a geração da guia. Você precisa pedir a guia depois da autorização da NF-e.
- Não gera guia de FCP nem de ICMS-ST. A guia usa só o
vICMSUFDest. O FCP da UF de destino (vFCPUFDest) e o ICMS-ST não entram na guia. - Não agrupa NF-e. Cada pedido gera uma guia para uma NF-e.
- Não evita guia duplicada. Cada pedido cria uma guia nova, mesmo que já exista guia para a mesma NF-e.
- Não acompanha o pagamento. Nenhum status indica que a guia foi paga.
- Não acompanha o cancelamento da NF-e. Se a NF-e for cancelada depois, a guia não muda.