Ogmma Revenue

Guias

GET/v1/guias

A 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

CampoTipoO que é
buscatexto
1–120 caracteres
Texto a procurar. Casa por pedaço do nome e também pelo código, sem diferenciar acento nem caixa.
registroANStexto
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.
competenciatexto
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.
numeroLotetexto
1–60 caracteres
O número do lote, como ele foi transmitido à operadora.
camadatexto
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.
comGlosatexto
um de: true, false
Só as linhas com glosa (true) ou só as sem (false). Omitido, traz as duas.
limiteinteiro
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.
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/guias \
  -H "Authorization: Bearer $MIYDAS_CHAVE"

Resposta 200

datalista de GuiaO recurso. Os campos estão na tabela abaixo.
paginacaoPaginacaoOnde 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

CampoTipoO que é
idtextoIdentificador 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.
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.
numeroLotetextoO número do lote, como ele foi transmitido à operadora.
numeroProtocolotextoO número do protocolo na operadora.
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.
nometextoRazão social da operadora como a ANS a publica. Informativo — a chave é o registro.
beneficiariotextoO 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.
carteiratextoNúmero da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador.
dataExecucaotextoData em que o procedimento foi executado, AAAA-MM-DD.
creditoEmtextoData em que o dinheiro caiu — a data de NEGÓCIO do documento de pagamento, e a que define a competência dele.
camadasobjetoQuais 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".
enviobooleanoO lote saiu daqui. Falso em 40.746 das 40.760 guias — o portal devolve julgamento, não o arquivo enviado.
analisebooleanoExiste documento de análise para esta guia — a operadora já julgou a conta.
pagamentobooleanoExiste documento de pagamento — ela já declarou o crédito. Sem esta camada, pago é nulo.
completudeAnalisetextoA completude do documento de análise que chegou. Num GLOSA_ONLY, o cobrado e o liberado não vieram — não são zero.
cobradotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
cobradoDaOperadorabooleanoSem envio, o cobrado é a palavra da operadora — a única testemunha que sobrou.
processadotextoO que a operadora reconheceu como devido.
liberadotextoO que ela aceitou pagar — julgamento da análise.
glosatextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
pagotextoO que o demonstrativo de PAGAMENTO declara. Nulo enquanto essa camada não existir.
diferencatextocobrado − liberado. Nulo quando um dos lados falta: indeterminada não é zero.
divergenciaPagamentotextopago − liberado. Positivo = pagou mais.
situacaoPagamentoobjetoDERIVADA de pago × liberado. A coluna statusPagamento está nula em 39.131 de 39.131 linhas.
codigotexto
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.
descricaotextoO mesmo veredito em português, para exibir.
pagamentosinteiroQuantas datas de crédito somaram em pago. >1 merece conferência.
temGlosaDeclaradabooleanoA operadora declarou glosa nesta guia. Diferente de ter pago a menor sem declarar — isso é glosa silenciosa.
motivoslista de objetosOs motivos de glosa que pesam sobre esta guia, somando os do nível da guia e os dos itens dela.
codigotextoO código do motivo, como a operadora o emitiu. Na glosa, é o código da Tabela 38 da ANS quando ela usa o oficial.
descricaotextoO motivo em texto, na língua da operadora — não traduzido.
origemtextoDe que nível o motivo veio: GUIA ou ITEM.
itensobjetoQuantas linhas cada lado tem. Números diferentes já indicam divergência antes de abrir os itens.
enviointeiroQuantos itens saíram daqui. Nulo quando não há camada de envio.
retornointeiroQuantos 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_listar

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

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.