Guias
/v1/guiasA guia pelas três camadas: envio, análise e pagamento
Cinco valores por linha — cobrado, processado, liberado, glosa e pago. liberado é o julgamento da análise; pago é o que o demonstrativo de pagamento declara. São duas respostas da operadora, com meses de distância, e é o pago que faz o relógio do prazo de recurso andar.
Ausência é null, nunca "0.00". A presença de cada camada é MEDIDA nas tabelas de retorno, não inferida da coluna: o motor grava zero e não nulo, então a coluna não distingue "não mandou" de "mandou zero".
camada=SEM_ENVIO e camada=SEM_RETORNO listam os buracos. Sem filtro por situação de conciliação, de propósito: isto é arquivo consultável, não fila de trabalho.
- Escopo:
- guia:ler
- Resposta:
- 200
Pedido
Parâmetros de query
| Campo | Tipo | O que é |
|---|---|---|
| busca | texto 1–120 caracteres | Texto a procurar. Casa por pedaço do nome e também pelo código, sem diferenciar acento nem caixa. |
| registroANS | texto 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. |
| competencia | texto ou sem-data · formato AAAA-MM | Mês AAAA-MM da data de NEGÓCIO do documento, em UTC — crédito na retenção, protocolo na glosa. NUNCA a data de emissão: o portal renderiza o documento no download, então a emissão é o dia em que nós baixamos. |
| numeroLote | texto 1–60 caracteres | O número do lote, como ele foi transmitido à operadora. |
| camada | texto um de: SEM_ENVIO, SEM_RETORNO | O BURACO, não o estado. SEM_ENVIO: voltou retorno de guia que nunca saiu daqui. SEM_RETORNO: a guia saiu e a operadora nunca respondeu — é faturamento parado sem ninguém ter sido avisado. |
| comGlosa | texto um de: true, false | Só as linhas com glosa (true) ou só as sem (false). Omitido, traz as duas. |
| limite | inteiro 1–100 · 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/guias \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de Guia | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde esta página está no total. Vem fora de data. |
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
}
}
],
"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/guias_listarA 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.