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

URL: https://docs.fiscalapi.com.br/docs/difal/consultar-difal-saida
Atualizado em 16/11/2026

<Callout type="info">
  **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](mailto:contato@fiscalapi.com.br) com o `request_id`.
</Callout>

`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](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=difal) faz a mesma consulta com o arquivo do certificado.

Para calcular o DIFAL de uma operação, use a [calculadora de DIFAL](https://fiscalapi.com.br/calculadora-difal/?utm_source=docs\&utm_medium=docs\&utm_campaign=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](#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](/docs/referencia/plans-and-limits).

## ## Autenticação

Envie sua chave no header `X-API-Key`. Veja [Autenticação](/docs/getting-started/authentication) 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.                      |

<Callout type="warn">
  O certificado tem de ser do emitente das notas: o portal mostra só as notas do titular.
</Callout>

## ## Exemplos

### ### Consultar outubro nas UFs RS e SC

<Tabs items="[&#x22;curl&#x22;, &#x22;JavaScript&#x22;, &#x22;Python&#x22;, &#x22;PHP&#x22;]">
  <Tab value="curl">
    ```bash
    # 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\"]}"
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    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);
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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"])
    ```
  </Tab>

  <Tab value="PHP">
    ```php
    $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();
    ```
  </Tab>
</Tabs>

Os SDKs têm o método pronto: `consultarDifalSaida` no [Node.js](https://www.npmjs.com/package/fiscalapi-br) e no [PHP](https://packagist.org/packages/fiscalapi-br/fiscalapi-php), `consultar_difal_saida` no [Python](https://pypi.org/project/fiscalapi-br/).

## ## 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](#em-aberto-e-a-conferir)).                   |
| `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](#limites)).                                          |
| `creditos_cobrados`                     | integer          | Consultas usadas: 1 por UF `ok`. O preço em R$ está na [tabela acima](#quanto-custa-cada-chamada).     |

### ### 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ó `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

```json
{
  "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](/docs/referencia/error-handling): 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.
