Documentação — Extensão Contador

A Extensão Contador é um conjunto de endpoints complementares à API Receita Saúde, voltado a contadores e sistemas de gestão contábil que precisam consultar recibos já emitidos — sem precisar emitir ou cancelar nada diretamente.

Diferente da API principal, esta extensão não emite novos recibos: ela permite solicitar o PDF de um recibo específico já emitido, ou solicitar uma listagem de recibos emitidos dentro de um período.

Assim como a API principal, ambas as operações desta extensão são assíncronas: a chamada apenas registra a solicitação, e o resultado é entregue posteriormente via callback.

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

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

Authorization: Bearer SEU_TOKEN_JWT_GERADO

As duas operações desta extensão são realizadas via requisições HTTP POST com corpo e respostas em JSON.

{
  "identificador": "CODIGO_DO_CLIENTE",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "receipt_number": "NUMERO_DO_RECIBO"
}

{
  "message": "PDF request registered successfully."
}

{
  "identificador": "CODIGO_DO_CLIENTE",
  "issuer_code": "SEU_CODIGO_DE_EMISSOR",
  "start_date": "2026-01-01",
  "end_date": "2026-03-31"
}

{
  "message": "List request registered successfully."
}

As duas operações desta extensão reutilizam o mesmo endpoint de callback registrado através da API Receita Saúde — não é necessário nenhum registro adicional.

{
  "data": {
    "receipt_number": "NUMERO_DO_RECIBO",
    "issuer_code": "CODIGO_DO_EMISSOR",
    "file_url": "https://url-expiravel-para-pdf"
  }
}

{
  "data": {
    "issuer_code": "CODIGO_DO_EMISSOR",
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "receipts": [
      { "receipt_number": "...", "received_at": "...", "payer_cpf": "...", "amount": 150.00, "occupation_code": 225 }
    ]
  }
}

Requisitos do Endpoint de Callback

• A URL deve estar acessível publicamente na internet.
• Deve aceitar requisições HTTP POST com corpo JSON.
• Deve retornar HTTP 200 OK para confirmar o recebimento.
• Deve validar o token enviado no header Authorization.

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."
}

Para uma lista completa de todos os códigos de erro por endpoint, consulte a Referência de Erros →