---
title: "Solicitar a guia do DIFAL pela API"
description: "Como pedir a GNRE ou o DUA-ES do DIFAL de uma NF-e pela API da NFE.io: rotas, autenticação, parâmetros de pagamento e vencimento, respostas de erro, o webhook com o resultado e a consulta da guia por id."
source_url: https://nfe.io/docs/guias-de-pagamento/como-solicitar/
product: documentacao
last_updated: 2026-11-17
tags: ["how-to", "referencia", "nfe", "emissao", "webhook", "impostos"]
integration: ["api"]
---

# Solicitar a guia do DIFAL pela API

Esta página mostra como pedir a guia de pagamento do DIFAL (`vICMSUFDest`) de uma NF-e autorizada. Para entender que guia é gerada e as limitações do produto, leia antes [Guias de pagamento do DIFAL: conceitos](./conceitos.md).

## 1. Visão geral

1. Cadastre um webhook para os eventos `tax_payment_form`.
2. Envie o pedido por uma das duas rotas.
3. Guarde o `id` da resposta.
4. Receba o webhook com o mesmo `id` e o desfecho da guia. Se precisar, consulte a guia pelo `id` (seção 7).

:::tip Cadastre o webhook antes do pedido
O webhook avisa quando a guia termina, sem você precisar consultar. Veja [Como cadastrar um webhook](../../webhooks/como-cadastrar-consultar-listar-editar-e-excluir.md) e assine `tax_payment_form.created_successfully`, `tax_payment_form.creation_failed` e `tax_payment_form.creation_not_needed`.
:::

## 2. Autenticação

Envie a chave de API da conta no cabeçalho `Authorization`. O `accountId` da rota precisa ser o da conta da chave.

Base da URL: `https://api.nfe.io`.

| Resposta | Causa |
|---|---|
| `401` | Chave ausente ou inválida. Vale para todas as rotas desta página. |
| `403` | A chave é válida, mas não tem permissão para esta API. |

## 3. As duas formas de pedir

| Forma | Rota | Corpo | Quando usar |
|---|---|---|---|
| Por `id` da NF-e | `POST /v1/tax-payment-forms/{accountId}/{companyId}/gnre` | JSON | A NF-e foi emitida pela NFE.io. |
| Por XML | `POST /v1/tax-payment-forms/{accountId}/{companyId}/gnre/xml` | XML `nfeProc` | Você tem o XML completo da NF-e autorizada. |

As duas rotas servem para GNRE e para DUA-ES. A NFE.io escolhe o tipo de guia pela UF de destino da NF-e.

### 3.1. Por `id` da NF-e

```http
POST https://api.nfe.io/v1/tax-payment-forms/{accountId}/{companyId}/gnre
Authorization: <sua-chave-de-api>
Content-Type: application/json
```

