Beneficiário
/v1/beneficiarios/{carteira}/elegibilidadesO histórico de consultas de elegibilidade
Leitura: não fala com a operadora. Chave de teste vê só o que nasceu em homologação.
- 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. |
Parâmetros de query
| Campo | Tipo | O que é |
|---|---|---|
| limite | inteiro 1–200 · padrão 50 | Quantos registros trazer nesta página. O teto varia por rota (50 a 200) e está nas regras do campo. |
| deslocamento | inteiro padrão 0 | Quantos registros pular, para a página seguinte. Use com paginacao.total da resposta; paginacao.temMais diz se vale pedir mais. |
* obrigatório. Campo desconhecido é recusado, não ignorado: a API responde VALIDATION_ERROR em vez de descartar em silêncio.
Exemplo de chamada
curl -X GET https://api.miydas.com.br/v1/beneficiarios/0012345678901234/elegibilidades \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de ElegibilidadeResumida | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde esta página está no total. Vem fora de data. |
Elegibilidade já consultada. Leitura: não fala com a operadora.
Campos de ElegibilidadeResumida
| Campo | Tipo | O que é |
|---|---|---|
| elegibilidadeId | texto | A consulta de elegibilidade, pelo identificador do Miydas. |
| operadora | objeto | A operadora do documento, identificada pelo registro ANS. |
| 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. |
| elegivel | booleano | A operadora respondeu que o beneficiário pode ser atendido. |
| alcance | texto | CARTEIRINHA | PROCEDIMENTO — até onde a operadora respondeu. |
| motivoNaoElegivel | texto | O que a operadora respondeu quando negou o atendimento, na língua dela. |
| plano | texto | Nome do plano do beneficiário na operadora. |
| validadeCarteira | texto | Último dia de validade da carteirinha informado pela operadora. |
| consultadaEm | texto | Quando a consulta à operadora aconteceu, em ISO 8601 com fuso. |
Exemplo de retorno
{
"data": [
{
"elegibilidadeId": "cmf3k2x9a0002ele",
"operadora": {
"registroANS": "334561"
},
"elegivel": true,
"alcance": "CARTEIRINHA",
"motivoNaoElegivel": null,
"plano": "PLANO EXEMPLO",
"validadeCarteira": "2027-01-31",
"consultadaEm": "2026-09-27T13:00:01.000Z"
}
],
"paginacao": {
"total": 1,
"limite": 20,
"deslocamento": 0,
"temMais": false
}
}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_elegibilidadesA 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.