API Receita Saúde – Validação Automática de Recibos Médicos (VALIDATE_MEDICAL_RECEIPT)

Valide recibos do Receita Saúde com precisão: Integração com a Receita Federal

Com apenas uma requisição síncrona, o processo executa três etapas: extração dos dados do recibo, consulta às informações oficiais da Receita Federal e comparação detalhada entre os dois conjuntos de dados.

📌

A rota síncrona realiza a consulta em tempo real à fonte oficial da Receita Federal. Por se tratar de uma integração direta, o tempo de conclusão da requisição pode ser elevado, com timeout configurado em até 6 minutos.

Além disso, o resultado pode ser impactado por instabilidades ou indisponibilidades temporárias da própria Receita Federal, o que foge ao controle do serviço.

Recomendação: é altamente recomendável que o cliente implemente políticas de retry em seus fluxos de consumo para aumentar a resiliência em casos de falha ou indisponibilidade momentânea da fonte.

Para garantir a extração correta, recomendamos enviar arquivos com apenas uma página, já que a rota foi otimizada para processar um único Recibo Receita Saúde por requisição.

Descrição dos status da validação do Recibo Receita Saúde (`status` do objeto `validation`)

Status	Descrição
VALIDO	Indica que o recibo foi localizado na base da Receita Federal com os parâmetros informados na requisição. Quando a entrada for um recibo completo (extraído), significa que os dados extraídos e os dados oficiais coincidem campo a campo. Se os parâmetros de entrada forem apenas textuais (sem documento para extração), o status confirma a existência do recibo, mas não há comparação detalhada dos campos além dos parâmetros fornecidos.
INVALIDO	Indica que: (i) a Receita Federal retornou uma mensagem de erro durante a consulta do recibo ou (ii) o recibo foi encontrado, mas a comparação entre os dados extraídos e os oficiais apresentou divergências em um ou mais campos. O grau de correspondência é indicado pelo score de comparação (0 a 1), sendo mais próximo de 0 = mais divergente, e mais próximo de 1 = mais consistente. O motivo detalhado estará disponível em `statusDescription`.
CANCELADO	Indica que o recibo correspondente aos parâmetros de entrada foi encontrado na Receita Federal, mas consta como cancelado pelo emitente.
ERRO	Indica que ocorreu uma falha no processamento da requisição, como ausência de parâmetros obrigatórios, envio de documento inválido (não sendo um recibo de saúde) ou outras inconsistências. O detalhe do motivo estará descrito em `statusDescription`.

Campos do JSON (Validação de Recibo Receita Saúde)

Campo	Nome Padrão / Origin Name	Descrição
`numero_documento`	document_number / Número do Recibo	Número único do recibo gerado pelo sistema Receita Saúde.
`data_emissao`	issue_date / Data de Emissão	Data em que o recibo foi emitido pelo prestador de serviço.
`data_pagamento`	payment_date / Data de Pagamento	Data em que o pagamento do serviço foi realizado pelo paciente.
`valor_total`	total_value / Valor do Serviço	Valor total cobrado e registrado no recibo.
`cpf`	cpf / CPF do Pagador	CPF da pessoa que realizou o pagamento (geralmente o paciente ou responsável).
`nome`	name / Nome do Pagador	Nome da pessoa responsável pelo pagamento.
`cpf_beneficiario`	beneficiary_cpf / CPF do Beneficiário	CPF do paciente beneficiário do serviço de saúde. Pode coincidir com o do pagador.
`nome_beneficiario`	beneficiary_name / Nome do Beneficiário	Nome completo do beneficiário que recebeu o serviço de saúde.
`cpf_prestador`	supplier_cpf / CPF do Profissional	CPF do profissional de saúde que prestou o serviço.
`nome_prestador`	supplier_name / Nome do Profissional	Nome do profissional de saúde responsável pelo atendimento.
`cpf_representante_prestador`	CPF do Representante	CPF de um representante legal do prestador, quando aplicável.
`descricao_cbo`	cbo_description / Descrição da Ocupação	Nome da ocupação do prestador conforme tabela CBO (ex: Psicólogo).
`cbo`	Código da Ocupação	Código numérico da ocupação (ex: 255 para Psicólogo).
`registro_prestador`	supplier_registration / Registro Profissional	Número do registro profissional do prestador (ex: CRP para psicólogos).
`data_consulta`	appointment_date	Data da consulta ou do atendimento prestado (quando disponível).
`observacao`	observation / Observação	Observações adicionais incluídas pelo prestador (ex: referência a número de sessões).
`cpf_emissor`	issuer_cpf	CPF da pessoa que efetivamente emitiu o recibo. Normalmente coincide com `cpf_prestador`.
`informacoes`	-	Campo reservado para informações adicionais; pode vir vazio/nulo.
`status`	Status do Recibo	Situação do recibo na base da Receita ( A = Ativo ou C = Cancelado).
`data_cancelamento`	Data do Cancelamento	Data em que o recibo foi cancelado (se aplicável).
`motivo_cancelamento`	Motivo do Cancelamento	Razão oficial do cancelamento do recibo (se houver).

