Ogmma Revenue

Beneficiário

GET/v1/beneficiarios/{carteira}/guias

Toda guia da carteirinha, em toda competência

valores.cobrado vem de uma coluna gerada no banco — o maior entre informado, processado e liberado. Não é o informado cru: há operadora que declara informado em escala nominal, e usar o informado inverteria o sinal da glosa.

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

CampoTipoO que é
limiteinteiro
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.
deslocamentointeiro
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/guias \
  -H "Authorization: Bearer $MIYDAS_CHAVE"

Resposta 200

datalista de GuiaDoBeneficiarioO recurso. Os campos estão na tabela abaixo.
paginacaoPaginacaoOnde esta página está no total. Vem fora de data.

A guia pelo olhar da conciliação: os valores e o veredito do casamento entre cobrado e pago.

Campos de GuiaDoBeneficiario

CampoTipoO que é
guiaIdtextoA guia a que este registro se refere, pelo identificador do Miydas.
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.
numeroGuiaPrestadortextoO número que VOCÊ deu à guia. O TISS não deixa repetir dentro do prestador, e é por ele que você reencontra a guia aqui.
numeroGuiaOperadoratextoO número que a OPERADORA deu à guia. Só existe depois que ela respondeu, e é o número que vale numa discussão com ela.
lotetextoO número do lote em que esta guia foi enviada.
protocolotextoO protocolo que a operadora devolveu ao receber. É o número que prova a entrega e por onde se consulta o andamento depois.
executadoEmtextoQuando a execução ocorreu, em ISO 8601 com fuso.
pagoEmtextoData do crédito do pagamento.
valoresobjetoOs quatro números da guia. Ausência é null, nunca "0.00".
cobradotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
liberadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
diferencatextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
conciliacaoobjetoO cruzamento que o Miydas fez entre o cobrado e o pago — não é o que a operadora disse.
situacaoobjetoO veredito do motor de conciliação sobre a guia, como código e por extenso.
codigointeiroO código do veredito, de 0 a 7. descricao traz o mesmo em português — use o código na lógica.
descricaotextoO mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar.
glosaDeclaradabooleanoA operadora declarou glosa. false com diferença a menor é glosa silenciosa: cortaram sem dizer.
direcaoDiferencatextoA_MENOR | A_MAIOR | null.
percentualGlosanúmeroQuanto da cobrança virou glosa, em percentual com duas casas.
scoreConfiancanúmeroO quanto o casamento entre o que foi cobrado e o que foi pago é confiável.
prioridadeRevisaotextoO quanto esta guia merece atenção humana, combinando valor em jogo e confiança do casamento.

Exemplo de retorno

{
  "data": [
    {
      "guiaId": "cmf3k2x9a0001gcc",
      "operadora": {
        "registroANS": "334561"
      },
      "numeroGuiaPrestador": "000123",
      "numeroGuiaOperadora": "18700001",
      "lote": "202609",
      "protocolo": "PROTO-18700001",
      "executadoEm": "2026-09-12",
      "pagoEm": "2026-10-18",
      "valores": {
        "cobrado": "240.00",
        "liberado": "180.00",
        "glosado": "60.00",
        "diferenca": "60.00"
      },
      "conciliacao": {
        "situacao": {
          "codigo": 4,
          "descricao": "Glosa parcial"
        },
        "glosaDeclarada": true,
        "direcaoDiferenca": "A_MENOR",
        "percentualGlosa": 25,
        "scoreConfianca": 0.92,
        "prioridadeRevisao": "ALTA"
      }
    }
  ],
  "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_guias

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.