```json
{
  "productInvoiceId": "6b1e2f3a4c5d6e7f8a9b0c1d",
  "paymentDate": "2026-11-18",
  "dueDateFrom": 1
}
```

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `productInvoiceId` | string | Sim | `id` da NF-e na NFE.io. A NF-e precisa ser da empresa `{companyId}`. |
| `paymentDate` | data | Não | Data de pagamento. Veja a [seção 4](#4-data-de-pagamento-e-vencimento). |
| `dueDateFrom` | número | Não | Regra para calcular o vencimento. Veja a [seção 4](#4-data-de-pagamento-e-vencimento). |
| `dueDate` | data | Não | Vencimento informado por você. Tem prioridade sobre `dueDateFrom`. |

A NFE.io lê o XML autorizado da NF-e. Se a NF-e não existir na empresa ou não tiver XML autorizado, a resposta é `404`.

### 3.2. Por XML

```http
POST https://api.nfe.io/v1/tax-payment-forms/{accountId}/{companyId}/gnre/xml?paymentDate=2026-11-18&dueDateFrom=1
Authorization: <sua-chave-de-api>
Content-Type: application/xml
```

O corpo é o XML completo da NF-e autorizada: o `nfeProc`, com a `NFe` e o protocolo `protNFe`.

Os parâmetros `paymentDate`, `dueDateFrom` e `dueDate` vão na query e têm o mesmo significado da rota por `id`. Na query, `dueDateFrom` aceita o número ou o nome da opção.

O `companyId` da rota é gravado na guia e volta no webhook. Use o `id` da empresa emitente na NFE.io.

## 4. Data de pagamento e vencimento

### `paymentDate`

- Se você não informar, a NFE.io usa o próximo dia útil a partir de hoje, pelo calendário de São Paulo.
- A data não pode ser anterior a hoje. Uma data passada é recusada com `Payment date cannot be in the past`.

:::warning A data de hoje desta checagem é a do servidor, em UTC
Entre 21h e 0h no horário de Brasília, a data UTC já é o dia seguinte. Nesse intervalo, um `paymentDate` com a data de hoje (Brasília) é recusado. Nesse horário, informe o dia seguinte ou não informe `paymentDate`.
:::

### Vencimento da guia

A NFE.io calcula o vencimento nesta ordem:

1. Se você informar `dueDate` posterior a 01/01/2020, o vencimento é o `dueDate`.
2. Se não, e você informar `dueDateFrom` diferente de `0`, o vencimento segue a tabela abaixo.
3. Se não, o vencimento é a data de emissão da NF-e quando o `paymentDate` é mais de 5 dias depois da emissão. Nos outros casos, o vencimento é o `paymentDate`.

Valores de `dueDateFrom` (enum `eDueDateFrom`):

| Valor | Nome | Vencimento |
|---|---|---|
| `0` | `None` | Sem regra: segue o item 3 acima. |
| `1` | `IssuedOn` | Data de emissão da NF-e (`dhEmi`). |
| `2` | `NextBusinessDay` | Próximo dia útil a partir de hoje, pelo calendário de São Paulo. |
| `3` | `DepartureOn` | Não use: não funciona com NF-e 4.00 (veja o aviso abaixo). |
| `4` | `PaymentOn` | Hoje. Não usa o `paymentDate`. |
| `5` | `Today` | Hoje. |

As opções de vencimento e a data de emissão da NF-e são calculadas no horário de Brasília (UTC-3).

:::warning Não use `DepartureOn`
A opção lê o campo de data de saída do leiaute 2.00 da NF-e (`dSaiEnt`). A NF-e 4.00 traz `dhSaiEnt`, e o vencimento fica sem data. Na GNRE, o pedido é recusado com `Item could not be build`. No DUA-ES, a guia não é gerada. Para vencimento na data de saída, informe a data em `dueDate`.
:::

:::note `PaymentOn` tem o mesmo efeito de `Today`
Apesar do nome, `PaymentOn` não copia o `paymentDate` para o vencimento. Para vencimento igual à data de pagamento, informe o mesmo valor em `dueDate`.
:::

## 5. Respostas e erros

### 200: pedido aceito

```json
{
  "id": "3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b",
  "companyId": "6a889d6f8eb325000111a3fc",
  "accountId": "6a889d6f8eb325000111a3fb"
}
```

Valores fictícios. O `id` identifica a guia e volta em todos os webhooks dela. A guia ainda não está gerada nesse momento.

### 400: pedido recusado

O corpo traz a lista `errors` com uma mensagem. A guia não é criada e nenhum webhook é enviado.

```json
{
  "errors": [
    "Seller and buyer UF are the same. GNRE cannot be issued - invoiceId: 6b1e2f3a4c5d6e7f8a9b0c1d"
  ]
}
```

Quando a NF-e tem mais de um problema, a resposta traz só o primeiro. Corrija e envie de novo para ver o próximo. Mensagens possíveis:

| Mensagem | Causa |
|---|---|
| `Payment date cannot be in the past` | `paymentDate` anterior a hoje. |
| `No NFe provided`, `No NFe infNFe provided`, `No NFe emit provided`, `No NFe emit address provided`, `No NFe dest provided`, `No NFe dest address provided` | Falta um grupo obrigatório no XML da NF-e. |
| `Seller and buyer UF are the same. GNRE cannot be issued - invoiceId: ...` | Operação dentro da mesma UF. |
| `NFe does not have interstate ICMS to pay - invoiceId: ...` | `vICMSUFDest` ausente ou igual a zero. |
| `CNPJ/CPF do emitente ou destinatario contem caracteres invalidos - invoiceId: ...` | CNPJ ou CPF com caracteres que não são letras ou números, ou com mais de 14 posições. |
| `Destination state SP is not currently supported` | Destino em SP. |
| `Invalid city ... for Espirito Santo` | Destino no ES com município fora da lista. Veja [a nota sobre municípios do ES](./conceitos.md#2-requisitos-da-nf-e). |
| `No items to process: infNFE.det has no child` | NF-e sem itens (GNRE). |
| `Invalid NFe emit address` | Endereço do emitente incompleto (GNRE). |
| `Invalid NFe emit tax number: infNFE.emit.CNPJ or infNFE.emit.CPF is not a valid federal tax number` | Emitente sem CNPJ e sem CPF (GNRE). |
| `Item could not be build` | O item da GNRE ficou incompleto. Exemplo: vencimento sem data, com `dueDateFrom` = `3` (`DepartureOn`) em NF-e 4.00. |
| `Could not retrieve a valid NFe XML` | Rota por `id`: o XML da NF-e não pôde ser lido como NF-e autorizada. Exemplo: NF-e cancelada. |
| `Unknown failure while creating request. Please contact support` | Falha inesperada ao montar o pedido. Fale com o suporte. |

Na rota por `id`, `invoiceId` é o `productInvoiceId` enviado. Na rota por XML, ele vem vazio.

Um corpo vazio ou malformado (JSON ou XML que não pode ser lido) também recebe `400`, mas em outro formato: detalhes de validação, com `type`, `title`, `status` e `errors` agrupados por campo.

### 401: conta não autorizada

Além do `401` de chave ausente ou inválida (seção 2), as duas rotas devolvem `401` quando o `accountId` da rota é diferente da conta da chave de API. Nesse caso, a guia não é criada:

```json
{
  "errors": ["This accountId is not authorized for the given authorization"]
}
```

### 404: NF-e não encontrada

Somente na rota por `id`.

```json
{
  "errors": [
    { "code": 404, "message": "Invoice could not be found." }
  ]
}
```

### 500: falha inesperada

O corpo vem no formato de detalhes de problema, com `type`, `title`, `status` e `traceId`. Um exemplo de causa: XML enviado sem o protocolo `protNFe`. Confira o XML. Se o erro continuar, fale com o suporte e informe o `traceId`.

## 6. Receber o resultado

Depois do pedido aceito, a NFE.io envia um destes webhooks, com o mesmo `id` da resposta 200:

| Evento | Quando | Campos principais |
|---|---|---|
| `tax_payment_form.created_successfully` | Guia gerada. | `barCode`, `pdfUrl`, `dueDate`, `paymentDate`, valores |
| `tax_payment_form.creation_failed` | O portal ou a SEFAZ recusou a guia, ou a comunicação falhou. | `errorMessage` |
| `tax_payment_form.creation_not_needed` | A guia não é necessária. | `reasonCode` |

O corpo é achatado na raiz, com o campo `action`. Os campos de cada evento estão em [Catálogo de saída — Outros eventos](../../webhooks/catalogo-saida/catalogo-saida-outros.md#eventos-de-tax_payment_form).

:::warning Baixe o PDF ao receber o webhook
O `pdfUrl` é um link temporário. Em algumas guias, ele expira 48 horas depois do envio do webhook. Baixe e guarde o PDF assim que receber `created_successfully`. Se o link expirar, consulte a guia pelo `id` (seção 7) para obter um link novo.
:::

Cada pedido cria uma guia nova, com outro `id`. Antes de pedir de novo uma guia que terminou em `creation_failed`, leia o alerta de risco de guia em duplicidade em [Etapas do processamento](./conceitos.md#3-etapas-do-processamento): a falha pode ter ocorrido depois de a guia existir no Portal GNRE ou na SEFAZ-ES.

## 7. Consultar a guia

A consulta é só de leitura. Ela usa a conta da chave de API, sem `accountId` nem `companyId` na rota.

```http
GET https://api.nfe.io/v3/frontend/tax-payment-forms/gnre/{id}
Authorization: <sua-chave-de-api>
```

`{id}` é o `id` da resposta do pedido.

Resposta `200` (valores fictícios):

```json
{
  "id": "3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b",
  "cnpj": "11222333000181",
  "name": "Empresa Exemplo Ltda",
  "createdOn": "2026-11-17T14:03:21.123Z",
  "expiresOn": "2026-11-18T00:00:00Z",
  "code": "858000000006120038520261118000000000000000000001",
  "cost": 61.2,
  "error": null,
  "status": "Generated",
  "file": "https://exemplo.nfe.io/guias/guia-exemplo.pdf"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | `id` da guia. |
| `cnpj` | string | CNPJ do emitente da NF-e. |
| `name` | string | Razão social do emitente da NF-e. |
| `createdOn` | data e hora | Momento do pedido. |
| `expiresOn` | data e hora | Data de pagamento da guia (`paymentDate`). Apesar do nome, não é o vencimento. |
| `code` | string ou `null` | Linha digitável (GNRE) ou código de barras (DUA-ES). Vem `null` antes de a guia ser gerada. |
| `cost` | número | Valor total da guia. Antes da geração, é o `vICMSUFDest` da NF-e. |
| `error` | objeto ou `null` | Preenchido quando `status` é `Error` ou `ErrorNotNeeded`. `error.message` traz o motivo. `error.number` não é preenchido e vem `0`. |
| `status` | string | `Created`, `Prepared`, `Transmitted`, `Generated`, `Error` ou `ErrorNotNeeded`. Veja [Etapas do processamento](./conceitos.md#3-etapas-do-processamento). |
| `file` | string ou `null` | Link para baixar o PDF. Vem `null` quando a guia não tem PDF. |

O link em `file` é gerado a cada consulta e expira. Em algumas guias, ele vale 25 minutos. Baixe o PDF logo depois da consulta. Para um link novo, consulte de novo.

Use a versão `v3` da rota. As versões `v1` e `v2` devolvem `cnpj` como número e respondem `404` para guias de emitente com CNPJ alfanumérico.

Se a guia não existir, a resposta é `404`, no formato de detalhes de problema.

## Veja também

- [Guias de pagamento do DIFAL: conceitos](./conceitos.md)
- [Catálogo de eventos de webhook](../../webhooks/catalogo-de-eventos.md)
- [Payloads dos webhooks de emissão](../../webhooks/guias/payloads-de-emissao.md)
