Receita Federal - Consulta de Restituição

O que é#

A consulta de restituição do Imposto de Renda Pessoa Física (IRPF) permite verificar a situação da restituição de um contribuinte junto à Receita Federal do Brasil.

A consulta retorna informações sobre o status da restituição, valores, dados bancários para crédito e situação do processamento da declaração.

Sobre a requisição#

Método: POST

Endereço: URL Base + /api/maestro/receita/restituicao

URL Base: https://api.plexi.com.br/

Parâmetros do header#

Nome	Tipo	Obrigatório?	Descrição
Authorization	String	Sim	Chave de API gerada no cadastro no Plexi, prefixada com `Bearer`
Callback	String	Não	URL para onde o resultado da requisição será enviado via HTTP POST.

Parâmetros do body#

Nome	Tipo	Obrigatório?	Descrição
cpf	string	Sim	CPF do contribuinte a ser pesquisado.
dataNascimento	string	Sim	Data de nascimento do contribuinte no formato DD/MM/AAAA.
anoExercicio	integer	Sim	Ano do exercício fiscal a ser consultado (ex: 2025).

Estrutura da resposta#

Status	Significado	Descrição	Informações retornadas
201	Created	Solicitação criada	Campo requestId, com o ID da requisição criada.
422	Unprocessable Entity	A solicitação contém erro	Em quais campos houve erro.

Exemplos de retornos quando você faz a requisição:

Status 201

A consulta recebida com sucesso e será processada. Com o ID retornado você pode consultar se já houve resposta.

JSON

{
  "requestId": "1fdd4247-4f98-4113-887a-b182117b0e42"
}

Status 422

Significa que ocorreu um erro de validação dos dados enviados.

JSON

{
  "message": "The given data was invalid.",
  "errors": {
    "cpf": [
      "O campo cpf é obrigatório."
    ],
    "nome": [
      "O campo nome é obrigatório."
    ]
  }
}

Exemplos de retornos do resultado da pesquisa#

Valores possíveis do campo "status"

Status	Significado
positivo	Contribuinte possui restituição a receber ou já creditada.
negativo	Contribuinte não possui restituição (imposto a pagar, saldo inexistente ou sem declaração).

Respostas com registro encontrado

JSON

{
    "status": "positivo",
    "mensagem": "Os dados da liberação de sua restituição estão descritos abaixo:",
    "dados": {
        "anoExercicio": 2025,
        "nomeContribuinte": "FULANO DE TAL",
        "resultado": "iar",
        "situacao": "Os dados da liberação de sua restituição estão descritos abaixo:",
        "situacaoRestituicao": "<p>Enviada para crédito no banco. Para obter maiores informações sobre a situação da restituição, consulte o <a href='https://www.gov.br/receitafederal/pt-br/assuntos/meu-imposto-de-renda' target='_blank'>Meu Imposto de Renda</a>.</p>",
        "lote": "003",
        "dataDisponibilidade": "01/05/2025",
        "mensagemPeres": null,
        "chavePix": "999.999.999-99",
        "banco": null,
        "agencia": null,
        "conta": null,
        "debAutomatico": null,
        "observacoes": "Caso a restituição não tenha sido creditada, ligue para a Central de Atendimento BB 4004-0001 (capitais), 0800-729-0001 (demais localidades) e 0800-729-0088 (deficientes auditivos) ou entre em contato com qualquer agência do Banco do Brasil S.A. para solicitar/reagendar o crédito. Também é possível solicitar/reagendar o crédito pelo Portal BB acessando o endereço <a href='https://www.bb.com.br/irpf' target='_blank'>https://www.bb.com.br/irpf</a>.",
        "fila": false,
        "tipoDeclaracao": null,
        "valorRestituicaoOriginal": null,
        "valorRestituicaoCorrigido": null,
        "valorRestituicao": null,
        "existeDeclaracao": true
    },
    "pdf": "base64"
}

JSON

{
    "status": "negativo",
    "mensagem": "Sua declaração já foi processada.<br/>Resultado encontrado: Saldo inexistente de imposto a pagar ou a restituir.",
    "dados": {
        "anoExercicio": 2025,
        "nomeContribuinte": "FULANO DE TAL",
        "resultado": "ssi",
        "situacao": "Sua declaração já foi processada.<br/>Resultado encontrado: Saldo inexistente de imposto a pagar ou a restituir.",
        "situacaoRestituicao": null,
        "lote": null,
        "dataDisponibilidade": null,
        "mensagemPeres": null,
        "chavePix": null,
        "banco": null,
        "agencia": null,
        "conta": null,
        "debAutomatico": null,
        "observacoes": null,
        "fila": false,
        "tipoDeclaracao": null,
        "valorRestituicaoOriginal": null,
        "valorRestituicaoCorrigido": null,
        "valorRestituicao": null,
        "existeDeclaracao": true
    },
    "pdf": "base64"
}