Beneficiário
/v1/beneficiarios/{carteira}/guiasToda 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
| 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/guias \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de GuiaDoBeneficiario | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde 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
| Campo | Tipo | O que é |
|---|---|---|
| guiaId | texto | A guia a que este registro se refere, 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. |
| numeroGuiaPrestador | texto | O número que VOCÊ deu à guia. O TISS não deixa repetir dentro do prestador, e é por ele que você reencontra a guia aqui. |
| numeroGuiaOperadora | texto | O número que a OPERADORA deu à guia. Só existe depois que ela respondeu, e é o número que vale numa discussão com ela. |
| lote | texto | O número do lote em que esta guia foi enviada. |
| protocolo | texto | O protocolo que a operadora devolveu ao receber. É o número que prova a entrega e por onde se consulta o andamento depois. |
| executadoEm | texto | Quando a execução ocorreu, em ISO 8601 com fuso. |
| pagoEm | texto | Data do crédito do pagamento. |
| valores | objeto | Os quatro números da guia. Ausência é null, nunca "0.00". |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| diferenca | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| conciliacao | objeto | O cruzamento que o Miydas fez entre o cobrado e o pago — não é o que a operadora disse. |
| situacao | objeto | O veredito do motor de conciliação sobre a guia, como código e por extenso. |
| codigo | inteiro | O código do veredito, de 0 a 7. descricao traz o mesmo em português — use o código na lógica. |
| descricao | texto | O mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar. |
| glosaDeclarada | booleano | A operadora declarou glosa. false com diferença a menor é glosa silenciosa: cortaram sem dizer. |
| direcaoDiferenca | texto | A_MENOR | A_MAIOR | null. |
| percentualGlosa | número | Quanto da cobrança virou glosa, em percentual com duas casas. |
| scoreConfianca | número | O quanto o casamento entre o que foi cobrado e o que foi pago é confiável. |
| prioridadeRevisao | texto | O 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_guiasA 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.