# Restituição do IRPF (Receita Federal)

> Consulta o andamento do pedido de restituição do Imposto de Renda Pessoa Física direto na fonte oficial da Receita Federal. Informe apenas o CPF: quando há restituição liberada, retorna a situação, o lote, a data de disponibilidade e o banco/agência do crédito.

- **Consulta:** `restituicao-irpf`
- **Categoria:** Receita Federal
- **Preço:** R$ 0,36 por consulta
- **Endpoint:** `GET https://app.fontedata.com/api/v1/consulta/restituicao-irpf`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/receita-federal/restituicao-irpf

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Consulta o andamento do pedido de **restituição do Imposto de Renda Pessoa Física** direto no portal oficial da Receita Federal, e devolve o resultado do processamento da declaração — a restituir, a pagar ou sem declaração no exercício. Quando há restituição liberada, traz o **lote**, a **data de disponibilidade** e o **banco/agência** do crédito.
>
> **Você não precisa saber a data de nascimento do contribuinte.** Informe apenas o CPF: a data exigida pela Receita é resolvida automaticamente a partir dele.

## Requisição

### cURL

```bash
curl -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/restituicao-irpf?cpf=SEU_CPF&exercicio=2025&data_nascimento=01%2F01%2F1990"
```

### Python

```python
import requests

resp = requests.get(
    "https://app.fontedata.com/api/v1/consulta/restituicao-irpf",
    params={"cpf": "SEU_CPF", "exercicio": "2025", "data_nascimento": "01/01/1990"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/restituicao-irpf");

url.search = new URLSearchParams({
  "cpf": "SEU_CPF",
  "exercicio": "2025",
  "data_nascimento": "01/01/1990"
}).toString();

const resp = await fetch(url, {
  method: "GET",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| `cpf` | CPF | sim | CPF do contribuinte (11 dígitos). Aceita com ou sem pontuação; o dígito verificador é conferido. | formato: 000.000.000-00 |
| `exercicio` | texto | não | Ano-exercício da declaração, com 4 dígitos (ex.: '2025'). Sem ele, consultamos o exercício CORRENTE, que é o que a maioria dos consulentes quer. | `2025` |
| `data_nascimento` | texto | não | OPCIONAL (DD/MM/AAAA). Não é preciso informar: sem ela, a data é resolvida pelo próprio CPF. Se você já tem a data em cadastro, envie-a — pula uma etapa de enriquecimento e deixa a consulta mais rápida. | `01/01/1990` |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> **Desfecho:** `status` traz a frase pronta (ex.: "Restituição creditada."); `resultado` traz o código da própria Receita (`iar` = imposto a restituir, `iap` = imposto a pagar, `indeterminado` = sem declaração processada).
>
> **Declaração:** `existeDeclaracao` diz se há declaração processada no exercício, `possuiRestituicao` se há restituição liberada, `emFilaRestituicao` se ela está na fila dos próximos lotes, e `situacao`/`observacoes` trazem os textos da fonte já limpos de HTML.
>
> **Crédito:** o objeto `restituicao` traz `lote`, `dataDisponibilidade` e `situacaoRestituicao`; `dadosBancarios` traz `banco`, `agencia`, `conta` e `chavePix` do depósito. `valorRestituicaoOriginal` e `valorRestituicaoCorrigido` vêm quando a fonte os informa.
>
> **Imposto a pagar:** `debitoAutomatico.situacao` informa a situação do débito automático.
>
> Os três sub-objetos (`restituicao`, `dadosBancarios`, `debitoAutomatico`) estão **sempre presentes**: quando a Receita não tem o dado, seus campos vêm em `null` — nunca `null` no lugar do objeto e nunca chave ausente.
>
> **Resultado negativo:** contribuinte sem declaração processada no exercício vem como `existeDeclaracao: false` com o `status` explicando — é resposta legítima, não erro.

### Exemplo de resposta

```json
{
  "status": "string",
  "situacao": "string",
  "exercicio": "number",
  "observacoes": null,
  "restituicao": {
    "lote": null,
    "dataDisponibilidade": null,
    "situacaoRestituicao": null
  },
  "cpfConsultado": "string",
  "dadosBancarios": {
    "banco": null,
    "conta": null,
    "agencia": null,
    "chavePix": null
  },
  "tipoDeclaracao": null,
  "debitoAutomatico": {
    "situacao": null
  },
  "existeDeclaracao": "boolean",
  "nomeContribuinte": "string",
  "emFilaRestituicao": "boolean",
  "possuiRestituicao": "boolean",
  "valorRestituicaoOriginal": null,
  "valorRestituicaoCorrigido": null
}
```

### Schema da resposta

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": [
        "string",
        "null"
      ],
      "description": "Frase-resumo do desfecho, pronta para exibir (ex.: 'Restituição creditada.', 'Declaração processada: imposto a pagar (sem restituição).', 'Nada consta: não há declaração processada para o CPF e exercício informados.')."
    },
    "situacao": {
      "type": [
        "string",
        "null"
      ],
      "description": "Texto da fonte descrevendo a situação da declaração (ex.: 'Os dados da liberação de sua restituição estão descritos abaixo:'). Já vem como texto puro — o HTML e as entidades da origem são removidos."
    },
    "exercicio": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Ano-exercício ao qual a resposta se refere, confirmado pela própria fonte (ex.: 2025). É o exercício que você pediu ou, na ausência do parâmetro, o ano corrente."
    },
    "resultado": {
      "type": [
        "string",
        "null"
      ],
      "description": "Código do resultado do processamento, como a Receita o informa: 'iar' = imposto a restituir, 'iap' = imposto a pagar, 'indeterminado' = sem declaração processada. Para leitura humana, prefira o campo `status`."
    },
    "observacoes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Observações e instruções ao contribuinte, quando a fonte as traz (ex.: telefone da central do banco pagador, aviso de débito automático). Texto puro; o texto de eventuais links é preservado."
    },
    "restituicao": {
      "type": "object",
      "properties": {
        "lote": {
          "type": [
            "string",
            "null"
          ],
          "description": "Lote em que a restituição foi (ou será) paga (ex.: '003')."
        },
        "mensagem": {
          "type": [
            "string",
            "null"
          ],
          "description": "Mensagem adicional da fonte sobre este crédito, quando houver."
        },
        "dataDisponibilidade": {
          "type": [
            "string",
            "null"
          ],
          "description": "Data em que o valor fica disponível no banco, em DD/MM/AAAA."
        },
        "situacaoRestituicao": {
          "type": [
            "string",
            "null"
          ],
          "description": "Situação da restituição segundo a Receita (ex.: 'Creditada')."
        }
      },
      "description": "Dados do crédito da restituição. Sempre presente; campos em null quando não há restituição liberada."
    },
    "cpfConsultado": {
      "type": [
        "string",
        "null"
      ],
      "description": "CPF consultado, formatado com máscara (ex.: '111.111.111-11')."
    },
    "dadosBancarios": {
      "type": "object",
      "properties": {
        "banco": {
          "type": [
            "string",
            "null"
          ],
          "description": "Nome do banco do crédito (ex.: 'ITAU UNIBANCO S.A.')."
        },
        "conta": {
          "type": [
            "string",
            "null"
          ],
          "description": "Conta informada na declaração, quando a fonte a devolve."
        },
        "agencia": {
          "type": [
            "string",
            "null"
          ],
          "description": "Agência informada na declaração."
        },
        "chavePix": {
          "type": [
            "string",
            "null"
          ],
          "description": "Chave PIX usada para o crédito, quando a restituição foi indicada por PIX."
        }
      },
      "description": "Conta em que o crédito da restituição foi (ou será) depositado. Sempre presente; campos em null quando a fonte não informa."
    },
    "tipoDeclaracao": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tipo da declaração, quando informado pela fonte (ex.: retificadora)."
    },
    "debitoAutomatico": {
      "type": "object",
      "properties": {
        "situacao": {
          "type": [
            "string",
            "null"
          ],
          "description": "Situação do débito automático informada pela fonte."
        }
      },
      "description": "Situação do débito automático do imposto a pagar. Sempre presente; campo em null quando não se aplica."
    },
    "existeDeclaracao": {
      "type": "boolean",
      "description": "true = há declaração processada para o CPF neste exercício; false = NADA CONSTA (o contribuinte não declarou nesse ano ou a declaração ainda não entrou na base). false é resultado legítimo, não erro."
    },
    "nomeContribuinte": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nome do contribuinte como consta no cadastro da Receita Federal."
    },
    "emFilaRestituicao": {
      "type": "boolean",
      "description": "true = a restituição está na fila de pagamento dos próximos lotes."
    },
    "possuiRestituicao": {
      "type": "boolean",
      "description": "true = há restituição com situação definida pela fonte (creditada, a ser creditada, em fila etc.); false = sem restituição liberada até o momento (inclui o caso de imposto a pagar)."
    },
    "valorRestituicaoOriginal": {
      "type": [
        "string",
        "null"
      ],
      "description": "Valor original da restituição, como a fonte o informa. null quando a fonte não traz o valor."
    },
    "valorRestituicaoCorrigido": {
      "type": [
        "string",
        "null"
      ],
      "description": "Valor da restituição corrigido (com a atualização aplicada pela Receita até o pagamento). null quando a fonte não traz o valor."
    }
  },
  "description": "Andamento do pedido de restituição do IRPF de um CPF num exercício, direto na fonte oficial e gratuita da Receita Federal (restituicao.receita.fazenda.gov.br). Quando há restituição liberada, traz lote, data de disponibilidade e o banco/agência do crédito. Os sub-objetos `restituicao`, `dadosBancarios` e `debitoAutomatico` estão SEMPRE presentes: quando a fonte não informa, vêm com os campos em null — nunca null no lugar do objeto, nunca chave ausente."
}
```