Mensagens

Objeto `enrichment`

status	errors
ERROR	SOURCE MESSAGE: DADOS INFORMADOS NÃO CONFEREM COM OS DO RECIBO.
ERROR	SOURCE MESSAGE: CPF DO PRESTADOR INVÁLIDO.
ERROR	SOURCE MESSAGE: RECIBO INFORMADO NÃO É VÁLIDO.
ERROR	A REQUIRED PARAMETER IS EMPTY OR THERE IS NO COMPATIBLE AUTOMATION.
ERROR	DATASET IS TOO SLOW. PLEASE TRY AGAIN IN A FEW MINUTES
ERROR	UNABLE TO FETCH DATA FROM DATASET

Objeto `validation`

status	statusDescription
VALIDO	RECIBO ENCONTRADO COM SUCESSO NA RECEITA FEDERAL.
INVALIDO	FORAM ENCONTRADAS INCONSISTÊNCIAS ENTRE OS DADOS DO RECIBO E OS DA RECEITA FEDERAL. RECOMENDA-SE REVISAR AS INFORMAÇÕES.
INVALIDO	SOURCE MESSAGE: RECIBO INFORMADO NÃO É VÁLIDO.
ERRO	A REQUIRED PARAMETER IS EMPTY OR THERE IS NO COMPATIBLE AUTOMATION.
ERRO	NÃO FOI POSSÍVEL CONCLUIR A EXTRAÇÃO. O DOCUMENTO PODE NÃO SER UM RECIBO DE SAÚDE OU A QUALIDADE DO ARQUIVO ESTÁ BAIXA, O QUE IMPEDE A LEITURA CORRETA E VALIDAÇÃO NA RECEITA FEDERAL.

Mensagens de erro

Impedidivas quanto a continuidade da requisição, apresentadas no objeto status do response body.

code	message
E100	The request could not be processed
R101	A specified parameter is wrong
R117	Invalid authorization data
R118	Rota inválida.
R119	Invalid method
R201	Flow redirect path not found for the given flow code

application/json

Body

Examples

VALIDO - RECIBO ENCONTRADO COM SUCESSO NA RECEITA FEDERALINVALIDO - DADOS INFORMADOS NÃO CONFEREM COM OS DO RECIBO.CANCELADOERRO - NÃO FOI POSSÍVEL CONCLUIR A EXTRAÇÃO.ERRO - A REQUIRED PARAMETER IS EMPTY OR THERE IS NO COMPATIBLE AUTOMATION.

