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.
1. Visão geral
- Cadastre um webhook para os eventos
tax_payment_form. - Envie o pedido por uma das duas rotas.
- Guarde o
idda resposta. - Receba o webhook com o mesmo
ide o desfecho da guia. Se precisar, consulte a guia peloid(seção 7).
O webhook avisa quando a guia termina, sem você precisar consultar. Veja Como cadastrar um webhook 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
POST https://api.nfe.io/v1/tax-payment-forms/{accountId}/{companyId}/gnre
Authorization: <sua-chave-de-api>
Content-Type: application/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. |
dueDateFrom | número | Não | Regra para calcular o vencimento. Veja a seção 4. |
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
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.
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:
- Se você informar
dueDateposterior a 01/01/2020, o vencimento é odueDate. - Se não, e você informar
dueDateFromdiferente de0, o vencimento segue a tabela abaixo. - 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 é opaymentDate.
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).
DepartureOnA 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.
PaymentOn tem o mesmo efeito de TodayApesar 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
{
"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.
{
"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. |
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:
{
"errors": ["This accountId is not authorized for the given authorization"]
}
404: NF-e não encontrada
Somente na rota por id.
{
"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.
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: 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.
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):
{
"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. |
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.