## Códigos de erro

| Código | Mensagem | Quando acontece |
|---|---|---|
| `400` | Informe um CPF válido (11 dígitos). | CPF ausente, com quantidade de dígitos diferente de 11 ou com dígito verificador inválido. |
| `400` | Exercício inválido para esta consulta. | O ano-exercício enviado não existe para a consulta (ex.: ano futuro), segundo a própria Receita Federal. |
| `400` | Data de nascimento não confere com o cadastro do CPF na fonte. | A Receita Federal não reconhece o par CPF + data de nascimento. Ocorre quando a data enviada está errada e, mais raramente, quando o CPF não existe — a fonte devolve a mesma resposta nos dois casos, e por isso não afirmamos 'nada consta'. |
| `401` | Chave de API ausente ou inválida. | Header X-API-Key não enviado ou não reconhecido. |
| `403` | Saldo insuficiente ou acesso negado a este endpoint. | Conta sem saldo para cobrir a consulta ou sem permissão no catálogo da marca. |
| `408` | A consulta excedeu o tempo limite. Tente novamente. | A fonte oficial demorou além do orçamento de tempo da consulta. |
| `503` | A fonte oficial está indisponível no momento. Tente novamente em instantes. | O portal de restituição da Receita Federal está fora do ar ou recusando consultas. A mensagem traz o endereço oficial da fonte. |

## Quando usar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - Acompanhamento da restituição de clientes por escritórios de contabilidade, em lote
> - Confirmação de crédito e da conta de depósito antes de acionar o contribuinte
> - Comprovação de entrega e processamento da declaração em análise de crédito e cadastro
> - Conferência do exercício corrente durante a temporada de lotes da Receita Federal

---

Página em HTML: https://fontedata.com/docs/receita-federal/restituicao-irpf
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp