API Despesas Escrituradas · v1.1

Listagem e Exclusão de Despesas Escrituradas

Consulte, por emissor e mês/ano, as despesas já escrituradas no Carnê-Leão Web e solicite a exclusão de um lançamento específico. A resposta HTTP confirma apenas o enfileiramento — o resultado chega pelo callback.

Última atualização: 18 de agosto de 2026·Versão 1.1

1. Introdução

A API de Despesas Escrituradas permite consultar os lançamentos de pagamento (despesas dedutíveis) já escriturados no Carnê-Leão Web de um emissor cadastrado, e excluir um lançamento específico. Ela complementa a API de Escrituração de Despesas, que registra essas despesas: aqui você lê o que foi escriturado e pode removê-lo.

Para usar esta API você precisa de um emissor já ativo através da API Receita Saúde.

2. Visão Geral

Esta API compartilha as características assíncronas do restante da plataforma Rebots:

Enfileiramento síncrono, resultado assíncrono

A resposta HTTP confirma apenas que a solicitação foi aceita e enfileirada. O acesso ao portal da Receita Federal e a leitura/exclusão efetiva acontecem em seguida, e o resultado é entregue exclusivamente pelo callback.

Listagem sem persistência

A listagem é raspada do portal e devolvida ao seu webhook assim que processada — a Rebots não armazena os lançamentos. Cada consulta reflete o estado atual da área 'Pagamentos' no momento.

Exclusão por três campos

A exclusão de um lançamento é solicitada informando data, natureza e valor. A Rebots exclui o primeiro lançamento coincidente com esses três dados; havendo mais de um idêntico, os demais permanecem.

Uma consulta por emissor e mês

A listagem é sempre delimitada por um único emissor e um único mês/ano, referente à data de lançamento.

A API opera sobre HTTPS, utiliza o mesmo token JWT da API Receita Saúde, e todas as respostas são em JSON.

3. Autenticação

Esta API utiliza exatamente o mesmo token de acesso da API Receita Saúde — não há autenticação separada.

http

Authorization: Bearer SEU_TOKEN_JWT_GERADO

Para o processo completo de obtenção e renovação do access_token, consulte a seção de Autenticação da documentação principal.

4. Operações

4.1 Listar despesas escrituradas

Solicita a listagem de todas as despesas escrituradas de um emissor em um determinado mês/ano.

POST/receita-saude/v2/expenses/list

Corpo da Requisição

json

{
  "identificador": "SEU_CODIGO_DE_CLIENTE",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "year": 2026,
  "month": 8
}

Parâmetro	Tipo	Req.	Descrição
identificador	string	Obrigatório	Código de identificação do Cliente.
issuer_code	string	Obrigatório	Código do emissor já cadastrado na plataforma Rebots.
year	integer	Obrigatório	Ano-calendário de referência, formato AAAA. Ex: 2026. Não pode ser futuro.
month	integer	Obrigatório	Mês de referência (1 a 12), pela data de lançamento. Ex: 8 para agosto.

Resposta (HTTP 200)

json

{
  "success": true,
  "issuer_code": "CODIGO_DO_EMISSOR",
  "message": "List request accepted for processing."
}

Esta resposta HTTP não é a lista. Ela confirma apenas que a solicitação foi enfileirada. A relação de lançamentos chega depois, pelo callback expense_list (seção 5.1).

4.2 Excluir um lançamento

Solicita a exclusão, no Carnê-Leão Web, do primeiro lançamento coincidente com data, natureza e valor.

POST/receita-saude/v2/expenses/delete

Corpo da Requisição

json

{
  "identificador": "SEU_CODIGO_DE_CLIENTE",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "date": "2026-08-17",
  "natureza": "Aluguel do escritório/consultório",
  "value": 1083.05
}

Parâmetro	Tipo	Req.	Descrição
identificador	string	Obrigatório	Código de identificação do Cliente.
issuer_code	string	Obrigatório	Código do emissor já cadastrado na plataforma Rebots.
date	date	Obrigatório	Data de lançamento do pagamento, formato AAAA-MM-DD — exatamente como recebido no callback da listagem (seção 5.1).
natureza	string	Obrigatório	Descrição da natureza do pagamento, exatamente como recebida na listagem. Comparação sem diferenciar maiúsculas/minúsculas. Máx: 255 caracteres.
value	double	Obrigatório	Valor em reais do lançamento, como recebido na listagem (ex: 1083.05). Deve ser maior que zero.

Resposta (HTTP 200)

json

{
  "success": true,
  "issuer_code": "CODIGO_DO_EMISSOR",
  "message": "Deletion request accepted for processing."
}

Esta resposta HTTP não é o resultado da exclusão. Se nenhum lançamento coincidir, a solicitação não é rejeitada aqui — ela é aceita e o resultado (sucesso ou falha) chega pelo callback expense_deletion (seção 5.2).

5. Sistema de Callback

Ao concluir o processamento, a Rebots faz um POST ao endpoint de callback registrado para o seu cliente, com o mesmo token Bearer configurado. Assim como no callback de despesas, o payload é entregue no nível raiz (sem envelope data), e o campo type identifica a origem.

5.1 Callback da listagem — type: "expense_list"

Enviado uma vez por solicitação de listagem, contendo todos os lançamentos do período.

json

