API de DIFAL de saída: pendência de DIFAL por UF de destino (Beta)
Veja, mês a mês e por UF de destino, as NF-e com DIFAL e FCP destacados, a situação da guia de cada nota e o valor em aberto, com o certificado A1 do próprio emitente e sem custódia.
Atualizado em
Beta. A leitura do portal ainda está sendo validada com os primeiros clientes. Se algum número não bater com o portal, escreva para contato@fiscalapi.com.br com o request_id.
POST /api/consultar-difal-saida lista, para um mês e cada UF de destino, as NF-e do emitente com DIFAL (EC 87/2015, LC 190/2022) e FCP destacados, a situação da guia de cada nota (paga, pendente, rejeitada ou sem guia) e o valor em aberto. A consulta usa o certificado A1 (e-CNPJ ou e-CPF) do próprio emitente das notas no Portal da DIFAL, o sistema nacional dos estados para o recolhimento.
- Quem usa: contabilidades e BPO fiscal que têm o A1 dos clientes; e-commerces e marketplaces que vendem a consumidor final em outras UFs.
- Para quê: achar a nota com DIFAL sem guia paga antes que vire débito e dívida ativa na UF de destino.
- Certificado: usado só durante a consulta e nunca armazenado.
- Sem programar: o painel faz a mesma consulta com o arquivo do certificado.
Para calcular o DIFAL de uma operação, use a calculadora de DIFAL.
Resumo
| Item | Valor |
|---|---|
| Endpoint | POST https://api.fiscalapi.com.br/api/consultar-difal-saida |
| Você envia | certificado (A1 do emitente em base64), senha, competencia (AAAA-MM) e, opcional, ufs |
| Volta | Notas, guias e totais por UF de destino, com status de cada UF |
| UFs de destino | AC, AP, DF, GO, MS, MT, RR, RS, SC e SE (limites) |
| Tempo | Até cerca de 70 s com as 10 UFs. Use timeout de 90 s no seu cliente. |
| Certificado guardado? | Não |
Quanto custa cada chamada
Cobra 1 consulta por UF com resposta completa (status = ok), com ou sem nota no mês. UF parcial, com erro ou nao_consultada não é cobrada.
| Plano | Por UF, com créditos do plano | Por UF, com créditos extras |
|---|---|---|
| Starter | R$ 0,10 | R$ 0,12 |
| Pro | R$ 0,065 | R$ 0,085 |
| Enterprise | R$ 0,025 | R$ 0,035 |
As 10 UFs de um mês são 10 consultas: R$ 1,00 no Starter, com os créditos do plano. A consulta não entra nas 10 consultas grátis do mês. Veja Planos e limites.
Autenticação
Envie sua chave no header X-API-Key. Veja Autenticação para detalhes.
Corpo da requisição
Envie um JSON (Content-Type: application/json) com os campos abaixo.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
certificado | string | Sim | Certificado A1 (.pfx/.p12) do emitente das notas, em base64, até 100 KB. e-CNPJ ou e-CPF. |
senha | string | Sim | Senha do certificado. |
competencia | string | Sim | Mês de emissão das notas, no formato AAAA-MM (ex.: 2026-10). Não aceita mês futuro. |
ufs | array de strings | Não | UFs de destino, em sigla (ex.: ["RS", "SC"]). Omitido ou [] = as 10 UFs. |
O certificado tem de ser do emitente das notas: o portal mostra só as notas do titular.
Exemplos
Consultar outubro nas UFs RS e SC
# codifica o certificado em base64 e envia
CERT=$(base64 < certificado.pfx | tr -d '\n')
curl -X POST "https://api.fiscalapi.com.br/api/consultar-difal-saida" \
-H "X-API-Key: fapi_sua_chave_aqui" \
-H "Content-Type: application/json" \
--max-time 90 \
-d "{\"certificado\":\"$CERT\",\"senha\":\"sua-senha\",\"competencia\":\"2026-10\",\"ufs\":[\"RS\",\"SC\"]}"import { readFileSync } from "node:fs";
const certificado = readFileSync("certificado.pfx").toString("base64");
const response = await fetch(
"https://api.fiscalapi.com.br/api/consultar-difal-saida",
{
method: "POST",
headers: {
"X-API-Key": "fapi_sua_chave_aqui",
"Content-Type": "application/json",
},
body: JSON.stringify({
certificado,
senha: "sua-senha",
competencia: "2026-10",
ufs: ["RS", "SC"],
}),
signal: AbortSignal.timeout(90_000),
}
);
const data = await response.json();
for (const uf of data.ufs) {
console.log(uf.uf, uf.status, uf.valor_em_aberto);
}import base64
import requests
with open("certificado.pfx", "rb") as f:
certificado = base64.b64encode(f.read()).decode()
response = requests.post(
"https://api.fiscalapi.com.br/api/consultar-difal-saida",
headers={"X-API-Key": "fapi_sua_chave_aqui"},
json={
"certificado": certificado,
"senha": "sua-senha",
"competencia": "2026-10",
"ufs": ["RS", "SC"],
},
timeout=90,
)
data = response.json()
for uf in data["ufs"]:
print(uf["uf"], uf["status"], uf["valor_em_aberto"])$certificado = base64_encode(file_get_contents('certificado.pfx'));
$response = Http::timeout(90)->withHeaders([
'X-API-Key' => 'fapi_sua_chave_aqui',
])->post('https://api.fiscalapi.com.br/api/consultar-difal-saida', [
'certificado' => $certificado,
'senha' => 'sua-senha',
'competencia' => '2026-10',
'ufs' => ['RS', 'SC'],
]);
$data = $response->json();Os SDKs têm o método pronto: consultarDifalSaida no Node.js e no PHP, consultar_difal_saida no Python.
Resposta
A resposta é plana, sem envelope. Os totais do topo somam as UFs.
| Campo | Tipo | Descrição |
|---|---|---|
request_id | string | Identificador único da requisição. |
fonte | string | Sistema consultado. |
emitente_tipo | string | CNPJ ou CPF do titular do certificado. |
emitente_documento | string | CNPJ ou CPF do titular. |
competencia | string | Mês consultado (AAAA-MM). |
periodo_inicio / periodo_fim | string | Primeiro e último dia do mês (AAAA-MM-DD). |
total_documentos | integer | Notas com DIFAL ou FCP no mês, somando as UFs. |
valor_difal / valor_fcp | number | DIFAL e FCP destacados nas notas. |
valor_em_aberto / notas_em_aberto | number / integer | Imposto sem guia, com guia pendente ou rejeitada (regra). |
valor_a_conferir / notas_a_conferir | number / integer | Pagamento não confirmado pelo portal (ou sem guia no portal em DF, GO e MT). Fora do valor em aberto. |
completo | boolean | true só quando todas as UFs pedidas vieram ok. Com false, os totais podem estar incompletos. |
ufs | array | Uma entrada por UF pedida. Veja abaixo. |
avisos | array de strings | Ressalvas fixas da fonte (as mesmas dos limites). |
creditos_cobrados | integer | Consultas usadas: 1 por UF ok. O preço em R$ está na tabela acima. |
Cada item de ufs
| Campo | Tipo | Descrição |
|---|---|---|
uf | string | UF de destino. |
status | string | Resultado da UF. Veja a tabela abaixo. |
mensagem | string | Vazia no ok, salvo em DF, GO e MT com notas; nos outros, o motivo. |
total_documentos, valor_difal, valor_fcp, valor_em_aberto, notas_em_aberto, valor_a_conferir, notas_a_conferir | Os mesmos totais do topo, só desta UF. | |
notas | array | Notas da UF (campos abaixo). |
guias | array | Guias GNRE da UF ligadas às notas: numero, vencimento_imposto, data_limite_pagamento, uf, tributo, valor e situacao (paga, pendente_pagamento, geracao_rejeitada, aguardando_processamento, substituida ou null). |
Cada item de notas
| Campo | Tipo | Descrição |
|---|---|---|
serie, numero | string | Série e número da NF-e. |
data_emissao, vencimento | string | null | Emissão da nota e vencimento do imposto (AAAA-MM-DD). |
destinatario, uf_destino | string | Nome do destinatário e UF de destino. |
valor_total | number | null | Valor total da nota. |
valor_difal, valor_fcp | number | null | DIFAL e FCP destacados na nota. |
situacao_guia_difal, situacao_guia_fcp | string | Situação da guia de cada tributo. Veja a tabela abaixo. |
em_aberto, valor_em_aberto | boolean, number | Se a nota tem imposto em aberto, e quanto. |
a_conferir, valor_a_conferir | boolean, number | Se a nota tem guia sem pagamento confirmado, e quanto. |
Valores de status da UF
| Status | Significado | É cobrada |
|---|---|---|
ok | UF lida por inteiro, com ou sem nota no mês. | Sim |
parcial | Dados incompletos (ex.: notas lidas, situação das guias não). Os números da UF vêm, mas podem faltar notas ou guias. | Não |
erro | Falha do portal nesta UF. | Não |
nao_consultada | O tempo da consulta acabou antes desta UF. Consulte de novo só ela. | Não |
Valores de situacao_guia_difal e situacao_guia_fcp
| Situação | Significado | Conta como |
|---|---|---|
paga | Guia paga. | Quitado |
sem_guia_no_portal | Nenhuma guia gerada no portal para a nota. | Em aberto (a conferir em DF, GO e MT) |
pendente_pagamento | Guia gerada e ainda não paga. | Em aberto |
geracao_rejeitada | A geração da guia foi rejeitada. | Em aberto |
aguardando_processamento | Guia gerada, em processamento. | A conferir |
substituida | A guia foi substituída por outra. | A conferir |
guia_gerada | Guia gerada, situação não localizada. | A conferir |
desconhecida | O portal mostrou algo fora do padrão. | A conferir |
nao_se_aplica | Tributo zerado na nota. | Nada a pagar |
Em aberto e a conferir
- Só
pagaquita. sem_guia_no_portal,pendente_pagamentoegeracao_rejeitadasomam emvalor_em_aberto.- Exceção: em DF, GO e MT a guia é emitida no sistema da SEFAZ, fora do Portal da DIFAL. Ali a nota
sem_guia_no_portalsoma emvalor_a_conferir, e a UF vem com umamensagemexplicando. - As outras situações com valor somam em
valor_a_conferir: há guia, mas o portal não confirma o pagamento. Elas ficam fora do valor em aberto.
Exemplo de resposta
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"fonte": "Portal da DIFAL - Módulo de Apuração",
"emitente_tipo": "CNPJ",
"emitente_documento": "12345678000199",
"competencia": "2026-10",
"periodo_inicio": "2026-10-01",
"periodo_fim": "2026-10-31",
"total_documentos": 3,
"valor_difal": 650.05,
"valor_fcp": 80.0,
"valor_em_aberto": 370.05,
"notas_em_aberto": 2,
"valor_a_conferir": 0.0,
"notas_a_conferir": 0,
"completo": true,
"ufs": [
{
"uf": "RS",
"status": "ok",
"mensagem": "",
"total_documentos": 3,
"valor_difal": 650.05,
"valor_fcp": 80.0,
"valor_em_aberto": 370.05,
"notas_em_aberto": 2,
"valor_a_conferir": 0.0,
"notas_a_conferir": 0,
"notas": [
{
"serie": "1",
"numero": "1001",
"data_emissao": "2026-10-03",
"vencimento": "2026-10-03",
"destinatario": "MARIA DA SILVA",
"uf_destino": "RS",
"valor_total": 1000.0,
"valor_difal": 100.0,
"valor_fcp": 20.0,
"situacao_guia_difal": "sem_guia_no_portal",
"situacao_guia_fcp": "sem_guia_no_portal",
"em_aberto": true,
"valor_em_aberto": 120.0,
"a_conferir": false,
"valor_a_conferir": 0.0
}
],
"guias": [
{
"numero": "2026100000001",
"vencimento_imposto": "2026-10-10",
"data_limite_pagamento": "2026-10-10",
"uf": "RS",
"tributo": "ICMS DIFAL",
"valor": 300.0,
"situacao": "paga"
}
]
},
{
"uf": "SC",
"status": "ok",
"mensagem": "",
"total_documentos": 0,
"valor_difal": 0.0,
"valor_fcp": 0.0,
"valor_em_aberto": 0.0,
"notas_em_aberto": 0,
"valor_a_conferir": 0.0,
"notas_a_conferir": 0,
"notas": [],
"guias": []
}
],
"avisos": [
"O Portal da DIFAL atende 10 UFs de destino: AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. As demais UFs têm sistema próprio e não são consultadas por esta fonte.",
"Nota 'sem_guia_no_portal' significa que nenhuma guia foi gerada no próprio portal. Guia emitida pelo ERP ou pelo Portal GNRE, e o recolhimento mensal de quem tem inscrição estadual na UF de destino, não aparecem aqui: confira antes de tratar como débito.",
"'a_conferir' marca nota cuja guia existe mas o pagamento não foi confirmado pelo portal (aguardando processamento, substituída ou não localizada) e, em DF, GO e MT, nota sem guia no portal, porque nesses estados a guia é emitida no sistema da SEFAZ. Ela não entra no valor em aberto.",
"A situação de cada guia (paga, pendente, rejeitada) é a informada pelo portal."
],
"creditos_cobrados": 2
}O exemplo mostra uma das três notas de RS. As duas UFs vieram ok, então a chamada cobrou 2 consultas.
Limites
- 10 UFs de destino: AC, AP, DF, GO, MS, MT, RR, RS, SC e SE, as que usam o Portal da DIFAL. As outras UFs têm sistema próprio e não são consultadas. UF fora da lista volta
UF_NAO_ATENDIDA. - Guia emitida fora do portal não aparece. Guia gerada pelo ERP ou pelo Portal GNRE, e o recolhimento mensal de quem tem inscrição estadual na UF de destino, não constam no portal: a nota sai
sem_guia_no_portal. Confira antes de tratar como débito. - Um mês por chamada. Para vários meses, faça uma chamada por
competencia. - Até 30 requisições por minuto por chave.
Códigos de erro
| Código | HTTP Status | Descrição |
|---|---|---|
CERTIFICADO_INVALIDO | 400 | Base64 inválido, arquivo vazio ou acima de 100 KB, senha incorreta, arquivo que não é A1 ou certificado vencido. O detail diz o motivo. |
CERTIFICADO_RECUSADO_PORTAL | 400 | O portal recusou o certificado. |
UF_NAO_ATENDIDA | 400 | UF fora das 10 atendidas, ou ufs só com textos vazios. |
COMPETENCIA_INVALIDA | 400 | Mês futuro. |
| — | 422 | Campo obrigatório ausente ou competencia fora do formato AAAA-MM. |
LIMITE_ATINGIDO | 402 | O saldo (do plano e extras) não cobre as UFs pedidas. A conferência reserva o pior caso: todas as UFs ok. |
RATE_LIMIT_EXCEEDED | 429 | Mais de 30 requisições por minuto na chave. Aguarde (header Retry-After). |
FONTE_INDISPONIVEL | 503 | O portal não respondeu para nenhuma UF. Nada foi cobrado. Tente mais tarde. |
Os erros seguem o formato padrão: o código vem em title e a mensagem em detail.
Perguntas frequentes
Serve para saber se o cliente tem DIFAL em aberto?
Sim, nas 10 UFs atendidas. A rota mostra, nota a nota, o DIFAL e o FCP destacados e se há guia paga no portal. Some valor_em_aberto e veja as notas com em_aberto = true.
Por que a nota aparece "sem guia no portal" se eu já paguei?
Porque a guia foi gerada fora do portal (no ERP ou no Portal GNRE) ou porque a empresa tem inscrição estadual na UF de destino e recolhe por apuração mensal. O portal não enxerga esses pagamentos. Confira na sua apuração antes de pagar de novo.
Em DF, GO e MT a guia do DIFAL é emitida no sistema da SEFAZ, fora do portal. Por isso, nesses três estados, a nota sem guia no portal vem a_conferir, não em aberto.
Preciso do certificado de quem?
Do emitente das notas (e-CNPJ ou e-CPF, tipo A1). A contabilidade usa o A1 de cada cliente, uma chamada por cliente.
A FiscalAPI guarda o certificado?
Não. O certificado e a senha são usados só durante a consulta e descartados ao fim dela.
A consulta gera ou paga a guia?
Não. Ela só lê. Para gerar a guia, use o próprio portal ou o seu ERP.
Quanto custa consultar as 10 UFs de um mês?
10 consultas, uma por UF ok: R$ 1,00 no Starter, R$ 0,65 no Pro e R$ 0,25 no Enterprise, com os créditos do plano. UF que falha não é cobrada.
Tem como testar grátis?
Não pelas consultas grátis do mês: o DIFAL de saída fica de fora, como as outras varreduras de várias UFs. Pela API, a consulta pede plano ou créditos extras, a partir de R$ 50 por mês.
E as outras 17 UFs?
Usam sistemas próprios e ainda não são cobertas.
Pendência de DIFAL por UF · Planos e preços
Esta pagina foi util?
API para baixar o XML do CT-e pela chave de acesso (com certificado)
Baixe o XML completo e autorizado (cteProc) do CT-e, CT-e OS ou GTV-e pela chave de acesso usando o certificado digital A1 de quem participa do documento, sem custódia.
Como consultar NFS-e pela chave de acesso via API
Consulte uma NFS-e do padrão nacional só com a chave de acesso de 50 dígitos, sem certificado digital. Dados da nota em JSON e, se quiser, o PDF do DANFSe.