{
    "result": {
        "flowCode": "VALIDATE_MEDICAL_RECEIPT",
        "contentExtraction": [
            {
                "fields": [
                    {
                        "name": "numero_documento",
                        "stdName": "document_number",
                        "value": "9999999999999",
                        "score": 0.99
                    },
                    {
                        "name": "data_pagamento",
                        "stdName": "payment_date",
                        "value": "2025-07-02",
                        "score": 0.99
                    },
                    {
                        "name": "valor_total",
                        "stdName": "total_value",
                        "value": "800.00",
                        "score": 0.99
                    },
                    {
                        "name": "cpf",
                        "stdName": "cpf",
                        "value": "99999999999",
                        "score": 0.99
                    },
                    {
                        "name": "nome",
                        "stdName": "name",
                        "value": "NOME SOBRENOME",
                        "score": 0.99
                    },
                    {
                        "name": "cpf_beneficiario",
                        "stdName": "beneficiary_cpf",
                        "value": "99999999999",
                        "score": 0.99
                    },
                    {
                        "name": "nome_beneficiario",
                        "stdName": "beneficiary_name",
                        "value": "NOME SOBRENOME",
                        "score": 1.0
                    },
                    {
                        "name": "cpf_prestador",
                        "stdName": "supplier_cpf",
                        "value": "99999999999",
                        "score": 0.99
                    },
                    {
                        "name": "nome_prestador",
                        "stdName": "supplier_name",
                        "value": "NOME SOBRENOME",
                        "score": 0.99
                    },
                    {
                        "name": "descricao_cbo",
                        "stdName": "cbo_description",
                        "value": "Psicólogo",
                        "score": 0.99
                    },
                    {
                        "name": "registro_prestador",
                        "stdName": "supplier_registration",
                        "value": "9999999",
                        "score": 0.99
                    },
                    {
                        "name": "data_consulta",
                        "stdName": "appointment_date",
                        "value": "",
                        "score": 0.8
                    },
                    {
                        "name": "observacao",
                        "stdName": "observation",
                        "value": "Pagamento referente a 4 sessões de\npsicoterapia. Mês referência: julho de\n2025",
                        "score": 0.99
                    },
                    {
                        "name": "data_emissao",
                        "stdName": "issue_date",
                        "value": "2025-07-03",
                        "score": 0.99
                    },
                    {
                        "name": "cpf_emissor",
                        "stdName": "issuer_cpf",
                        "value": "99999999999",
                        "score": 0.99
                    },
                    {
                        "name": "informacoes",
                        "stdName": null,
                        "value": null,
                        "score": null
                    }
                ],
                "image": null,
                "score": 0.92,
                "type": "recibo",
                "stdType": "receipt",
                "pageNumber": 1,
                "tags": [
                    "country=bra",
                    "goal=declare",
                    "id=bra-receita-saude-2",
                    "language=pt-BR",
                    "of=health",
                    "of=payment",
                    "process-type=extraction",
                    "std-type=receipt",
                    "type=recibo"
                ],
                "tables": [],
                "processType": "extraction"
            }
        ],
        "enrichment": {
            "processId": "365cb8fb-3501-4c30-af1b-a6456b72ed29",
            "tier": "VALIDAR_RECIBO_SAUDE",
            "query": "VALIDAR_RECIBO_SAUDE",
            "status": "DONE",
            "parameters": {
                "mostqiResponse": {
                    "result": [
                        {
                            "fields": [
                                {
                                    "name": "numero_documento",
                                    "stdName": "document_number",
                                    "value": "9999999999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "data_pagamento",
                                    "stdName": "payment_date",
                                    "value": "2025-07-02",
                                    "score": 0.99
                                },
                                {
                                    "name": "valor_total",
                                    "stdName": "total_value",
                                    "value": "800.00",
                                    "score": 0.99
                                },
                                {
                                    "name": "cpf",
                                    "stdName": "cpf",
                                    "value": "99999999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "nome",
                                    "stdName": "name",
                                    "value": "NOME SOBRENOME",
                                    "score": 0.99
                                },
                                {
                                    "name": "cpf_beneficiario",
                                    "stdName": "beneficiary_cpf",
                                    "value": "99999999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "nome_beneficiario",
                                    "stdName": "beneficiary_name",
                                    "value": "NOME SOBRENOME",
                                    "score": 1
                                },
                                {
                                    "name": "cpf_prestador",
                                    "stdName": "supplier_cpf",
                                    "value": "99999999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "nome_prestador",
                                    "stdName": "supplier_name",
                                    "value": "NOME SOBRENOME",
                                    "score": 0.99
                                },
                                {
                                    "name": "descricao_cbo",
                                    "stdName": "cbo_description",
                                    "value": "Psicólogo",
                                    "score": 0.99
                                },
                                {
                                    "name": "registro_prestador",
                                    "stdName": "supplier_registration",
                                    "value": "9999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "data_consulta",
                                    "stdName": "appointment_date",
                                    "value": "",
                                    "score": 0.8
                                },
                                {
                                    "name": "observacao",
                                    "stdName": "observation",
                                    "value": "Pagamento referente a 4 sessões de\npsicoterapia. Mês referência: julho de\n2025",
                                    "score": 0.99
                                },
                                {
                                    "name": "data_emissao",
                                    "stdName": "issue_date",
                                    "value": "2025-07-03",
                                    "score": 0.99
                                },
                                {
                                    "name": "cpf_emissor",
                                    "stdName": "issuer_cpf",
                                    "value": "99999999999",
                                    "score": 0.99
                                },
                                {
                                    "name": "informacoes",
                                    "stdName": null,
                                    "value": null,
                                    "score": null
                                }
                            ],
                            "image": null,
                            "score": 0.92,
                            "type": "recibo",
                            "stdType": "receipt",
                            "pageNumber": 1,
                            "tags": [
                                "country=bra",
                                "goal=declare",
                                "id=bra-receita-saude-2",
                                "language=pt-BR",
                                "of=health",
                                "of=payment",
                                "process-type=extraction",
                                "std-type=receipt",
                                "type=recibo"
                            ],
                            "tables": [],
                            "processType": "extraction"
                        }
                    ],
                    "requestId": "c1HRzukmRr2m7BQM5wKce",
                    "elapsedMilliseconds": 1810,
                    "status": {
                        "message": "Ok",
                        "code": "200",
                        "errors": null
                    }
                }
            },
            "datasets": [
                {
                    "name": "validar_receita_saude",
                    "code": "validar_receita_saude_ondemand_817669",
                    "status": "DONE",
                    "fromCache": false,
                    "errors": [],
                    "data": [
                        {
                            "type": "recibo",
                            "id": "bra-validar-receita-saude-1",
                            "fields": [
                                {
                                    "name": "numero_documento",
                                    "origin_name": "Número do Recibo",
                                    "value": "999.999.99.999999999",
                                    "score": null
                                },
                                {
                                    "name": "data_emissao",
                                    "origin_name": "Data de Emissão",
                                    "value": "2025-07-03",
                                    "score": null
                                },
                                {
                                    "name": "data_pagamento",
                                    "origin_name": "Data de Pagamento",
                                    "value": "2025-07-02",
                                    "score": null
                                },
                                {
                                    "name": "cbo",
                                    "origin_name": "Código da Ocupação",
                                    "value": "255",
                                    "score": null
                                },
                                {
                                    "name": "descricao_cbo",
                                    "origin_name": "Descrição da Ocupação",
                                    "value": "Psicólogo",
                                    "score": null
                                },
                                {
                                    "name": "registro_prestador",
                                    "origin_name": "Registro Profissional",
                                    "value": "99/99999",
                                    "score": null
                                },
                                {
                                    "name": "cpf",
                                    "origin_name": "CPF do Pagador",
                                    "value": "99999999999",
                                    "score": null
                                },
                                {
                                    "name": "nome",
                                    "origin_name": "Nome do Pagador",
                                    "value": "NOME SOBRENOME",
                                    "score": null
                                },
                                {
                                    "name": "cpf_beneficiario",
                                    "origin_name": "CPF do Beneficiário",
                                    "value": "99999999999",
                                    "score": null
                                },
                                {
                                    "name": "nome_beneficiario",
                                    "origin_name": "Nome do Beneficiário",
                                    "value": "NOME SOBRENOME",
                                    "score": null
                                },
                                {
                                    "name": "valor_total",
                                    "origin_name": "Valor do Serviço",
                                    "value": "800.00",
                                    "score": null
                                },
                                {
                                    "name": "observacao",
                                    "origin_name": "Observação",
                                    "value": "Pagamento referente a 4 sessões de psicoterapia. Mês referência: julho de 2025",
                                    "score": null
                                },
                                {
                                    "name": "status",
                                    "origin_name": "Status do Recibo",
                                    "value": "A",
                                    "score": null
                                },
                                {
                                    "name": "cpf_representante_prestador",
                                    "origin_name": "CPF do Representante",
                                    "value": "99999999999",
                                    "score": null
                                },
                                {
                                    "name": "cpf_prestador",
                                    "origin_name": "CPF do Profissional",
                                    "value": "99999999999",
                                    "score": null
                                },
                                {
                                    "name": "nome_prestador",
                                    "origin_name": "Nome do Profissional",
                                    "value": "NOME SOBRENOME",
                                    "score": null
                                },
                                {
                                    "name": "data_consulta",
                                    "origin_name": null,
                                    "value": "2025-09-23 15:29:49",
                                    "score": null
                                },
                                {
                                    "name": "motivo_cancelamento",
                                    "origin_name": "Motivo do Cancelamento",
                                    "value": null,
                                    "score": null
                                },
                                {
                                    "name": "data_cancelamento",
                                    "origin_name": "Data do Cancelamento",
                                    "value": null,
                                    "score": null
                                }
                            ],
                            "tables": [],
                            "tags": [
                                "country=bra",
                                "goal=declare",
                                "id=bra-validar-receita-saude-1",
                                "language=pt-BR",
                                "of=health",
                                "of=payment",
                                "std-type=receipt",
                                "type=recibo"
                            ]
                        }
                    ]
                }
            ]
        },
        "validation": {
            "status": "VALIDO",
            "statusDescription": "RECIBO ENCONTRADO COM SUCESSO NA RECEITA FEDERAL.",
            "fields": [
                {
                    "name": "numero_documento",
                    "extractionValue": "9999999999999",
                    "originValue": "999.999.99.99999",
                    "score": 1.0
                },
                {
                    "name": "data_emissao",
                    "extractionValue": "2025-07-03",
                    "originValue": "2025-07-03",
                    "score": 1.0
                },
                {
                    "name": "data_pagamento",
                    "extractionValue": "2025-07-02",
                    "originValue": "2025-07-02",
                    "score": 1.0
                },
                {
                    "name": "descricao_cbo",
                    "extractionValue": "Psicólogo",
                    "originValue": "Psicólogo",
                    "score": 1.0
                },
                {
                    "name": "registro_prestador",
                    "extractionValue": "9999999",
                    "originValue": "99/99999",
                    "score": 1.0
                },
                {
                    "name": "cpf",
                    "extractionValue": "99999999999",
                    "originValue": "99999999999",
                    "score": 1.0
                },
                {
                    "name": "nome",
                    "extractionValue": "NOME SOBRENOME",
                    "originValue": "NOME SOBRENOME",
                    "score": 1.0
                },
                {
                    "name": "cpf_beneficiario",
                    "extractionValue": "99999999999",
                    "originValue": "99999999999",
                    "score": 1.0
                },
                {
                    "name": "nome_beneficiario",
                    "extractionValue": "NOME SOBRENOME",
                    "originValue": "NOME SOBRENOME",
                    "score": 1.0
                },
                {
                    "name": "valor_total",
                    "extractionValue": "800.00",
                    "originValue": "800.00",
                    "score": 1.0
                },
                {
                    "name": "cpf_representante_prestador",
                    "extractionValue": null,
                    "originValue": "99999999999",
                    "score": null
                },
                {
                    "name": "cpf_prestador",
                    "extractionValue": "99999999999",
                    "originValue": "99999999999",
                    "score": 1.0
                },
                {
                    "name": "nome_prestador",
                    "extractionValue": "NOME SOBRENOME",
                    "originValue": "NOME SOBRENOME",
                    "score": 1.0
                },
                {
                    "name": "observacao",
                    "extractionValue": "Pagamento referente a 4 sessões de\npsicoterapia. Mês referência: julho de\n2025",
                    "originValue": "Pagamento referente a 4 sessões de psicoterapia. Mês referência: julho de 2025",
                    "score": 1.0
                },
                {
                    "name": "data_consulta",
                    "extractionValue": "",
                    "originValue": "2025-09-23 15:29:49",
                    "score": null
                },
                {
                    "name": "data_cancelamento",
                    "extractionValue": null,
                    "originValue": null,
                    "score": null
                },
                {
                    "name": "motivo_cancelamento",
                    "extractionValue": null,
                    "originValue": null,
                    "score": null
                }
            ]
        }
    },
    "requestId": "51yRTuNzup2x89GW51w4e",
    "elapsedMilliseconds": 49398,
    "status": {
        "message": "Ok",
        "code": "200",
        "errors": null
    }
}

sync

Valide recibos do Receita Saúde com precisão: Integração com a Receita Federal

Descrição dos status da validação do Recibo Receita Saúde (`status` do objeto `validation`)

Campos do JSON (Validação de Recibo Receita Saúde)

Mensagens

Objeto `enrichment`

Objeto `validation`

Mensagens de erro

Request

Request Code Samples

Responses

sync

Valide recibos do Receita Saúde com precisão: Integração com a Receita Federal#

Descrição dos status da validação do Recibo Receita Saúde (status do objeto validation)#

Campos do JSON (Validação de Recibo Receita Saúde)#

Mensagens#

Objeto enrichment#

Objeto validation#

Mensagens de erro#

Request

Request Code Samples

Responses

Valide recibos do Receita Saúde com precisão: Integração com a Receita Federal

Descrição dos status da validação do Recibo Receita Saúde (`status` do objeto `validation`)

Campos do JSON (Validação de Recibo Receita Saúde)

Mensagens

Objeto `enrichment`

Objeto `validation`

Mensagens de erro