Beneficiário
/v1/beneficiariosBusca por carteirinha ou nome
q exige ao menos 3 caracteres. Não é ergonomia: sem mínimo, uma chamada devolveria a base de carteirinhas da clínica inteira. Dado de paciente sai por pergunta específica, não por varredura.
- Escopo:
- beneficiario:ler
- Resposta:
- 200
Pedido
Parâmetros de query
| Campo | Tipo | O que é |
|---|---|---|
| q* | texto 3–60 caracteres | Texto a procurar. Casa por pedaço do nome e também pelo código, sem diferenciar acento nem caixa. |
| registroANS | texto 1–20 caracteres | 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. |
| limite | inteiro 1–50 · padrão 20 | Quantos registros trazer nesta página. O teto varia por rota (50 a 200) e está nas regras do campo. |
* 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 \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de BeneficiarioEncontrado | O recurso. Os campos estão na tabela abaixo. |
Campos de BeneficiarioEncontrado
| 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 | Nome do beneficiário. A operadora frequentemente não manda — a chave é a carteirinha. |
| 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. |
| ultimaGuia | texto | Data da guia mais recente desta carteirinha, para distinguir homônimos na busca. |
Exemplo de retorno
{
"data": [
{
"carteira": "00000000000000000",
"nome": "PACIENTE EXEMPLO",
"operadora": {
"registroANS": "334561"
},
"ultimaGuia": "2026-09-30"
}
]
}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_buscarA 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
Esta rota não tem erro próprio: só os comuns a qualquer chamada com chave — chave ausente ou inválida, escopo insuficiente, parâmetro recusado e erro interno.
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.