FiscalAPI
DIFAL (Beta)

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

ItemValor
EndpointPOST https://api.fiscalapi.com.br/api/consultar-difal-saida
Você enviacertificado (A1 do emitente em base64), senha, competencia (AAAA-MM) e, opcional, ufs
VoltaNotas, guias e totais por UF de destino, com status de cada UF
UFs de destinoAC, AP, DF, GO, MS, MT, RR, RS, SC e SE (limites)
TempoAté 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.

PlanoPor UF, com créditos do planoPor UF, com créditos extras
StarterR$ 0,10R$ 0,12
ProR$ 0,065R$ 0,085
EnterpriseR$ 0,025R$ 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.

CampoTipoObrigatórioDescrição
certificadostringSimCertificado A1 (.pfx/.p12) do emitente das notas, em base64, até 100 KB. e-CNPJ ou e-CPF.
senhastringSimSenha do certificado.
competenciastringSimMês de emissão das notas, no formato AAAA-MM (ex.: 2026-10). Não aceita mês futuro.
ufsarray de stringsNãoUFs 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.

CampoTipoDescrição
request_idstringIdentificador único da requisição.
fontestringSistema consultado.
emitente_tipostringCNPJ ou CPF do titular do certificado.
emitente_documentostringCNPJ ou CPF do titular.
competenciastringMês consultado (AAAA-MM).
periodo_inicio / periodo_fimstringPrimeiro e último dia do mês (AAAA-MM-DD).
total_documentosintegerNotas com DIFAL ou FCP no mês, somando as UFs.
valor_difal / valor_fcpnumberDIFAL e FCP destacados nas notas.
valor_em_aberto / notas_em_abertonumber / integerImposto sem guia, com guia pendente ou rejeitada (regra).
valor_a_conferir / notas_a_conferirnumber / integerPagamento não confirmado pelo portal (ou sem guia no portal em DF, GO e MT). Fora do valor em aberto.
completobooleantrue só quando todas as UFs pedidas vieram ok. Com false, os totais podem estar incompletos.
ufsarrayUma entrada por UF pedida. Veja abaixo.
avisosarray de stringsRessalvas fixas da fonte (as mesmas dos limites).
creditos_cobradosintegerConsultas usadas: 1 por UF ok. O preço em R$ está na tabela acima.

Cada item de ufs

CampoTipoDescrição
ufstringUF de destino.
statusstringResultado da UF. Veja a tabela abaixo.
mensagemstringVazia 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_conferirOs mesmos totais do topo, só desta UF.
notasarrayNotas da UF (campos abaixo).
guiasarrayGuias 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

CampoTipoDescrição
serie, numerostringSérie e número da NF-e.
data_emissao, vencimentostring | nullEmissão da nota e vencimento do imposto (AAAA-MM-DD).
destinatario, uf_destinostringNome do destinatário e UF de destino.
valor_totalnumber | nullValor total da nota.
valor_difal, valor_fcpnumber | nullDIFAL e FCP destacados na nota.
situacao_guia_difal, situacao_guia_fcpstringSituação da guia de cada tributo. Veja a tabela abaixo.
em_aberto, valor_em_abertoboolean, numberSe a nota tem imposto em aberto, e quanto.
a_conferir, valor_a_conferirboolean, numberSe a nota tem guia sem pagamento confirmado, e quanto.

Valores de status da UF

StatusSignificadoÉ cobrada
okUF lida por inteiro, com ou sem nota no mês.Sim
parcialDados 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
erroFalha do portal nesta UF.Não
nao_consultadaO tempo da consulta acabou antes desta UF. Consulte de novo só ela.Não

Valores de situacao_guia_difal e situacao_guia_fcp

SituaçãoSignificadoConta como
pagaGuia paga.Quitado
sem_guia_no_portalNenhuma guia gerada no portal para a nota.Em aberto (a conferir em DF, GO e MT)
pendente_pagamentoGuia gerada e ainda não paga.Em aberto
geracao_rejeitadaA geração da guia foi rejeitada.Em aberto
aguardando_processamentoGuia gerada, em processamento.A conferir
substituidaA guia foi substituída por outra.A conferir
guia_geradaGuia gerada, situação não localizada.A conferir
desconhecidaO portal mostrou algo fora do padrão.A conferir
nao_se_aplicaTributo zerado na nota.Nada a pagar

Em aberto e a conferir

  • Só paga quita.
  • sem_guia_no_portal, pendente_pagamento e geracao_rejeitada somam em valor_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_portal soma em valor_a_conferir, e a UF vem com uma mensagem explicando.
  • 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ódigoHTTP StatusDescrição
CERTIFICADO_INVALIDO400Base64 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_PORTAL400O portal recusou o certificado.
UF_NAO_ATENDIDA400UF fora das 10 atendidas, ou ufs só com textos vazios.
COMPETENCIA_INVALIDA400Mês futuro.
—422Campo obrigatório ausente ou competencia fora do formato AAAA-MM.
LIMITE_ATINGIDO402O saldo (do plano e extras) não cobre as UFs pedidas. A conferência reserva o pior caso: todas as UFs ok.
RATE_LIMIT_EXCEEDED429Mais de 30 requisições por minuto na chave. Aguarde (header Retry-After).
FONTE_INDISPONIVEL503O 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?

On this page