Guias
GET
/v1/guias/{id}Uma guia, com as três camadas e os cinco valores
- Escopo:
- guia:ler
- Resposta:
- 200
Pedido
Caminho
| {id}* | Identificador do recurso no Miydas. Opaco e estável — NÃO é o número que a operadora ou o seu sistema usam para a mesma coisa. Guarde-o como veio e não derive significado do formato. |
Exemplo de chamada
curl -X GET https://api.miydas.com.br/v1/guias/cmf3k2x9a0001aut \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | Guia | O recurso. Os campos estão na tabela abaixo. |
A guia pelas três camadas que a atravessam: envio, análise e pagamento.
Campos de Guia
| Campo | Tipo | O que é |
|---|---|---|
| id | texto | Identificador do recurso no Miydas. Opaco e estável — NÃO é o número que a operadora ou o seu sistema usam para a mesma coisa. Guarde-o como veio e não derive significado do formato. |
| 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. |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| numeroProtocolo | texto | O número do protocolo na operadora. |
| 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. |
| nome | texto | Razão social da operadora como a ANS a publica. Informativo — a chave é o registro. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| dataExecucao | texto | Data em que o procedimento foi executado, AAAA-MM-DD. |
| creditoEm | texto | Data em que o dinheiro caiu — a data de NEGÓCIO do documento de pagamento, e a que define a competência dele. |
| camadas | objeto | Quais documentos existem para esta guia. MEDIDO nas tabelas de retorno, não inferido da coluna: o motor grava zero e não nulo, então a coluna não distingue "não mandou" de "mandou zero". |
| envio | booleano | O lote saiu daqui. Falso em 40.746 das 40.760 guias — o portal devolve julgamento, não o arquivo enviado. |
| analise | booleano | Existe documento de análise para esta guia — a operadora já julgou a conta. |
| pagamento | booleano | Existe documento de pagamento — ela já declarou o crédito. Sem esta camada, pago é nulo. |
| completudeAnalise | texto | A completude do documento de análise que chegou. Num GLOSA_ONLY, o cobrado e o liberado não vieram — não são zero. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| cobradoDaOperadora | booleano | Sem envio, o cobrado é a palavra da operadora — a única testemunha que sobrou. |
| processado | texto | O que a operadora reconheceu como devido. |
| liberado | texto | O que ela aceitou pagar — julgamento da análise. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| pago | texto | O que o demonstrativo de PAGAMENTO declara. Nulo enquanto essa camada não existir. |
| diferenca | texto | cobrado − liberado. Nulo quando um dos lados falta: indeterminada não é zero. |
| divergenciaPagamento | texto | pago − liberado. Positivo = pagou mais. |
| situacaoPagamento | objeto | DERIVADA de pago × liberado. A coluna statusPagamento está nula em 39.131 de 39.131 linhas. |
| codigo | texto um de: PAGO_INTEGRAL, PAGO_PARCIAL, PAGO_A_MAIOR, NAO_PAGO | O confronto entre o que foi pago e o que foi liberado. PAGO_A_MAIOR existe e costuma ser reemissão contada duas vezes — confira pagamentos. |
| descricao | texto | O mesmo veredito em português, para exibir. |
| pagamentos | inteiro | Quantas datas de crédito somaram em pago. >1 merece conferência. |
| temGlosaDeclarada | booleano | A operadora declarou glosa nesta guia. Diferente de ter pago a menor sem declarar — isso é glosa silenciosa. |
| motivos | lista de objetos | Os motivos de glosa que pesam sobre esta guia, somando os do nível da guia e os dos itens dela. |
| codigo | texto | O código do motivo, como a operadora o emitiu. Na glosa, é o código da Tabela 38 da ANS quando ela usa o oficial. |
| descricao | texto | O motivo em texto, na língua da operadora — não traduzido. |
| origem | texto | De que nível o motivo veio: GUIA ou ITEM. |
| itens | objeto | Quantas linhas cada lado tem. Números diferentes já indicam divergência antes de abrir os itens. |
| envio | inteiro | Quantos itens saíram daqui. Nulo quando não há camada de envio. |
| retorno | inteiro | Quantos itens a operadora devolveu. |
Exemplo de retorno
{
"data": {
"id": "cmf3k2x9a0001gui",
"numeroGuiaPrestador": "000123",
"numeroGuiaOperadora": "18700001",
"numeroLote": "2026070112",
"numeroProtocolo": "4530775",
"operadora": {
"registroANS": "334561",
"nome": "Unimed Blumenau"
},
"beneficiario": "PACIENTE EXEMPLO",
"carteira": "00000000000000000",
"dataExecucao": "2026-07-02",
"creditoEm": "2026-07-15",
"camadas": {
"envio": false,
"analise": true,
"pagamento": true,
"completudeAnalise": "FULL"
},
"cobrado": "3.65",
"cobradoDaOperadora": true,
"processado": "3.65",
"liberado": "3.56",
"glosa": "0.09",
"pago": "3.56",
"diferenca": "0.09",
"divergenciaPagamento": "0.00",
"situacaoPagamento": {
"codigo": "PAGO_INTEGRAL",
"descricao": "Pago integralmente"
},
"pagamentos": 1,
"temGlosaDeclarada": true,
"motivos": [
{
"codigo": "1705",
"descricao": "VALOR APRESENTADO A MAIOR",
"origem": "ITEM"
}
],
"itens": {
"envio": null,
"retorno": 19
}
}
}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/guias_detalheA 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.