{
  "type": "expense_list",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "year": 2026,
  "month": 8,
  "expenses": [
    {
      "date": "2026-08-17",
      "competencia": "",
      "natureza": "Aluguel do escritório/consultório",
      "historico": "PAGAMENTO REF A ALUGUEL",
      "value": 1083.05
    },
    {
      "date": "2026-08-17",
      "competencia": "",
      "natureza": "Energia do escritório/consultório",
      "historico": "PAGAMENTO REF A ENERGIA ELETRICA",
      "value": 1177.51
    }
  ]
}

Campos do callback (raiz)

Parâmetro	Tipo	Req.	Descrição
type	string	Obrigatório	Sempre "expense_list" — identifica a origem do callback.
issuer_code	string	Obrigatório	Código do emissor consultado.
year	integer	Obrigatório	Ano-calendário da consulta.
month	integer	Obrigatório	Mês da consulta (1 a 12).
expenses	array	Obrigatório	Lançamentos do período, ordenados por data. Vazio se não houver nenhum.

Campos de cada item de "expenses"

Parâmetro	Tipo	Req.	Descrição
date	date	Obrigatório	Data de lançamento, formato AAAA-MM-DD. Um dos três campos usados para solicitar a exclusão (seção 4.2).
competencia	string	Opcional	Mês/ano de competência (MM/AAAA) quando informado no lançamento; caso contrário, string vazia.
natureza	string	Obrigatório	Descrição da natureza do pagamento (ex: 'Aluguel do escritório/consultório').
historico	string	Opcional	Histórico livre do lançamento.
value	double	Obrigatório	Valor em reais do lançamento.

5.2 Callback da exclusão — type: "expense_deletion"

Enviado uma vez por solicitação de exclusão, informando o resultado. O callback ecoa os três campos identificadores (date, natureza, value) para você correlacionar com a solicitação.

Sucesso

json

{
  "type": "expense_deletion",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "date": "2026-08-17",
  "natureza": "Aluguel do escritório/consultório",
  "value": 1083.05,
  "success": true
}

Falha

json

{
  "type": "expense_deletion",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "date": "2026-08-17",
  "natureza": "Aluguel do escritório/consultório",
  "value": 1083.05,
  "success": false,
  "error": "Lançamento não encontrado (nenhum lançamento coincide com data, natureza e valor informados)."
}

Parâmetro	Tipo	Req.	Descrição
type	string	Obrigatório	Sempre "expense_deletion".
issuer_code	string	Obrigatório	Código do emissor do lançamento.
date	date	Obrigatório	A mesma data enviada na solicitação (AAAA-MM-DD).
natureza	string	Obrigatório	A mesma natureza enviada na solicitação.
value	double	Obrigatório	O mesmo valor enviado na solicitação.
success	boolean	Obrigatório	true se um lançamento coincidente foi excluído; false se nenhum coincidiu ou se não foi possível excluir.
error	string	Opcional	Presente apenas quando success é false — mensagem legível do motivo.

A exclusão remove apenas o primeiro lançamento coincidente. Se você tinha lançamentos idênticos duplicados, repita a solicitação para remover os demais, um a um.

6. Como a exclusão localiza o lançamento

A exclusão não usa um identificador interno: a Rebots abre a área "Pagamentos" do emissor, filtra pela date informada e procura, na ordem em que os lançamentos aparecem, o primeiro cujos três campos coincidem:

Data

Igual à date da solicitação.

Natureza

Igual à natureza, com comparação sem diferenciar maiúsculas/minúsculas. Use exatamente o texto recebido na listagem.

Valor

Igual ao value.

Comportamento importante

01
Duplicados
Se houver mais de um lançamento idêntico (mesma data, natureza e valor), apenas o primeiro é excluído. Para remover os demais, repita a solicitação — cada chamada remove mais um.
02
Nenhum coincidente
A solicitação é aceita, mas o callback retorna success: false com a mensagem de "não encontrado".

Como a listagem reflete o estado atual do portal e não é persistida, obtenha os valores de date, natureza e value de uma listagem recente antes de solicitar a exclusão.

7. Tratamento de Erros

Erros de requisição interrompem a chamada e retornam HTTP 4xx/5xx com corpo { error_code, error_message } — nada é enfileirado. Já problemas de execução (ex: emissor sem procuração válida no momento, lançamento não localizado) não são erros HTTP: a solicitação é aceita (HTTP 200) e o desfecho chega pelo callback.

200OKSolicitação aceita e enfileirada. O resultado vem pelo callback.

400Bad RequestParâmetros inválidos ou ausentes (ex: month fora de 1–12, date fora do formato).

401UnauthorizedToken ausente, inválido, expirado ou revogado.

403ForbiddenEmissor desativado, ou (fora do sandbox) nenhum callback registrado.

422Unprocessable EntityEmissor não encontrado para o identificador informado (a rota existe — não é URL inválida).

500Internal Server ErrorErro interno no servidor. Entre em contato com o suporte.

Fora do ambiente sandbox, ter um endpoint de callback registrado é obrigatório — sem ele a solicitação é recusada, pois o resultado só pode ser entregue por callback.

Para a lista completa dos códigos de erro destas duas rotas, consulte a Referência de Erros →

Listagem e Exclusão de Despesas Escrituradas · Versão 1.1

Última atualização: 18 de agosto de 2026

Suporte técnico