---
title: "Guias de pagamento do DIFAL: conceitos"
description: "O que a NFE.io gera como guia de pagamento a partir de uma NF-e (GNRE ou DUA-ES do DIFAL), para quais UFs, etapas do processamento, quando a guia não é necessária e o que o produto não faz."
source_url: https://nfe.io/docs/guias-de-pagamento/conceitos/
product: documentacao
last_updated: 2026-11-17
tags: ["conceitos", "nfe", "impostos"]
integration: ["api"]
---

# 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](./como-solicitar.md).

## 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 `vICMSUFDest` da 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 `vICMSUFDest` maior 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](./como-solicitar.md#5-respostas-e-erros).

:::note Município do Espírito Santo
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:

1. **Pedido aceito.** A NFE.io valida a NF-e e monta os dados da guia.
2. **Transmissão.** A NFE.io envia os dados ao Portal GNRE ou à SEFAZ-ES.
3. **Consulta do resultado.** A NFE.io consulta o resultado até a guia ficar pronta.
4. **Notificação.** A NFE.io envia o webhook `tax_payment_form` com o desfecho.

Cada guia tem um status. A [consulta por `id`](./como-solicitar.md#7-consultar-a-guia) 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.

:::warning Risco de guia em duplicidade
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.
:::

:::tip Não recebeu nenhum dos três webhooks?
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.

## Veja também

- [Solicitar a guia do DIFAL pela API](./como-solicitar.md)
- [Catálogo de saída — Outros eventos (`tax_payment_form`)](../../webhooks/catalogo-saida/catalogo-saida-outros.md#eventos-de-tax_payment_form)
- [Payloads dos webhooks de emissão](../../webhooks/guias/payloads-de-emissao.md)
