Ogmma Revenue

Beneficiário

GET/v1/beneficiarios

Busca 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

CampoTipoO 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.
registroANStexto
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.
limiteinteiro
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

datalista de BeneficiarioEncontradoO recurso. Os campos estão na tabela abaixo.

Campos de BeneficiarioEncontrado

CampoTipoO que é
carteiratextoNúmero da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador.
nometextoNome do beneficiário. A operadora frequentemente não manda — a chave é a carteirinha.
operadoraobjetoA operadora do documento, identificada pelo registro ANS.
registroANStextoRegistro 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.
ultimaGuiatextoData 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_buscar

A 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.