Beneficiário
/v1/beneficiarios/{carteira}O histórico de uma carteirinha
A pergunta que nenhum sistema respondia: o que já aconteceu com esta carteirinha. Medido em produção: 17.464 carteirinhas distintas.
glosado traz dois números e os dois são verdade: declarado é o que a operadora chamou de glosa; derivado é cobrado menos liberado. Quando divergem, a diferença é corte não declarado.
- Escopo:
- beneficiario:ler
- Resposta:
- 200
Pedido
Caminho
| {carteira}* | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
Exemplo de chamada
curl -X GET https://api.miydas.com.br/v1/beneficiarios/0012345678901234 \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | Beneficiario | O recurso. Os campos estão na tabela abaixo. |
O histórico de uma carteirinha nesta clínica. A pergunta que nenhum sistema respondia.
Campos de Beneficiario
| Campo | Tipo | O que é |
|---|---|---|
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| nome | texto | A operadora frequentemente não manda. A carteirinha é a chave; o nome é enriquecimento. |
| operadoras | lista de objetos | As operadoras alcançadas pelo recorte pedido. |
| registroANS | texto | Registro da operadora na ANS, seis dígitos (ex. 334561). É a chave de operadora em toda a API — não usamos nome nem código interno para identificar operadora. |
| resumo | objeto | O histórico desta carteirinha nesta clínica, somado. |
| guias | inteiro | As guias do documento. |
| cobrado | texto | Decimal em string, duas casas — dinheiro não é number. |
| liberado | texto | Decimal em string, duas casas — dinheiro não é number. |
| glosado | objeto | Dois números, os dois verdade: declarado é o que a operadora chamou de glosa; derivado é cobrado menos liberado. |
| declarado | texto | Decimal em string, duas casas — dinheiro não é number. |
| derivado | texto | Decimal em string, duas casas — dinheiro não é number. |
| taxaGlosa | número | Proporção 0–1 do derivado sobre o cobrado. 0 quando não houve cobrança. |
| guiasComGlosaDeclarada | inteiro | Em quantas guias a operadora declarou glosa. |
| guiasPagas | inteiro | Em quantas guias já houve crédito declarado. |
| primeiraGuia | texto | Data da primeira guia desta carteirinha aqui. |
| ultimaGuia | texto | Data da guia mais recente desta carteirinha aqui. |
| glosas | objeto | As glosas desta carteirinha, somadas. |
| total | inteiro | O total do recorte pedido. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| alertas | lista de objetos | Sinal medido no histórico desta carteirinha, não previsão de modelo. |
| tipo | texto | Que sinal é este (ex. taxa de glosa acima da média, guia parada sem retorno). |
| detalhe | texto | Detalhe em texto livre, para humano. Não é contrato. |
Exemplo de retorno
{
"data": {
"carteira": "00000000000000000",
"nome": "PACIENTE EXEMPLO",
"operadoras": [
{
"registroANS": "334561"
}
],
"resumo": {
"guias": 11,
"cobrado": "1888.73",
"liberado": "1079.82",
"glosado": {
"declarado": "742.18",
"derivado": "808.91"
},
"taxaGlosa": 0.4283,
"guiasComGlosaDeclarada": 7,
"guiasPagas": 9,
"primeiraGuia": "2026-02-11",
"ultimaGuia": "2026-09-30"
},
"glosas": {
"total": 19,
"valorTotal": "742.18"
},
"alertas": [
{
"tipo": "GLOSA_RECORRENTE",
"detalhe": "4 glosas com o código 1705 nesta carteirinha"
}
]
}
}Experimente sem chave
O sandbox devolve este mesmo corpo, sem autenticação e sem tocar na base de ninguém.
curl https://api.miydas.com.br/v1/sandbox/beneficiarios_obterA chave de teste myd_test_… é outra coisa: ela opera na homologação da operadora e serve para escrever. Para ver o formato antes de ter credencial, convênio e varredura, é este sandbox.
Erros
| Código | HTTP | Quando | O que fazer |
|---|---|---|---|
| RECURSO_NAO_ENCONTRADO | 404 | O id não existe — ou é de outra empresa, o que a API não distingue de propósito. Também a rota inexistente na v1. | Confira o id. |
Toda falha tem o mesmo formato: { "error": "CODIGO", "message": "…", "details": { … } }. error é estável e serve para lógica; message é para gente e pode mudar. Erros comuns a toda rota com chave (lista completa) não se repetem aqui.