Documentação da API

Esta documentação descreve a API utilizada para automatizar a geração e gerenciamento de recibos eletrônicos de serviços de saúde, em conformidade com as normativas do sistema Receita Saúde da Receita Federal do Brasil.

A API foi desenvolvida pela Rebots para facilitar a integração entre os sistemas de gestão de prestadores de serviços de saúde e a plataforma oficial, permitindo a emissão, cancelamento e consulta de recibos de forma eficiente e segura.

O sistema Receita Saúde é uma iniciativa da Receita Federal que visa modernizar e simplificar a declaração de despesas médicas no Imposto de Renda, tanto para contribuintes quanto para prestadores de serviço.

Este manual técnico detalha todos os aspectos necessários para a correta utilização da API, incluindo processos de autenticação, endpoints disponíveis, operações suportadas, tratamento de erros e exemplos práticos de integração.

A API Rebots para o Receita Saúde oferece uma interface programática robusta e simplificada, permitindo que sistemas de terceiros — como softwares de gestão de clínicas e consultórios — interajam de forma automatizada com o sistema de emissão de recibos da Receita Federal.

A API opera sobre o protocolo HTTPS, utiliza autenticação baseada em token JWT e todas as respostas são no formato JSON.

A API utiliza JWT (JSON Web Tokens) para garantir segurança e controle de acesso. Todas as requisições — com exceção da rota de obtenção do token — devem incluir um token de acesso válido no cabeçalho HTTP.

{
  "identificador": "CODIGO_DO_CLIENTE",
  "master_key": "SUA_MASTER_KEY_FORNECIDA"
}

{
  "access_token": "SEU_TOKEN_JWT_GERADO",
  "token_type": "Bearer",
  "client_name": "Nome do Cliente"
}

Authorization: Bearer SEU_TOKEN_JWT_GERADO

A API suporta diversas operações para o gerenciamento completo do ciclo de vida dos recibos eletrônicos e da configuração do emissor. Todas as operações são realizadas via requisições HTTP POST com corpo e respostas em JSON.

{
  "identificador": "CODIGO_DO_CLIENTE",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "cpf": "CPF_DO_PROFISSIONAL",
  "action": "enable",
  "occupation_code": "CODIGO_DA_OCUPACAO",
  "registration": "REGISTRO_PROFISSIONAL"
}

{
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "message": "Issuer created and enabled successfully."
}

{
  "identificador": "CODIGO_DO_CLIENTE",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "action": "disable"
}

{
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "message": "Issuer disabled successfully."
}

{
  "identificador": "CODIGO_DO_CLIENTE",
  "action": "issue",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "receipt_id": 12345,
  "payer": "CPF_PAGADOR",
  "beneficiary": "CPF_BENEFICIARIO",
  "amount": 2345.78,
  "date": "2026-03-12T00:00:00",
  "description": "Consulta médica",
  "test": false
}

{
  "receipt_id": 12345,
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "success": true,
  "message": "Issue request registered successfully"
}

{
  "identificador": "CODIGO_DO_CLIENTE",
  "action": "cancel",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "receipt_id": 12345,
  "reason": "Erro no valor informado",
  "test": false
}

{
  "receipt_id": 12345,
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "success": true,
  "message": "Cancel request registered successfully"
}

Para informar o resultado final das operações assíncronas de emissão e cancelamento, a API utiliza um sistema de callback. O cliente deve registrar uma URL para a qual a API enviará uma requisição HTTP POST com os detalhes do resultado.

{
  "identificador": "CODIGO_DO_CLIENTE",
  "url": "https://sua-api.com/callback",
  "token": "SEU_TOKEN_DE_SEGURANCA"
}

{
  "data": {
    "receipt_id": 12345,
    "issuer_code": "CODIGO_DO_EMISSOR",
    "success": true,
    "key": "IDENTIFICADOR_UNICO_NA_API",
    "file_url": "https://url-expiravel-para-pdf",
    "status_message": "Operation carried out successfully",
    "original_action": "issue"
  }
}

A API utiliza códigos de status HTTP padrão para indicar sucesso ou falha. Em caso de erro, o corpo da resposta conterá um objeto JSON com error_code e error_message detalhando o problema.

{
  "error_code": "CODIGO_DO_ERRO_ESPECIFICO",
  "error_message": "Descrição detalhada do erro ocorrido."
}