Pular para o conteúdo principal

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​

  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).
Cadastre o webhook antes do pedido

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.

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

3. As duas formas de pedir​

FormaRotaCorpoQuando usar
Por id da NF-ePOST /v1/tax-payment-forms/{accountId}/{companyId}/gnreJSONA NF-e foi emitida pela NFE.io.
Por XMLPOST /v1/tax-payment-forms/{accountId}/{companyId}/gnre/xmlXML nfeProcVocê 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
}
CampoTipoObrigatórioDescrição
productInvoiceIdstringSimid da NF-e na NFE.io. A NF-e precisa ser da empresa {companyId}.
paymentDatedataNãoData de pagamento. Veja a seção 4.
dueDateFromnúmeroNãoRegra para calcular o vencimento. Veja a seção 4.
dueDatedataNãoVencimento 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.
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):

ValorNomeVencimento
0NoneSem regra: segue o item 3 acima.
1IssuedOnData de emissão da NF-e (dhEmi).
2NextBusinessDayPróximo dia útil a partir de hoje, pelo calendário de São Paulo.
3DepartureOnNão use: não funciona com NF-e 4.00 (veja o aviso abaixo).
4PaymentOnHoje. Não usa o paymentDate.
5TodayHoje.

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).

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.

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​

{
"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:

MensagemCausa
Payment date cannot be in the pastpaymentDate 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 providedFalta 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 supportedDestino em SP.
Invalid city ... for Espirito SantoDestino no ES com município fora da lista. Veja a nota sobre municípios do ES.
No items to process: infNFE.det has no childNF-e sem itens (GNRE).
Invalid NFe emit addressEndereço do emitente incompleto (GNRE).
Invalid NFe emit tax number: infNFE.emit.CNPJ or infNFE.emit.CPF is not a valid federal tax numberEmitente sem CNPJ e sem CPF (GNRE).
Item could not be buildO item da GNRE ficou incompleto. Exemplo: vencimento sem data, com dueDateFrom = 3 (DepartureOn) em NF-e 4.00.
Could not retrieve a valid NFe XMLRota 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 supportFalha 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:

EventoQuandoCampos principais
tax_payment_form.created_successfullyGuia gerada.barCode, pdfUrl, dueDate, paymentDate, valores
tax_payment_form.creation_failedO portal ou a SEFAZ recusou a guia, ou a comunicação falhou.errorMessage
tax_payment_form.creation_not_neededA 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.

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: 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"
}
CampoTipoDescrição
idstringid da guia.
cnpjstringCNPJ do emitente da NF-e.
namestringRazão social do emitente da NF-e.
createdOndata e horaMomento do pedido.
expiresOndata e horaData de pagamento da guia (paymentDate). Apesar do nome, não é o vencimento.
codestring ou nullLinha digitável (GNRE) ou código de barras (DUA-ES). Vem null antes de a guia ser gerada.
costnúmeroValor total da guia. Antes da geração, é o vICMSUFDest da NF-e.
errorobjeto ou nullPreenchido quando status é Error ou ErrorNotNeeded. error.message traz o motivo. error.number não é preenchido e vem 0.
statusstringCreated, Prepared, Transmitted, Generated, Error ou ErrorNotNeeded. Veja Etapas do processamento.
filestring ou nullLink 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​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.