API Escrituração de Despesas · v1.0

Documentação — Escrituração de Despesas

Registro em lote de despesas vinculadas a um contribuinte pessoa física, com validação individual por item e aceitação parcial.

Última atualização: 29 de julho de 2026·Versão 1.0

1. Introdução

A API Escrituração de Despesas permite registrar, em lote, despesas vinculadas a um contribuinte já cadastrado através da API Receita Saúde.

Assim como a emissão de recibos, este endpoint envia as despesas para processamento junto à Receita Federal — útil para escrituração de despesas (ex: energia elétrica, aluguel) associadas à atividade do emissor.

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

Para consultar as despesas já escrituradas ou excluir um lançamento, veja a API de Listagem e Exclusão de Despesas Escrituradas.

2. Visão Geral

Esta API tem uma característica que a difere da API Receita Saúde:

Aceitação parcial em lote

Itens com formato válido do array 'expenses' são aceitos para processamento mesmo que outros itens do mesmo lote sejam rejeitados na validação. Não é uma operação tudo-ou-nada.

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

A API Escrituração de Despesas utiliza exatamente o mesmo token de acesso da API Receita Saúde — não há uma 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 Registro de Despesas (Lote)

Pré-requisitos:

Ter um emissor ativo para o issuer_code informado
Ter o plano de contas completo já pré-configurado no Carnê-Leão Web do contribuinte
Fora do ambiente sandbox, ter um endpoint de callback registrado (/endpoint) — obrigatório antes de processar qualquer item do lote

Em ambiente sandbox, o endpoint de callback é opcional.

POST/receita-saude/v2/expenses

Corpo da Requisição

json

{
  "identificador": "SEU_CODIGO_DE_CLIENTE",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "expenses": [
    {
      "id": 97077,
      "date": "2026-07-28",
      "accountCode": "P10.01.00014",
      "value": 1177.51,
      "description": "PAGAMENTO REF A ENERGIA ELETRICA"
    },
    {
      "id": 97092,
      "date": "2026-07-28",
      "accountCode": "P10.01.00015",
      "value": 1083.05,
      "description": "PAGAMENTO REF A ALUGUEL"
    }
  ]
}

Envelope da Requisição

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.
expenses	array	Obrigatório	Lote de despesas a registrar. Deve conter ao menos um item.

Campos de cada item de "expenses"

Parâmetro	Tipo	Req.	Descrição
id	integer	Obrigatório	ID único da despesa, definido por você. Único e imutável por emissor — reenviar um id já aceito é sempre rejeitado, nunca é tratado como atualização.
date	date	Obrigatório	Data da despesa, formato AAAA-MM-DD. Não pode ser uma data futura.
accountCode	string	Obrigatório	Código da conta no padrão A00.00.00000 (uma letra, 2 dígitos, ponto, 2 dígitos, ponto, 5 dígitos). Ex: P10.01.00014. Deve estar obrigatoriamente já pré-cadastrado no plano de contas do Carnê-Leão Web do contribuinte.
value	double	Obrigatório	Valor em reais. Deve ser maior que zero. Máximo permitido: 99.999.999,99.
description	string	Obrigatório	Descrição livre da despesa. Até 255 caracteres.

O lote não é transacional: itens com formato válido são aceitos para processamento normalmente mesmo que outros itens do mesmo array sejam rejeitados.

Esta resposta HTTP não é o resultado final. Ela confirma apenas que o formato de cada item é válido e que não é duplicado — o resultado definitivo (aceito ou rejeitado pela Receita Federal) chega depois, exclusivamente pelo callback (seção 5).

Resposta de Sucesso — todos os itens aceitos para processamento (HTTP 200)

json

{
  "success": true,
  "issuer_code": "CODIGO_DO_EMISSOR",
  "message": "All expenses accepted for processing.",
  "accepted": [97077, 97092]
}

Resposta — aceitação parcial (HTTP 200)

json

{
  "success": false,
  "issuer_code": "CODIGO_DO_EMISSOR",
  "accepted": [97077],
  "errors": [
    {
      "id": 97092,
      "index": 1,
      "error_code": "EXPENSES_ERROR_014",
      "error_message": "Field 'accountCode' must follow the pattern A00.00.00000."
    }
  ]
}

Parâmetro	Tipo	Req.	Descrição
id	integer	Obrigatório	ID do item rejeitado. O campo sempre está presente, mas o valor pode ser null se o próprio campo 'id' era inválido ou ausente.
index	integer	Obrigatório	Posição (a partir de 0) do item dentro do array 'expenses' enviado.
error_code	string	Obrigatório	Código do erro — ver seção 6.
error_message	string	Obrigatório	Descrição legível do erro.

5. Sistema de Callback

Igual ao que ocorre na emissão de recibos, a resposta HTTP direta (seção 4.1) não traz o resultado final — ela confirma apenas que o formato dos itens é válido e que não são duplicados. O resultado definitivo, depois do processamento pela Receita Federal, chega exclusivamente pelo callback.

O callback reutiliza o mesmo endpoint registrado através da API Receita Saúde, e é disparado uma vez por request (não uma vez por item do lote).

5.1 Formato do Callback

json

{
  "type": "expenses",
  "issuer_code": "CODIGO_DO_EMISSOR",
  "results": [
    { "id": 97077, "success": true },
    { "id": 97092, "success": false, "error": "Field 'accountCode' must follow the pattern A00.00.00000." }
  ]
}

Diferente do callback de recibos, este formato não tem envelope data — os campos ficam na raiz do payload.

Parâmetro	Tipo	Req.	Descrição
type	string	Obrigatório	Sempre "expenses" — identifica a origem do callback.
issuer_code	string	Obrigatório	Código do emissor do lote processado.
results	array	Obrigatório	Um item por despesa do request original, na mesma ordem — sucesso e falha inclusos.

Parâmetro	Tipo	Req.	Descrição
results[].id	integer	Opcional	ID da despesa. Pode ser null para itens com id inválido.
results[].success	boolean	Obrigatório	true se o item foi aceito e persistido, false se foi rejeitado.
results[].error	string	Opcional	Presente apenas quando success é false — mensagem legível do motivo da rejeição.

Fora do ambiente sandbox, ter um endpoint de callback registrado é obrigatório antes de qualquer item do lote ser processado. No sandbox, se nenhum endpoint estiver registrado, o lote ainda é processado normalmente — apenas o callback não é enviado.

6. Tratamento de Erros

Esta API tem dois níveis de erro, diferente do restante da plataforma Rebots:

01
Erros de Requisição
Interrompem o request inteiro — HTTP 400/403/422, corpo {error_code, error_message}. Nenhum item do lote é processado.
02
Erros de Item
Sempre retornam HTTP 200 (com success: false), dentro do array errors da resposta — os demais itens do lote continuam sendo processados normalmente.

200OKRequisição processada (ver 'success' no corpo para saber se houve rejeições).

400Bad RequestParâmetros inválidos ou ausentes no nível de requisição.

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.

Para uma lista completa de todos os códigos de erro (requisição e por item), consulte a Referência de Erros →

Documentação — Escrituração de Despesas · Versão 1.0

Última atualização: 29 de julho de 2026

Suporte técnico