Ogmma Revenue

Beneficiário

GET/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

dataBeneficiarioO 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

CampoTipoO que é
carteiratextoNúmero da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador.
nometextoA operadora frequentemente não manda. A carteirinha é a chave; o nome é enriquecimento.
operadoraslista de objetosAs operadoras alcançadas pelo recorte pedido.
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.
resumoobjetoO histórico desta carteirinha nesta clínica, somado.
guiasinteiroAs guias do documento.
cobradotextoDecimal em string, duas casas — dinheiro não é number.
liberadotextoDecimal em string, duas casas — dinheiro não é number.
glosadoobjetoDois números, os dois verdade: declarado é o que a operadora chamou de glosa; derivado é cobrado menos liberado.
declaradotextoDecimal em string, duas casas — dinheiro não é number.
derivadotextoDecimal em string, duas casas — dinheiro não é number.
taxaGlosanúmeroProporção 0–1 do derivado sobre o cobrado. 0 quando não houve cobrança.
guiasComGlosaDeclaradainteiroEm quantas guias a operadora declarou glosa.
guiasPagasinteiroEm quantas guias já houve crédito declarado.
primeiraGuiatextoData da primeira guia desta carteirinha aqui.
ultimaGuiatextoData da guia mais recente desta carteirinha aqui.
glosasobjetoAs glosas desta carteirinha, somadas.
totalinteiroO total do recorte pedido.
valorTotaltextoDecimal em string, duas casas — dinheiro não é number.
alertaslista de objetosSinal medido no histórico desta carteirinha, não previsão de modelo.
tipotextoQue sinal é este (ex. taxa de glosa acima da média, guia parada sem retorno).
detalhetextoDetalhe 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_obter

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

CódigoHTTPQuandoO que fazer
RECURSO_NAO_ENCONTRADO404O 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.