Ogmma Revenue

Faturamento

GET/v1/lotes

Lotes da clínica, por operadora, período, protocolo e situação

Filtra por operadora (registroANS), por período de transmissão (enviadoDe/enviadoAte) ou de criação (criadoDe/criadoAte), por protocolo e por competência. As datas são AAAA-MM-DD e o intervalo é fechado dos dois lados: ate inclui o dia inteiro. situacao e processamento respondem perguntas diferentes: a primeira é se o lote CHEGOU, a segunda é o que a operadora fez com o conteúdo. Um lote ENVIADO com protocolo pode ter sido REJEITADO — nenhuma conta entrou, e nada em situacao diz isso.

Escopo:
lote:ler
Resposta:
200

Pedido

Parâmetros de query

CampoTipoO que é
competenciatexto
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.
situacaotexto
um de: VALIDADO, ERRO_XSD, ENVIADO, ERRO_ENVIO, INDETERMINADO, TRANSMITINDO
O estado da TRANSMISSÃO do lote. INDETERMINADO é o caso que exige gente: a conexão caiu sem resposta e não se sabe se a operadora recebeu — reenviar às cegas duplica.
processamentotexto
um de: PROCESSANDO, ACEITO, REJEITADO
O julgamento do CONTEÚDO pela operadora, que é outra pergunta: um lote transmitido com sucesso pode estar REJEITADO aqui.
referenciaExternatexto
até 64 caracteres
O identificador deste objeto NO SEU sistema. É a chave de idempotência: repetir o pedido com a mesma referência devolve o mesmo recurso em vez de criar outro.
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.
protocolotexto
1–40 caracteres
O protocolo que a operadora devolveu ao receber. É o número que prova a entrega e por onde se consulta o andamento depois.
enviadoDetexto
formato AAAA-MM-DD
Transmitidos a partir deste dia, AAAA-MM-DD. O intervalo é fechado: o dia informado entra.
enviadoAtetexto
formato AAAA-MM-DD
Transmitidos até este dia, AAAA-MM-DD, inclusive — o dia inteiro entra.
criadoDetexto
formato AAAA-MM-DD
Criados no Miydas a partir deste dia, AAAA-MM-DD. Diferente de enviadoDe: lote pode nascer hoje e ser transmitido semana que vem.
criadoAtetexto
formato AAAA-MM-DD
Criados no Miydas até este dia, AAAA-MM-DD, inclusive.
limiteinteiro
1–100 · padrão 25
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/lotes \
  -H "Authorization: Bearer $MIYDAS_CHAVE"

Resposta 200

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

Um lote de faturamento. A mensagem TISS em si não aparece aqui de propósito: formato é implementação, e o integrador precisa do veredito, não do XML.

Campos de Lote

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.
referenciaExternatextoO id do lote no seu sistema. Chave de idempotência.
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.
competenciatextoYYYY-MM
numeroLotetextoO número do lote, como ele foi transmitido à operadora.
situacaoobjetoA TRANSMISSÃO: o lote chegou à operadora e ganhou protocolo? Não diz o que a operadora achou do conteúdo — isso é processamento.
codigotexto
um de: PRONTO, INVALIDO, TRANSMITIDO, TRANSMITINDO, RECUSADO, INDETERMINADO
O estado da transmissão. INDETERMINADO é o que exige gente: a conexão caiu sem resposta e não se sabe se a operadora recebeu — reenviar às cegas duplica o faturamento.
descricaotextoO mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar.
podeEnviarbooleanoEste lote pode ser transmitido agora. false em lote já transmitido, inválido ou indeterminado.
processamentoobjetoO JULGAMENTO DO CONTEÚDO pela operadora. Outra pergunta, outra resposta: um lote TRANSMITIDO pode estar REJEITADO aqui — recebido e protocolado, com nenhuma conta aceita. null é "ainda não se sabe", nunca "aceito": a importação da operadora é assíncrona.
codigotexto
um de: PROCESSANDO, ACEITO, REJEITADO
O veredito sobre o conteúdo. REJEITADO com situacao TRANSMITIDO é caso real: chegou, foi protocolado, e nenhuma conta passou.
descricaotextoO mesmo estado de processamento.codigo, em português, para mostrar a gente. O contrato é o código.
acaotextoO que fazer agora. Em REJEITADO: corrigir e gerar lote NOVO, nunca retransmitir este.
motivotextoO motivo na língua da operadora (ex. "CM104 - NUMERO DE GUIA INVALIDO").
emtextoQuando soubemos do julgamento.
conformidadeobjetoVeredito do esquema oficial da ANS. Lote inválido é recusado na transmissão.
xsdValidobooleanoO documento passou no esquema oficial da ANS (XSD). Lote inválido é recusado antes de ir à operadora.
erros—O que falhou, item por item.
totaisobjetoOs totais do documento, já somados.
guiasinteiroQuantas guias o lote leva.
procedimentosinteiroQuantas linhas de procedimento o lote leva, somando todas as guias.
valorTotaltextoDecimal em string, duas casas — dinheiro não é number.
protocolotextoO protocolo que a operadora devolveu ao receber. É o número que prova a entrega e por onde se consulta o andamento depois.
transmitidoEmtextoQuando o lote foi transmitido à operadora, em ISO 8601 com fuso.
ultimoErrotextoTexto para humano. O contrato é o código do erro, não esta frase.
criadoEmtextoQuando o registro nasceu no Miydas, em ISO 8601 com fuso.

Exemplo de retorno

{
  "data": [
    {
      "id": "cmf3k2x9a0001lot",
      "referenciaExterna": "fatura-2026-09-0042",
      "operadora": {
        "registroANS": "334561",
        "nome": "Unimed Blumenau"
      },
      "competencia": "2026-09",
      "numeroLote": "202609",
      "situacao": {
        "codigo": "PRONTO",
        "descricao": "Montado e válido no XSD. Pronto para transmitir.",
        "podeEnviar": true
      },
      "processamento": null,
      "conformidade": {
        "xsdValido": true,
        "erros": null
      },
      "totais": {
        "guias": 1,
        "procedimentos": 1,
        "valorTotal": "12.50"
      },
      "protocolo": null,
      "transmitidoEm": null,
      "ultimoErro": null,
      "criadoEm": "2026-09-27T13:00:00.000Z"
    }
  ],
  "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/lotes_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.