Faturamento
/v1/lotesLotes 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
| Campo | Tipo | O que é |
|---|---|---|
| competencia | texto 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. |
| situacao | texto 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. |
| processamento | texto um de: PROCESSANDO, ACEITO, REJEITADO | O julgamento do CONTEÚDO pela operadora, que é outra pergunta: um lote transmitido com sucesso pode estar REJEITADO aqui. |
| referenciaExterna | texto 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. |
| 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. |
| protocolo | texto 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. |
| enviadoDe | texto formato AAAA-MM-DD | Transmitidos a partir deste dia, AAAA-MM-DD. O intervalo é fechado: o dia informado entra. |
| enviadoAte | texto formato AAAA-MM-DD | Transmitidos até este dia, AAAA-MM-DD, inclusive — o dia inteiro entra. |
| criadoDe | texto 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. |
| criadoAte | texto formato AAAA-MM-DD | Criados no Miydas até este dia, AAAA-MM-DD, inclusive. |
| limite | inteiro 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. |
| 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/lotes \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de Lote | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde 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
| 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. |
| referenciaExterna | texto | O id do lote no seu sistema. Chave de idempotência. |
| 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. |
| competencia | texto | YYYY-MM |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| situacao | objeto | A TRANSMISSÃO: o lote chegou à operadora e ganhou protocolo? Não diz o que a operadora achou do conteúdo — isso é processamento. |
| codigo | texto 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. |
| descricao | texto | O mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar. |
| podeEnviar | booleano | Este lote pode ser transmitido agora. false em lote já transmitido, inválido ou indeterminado. |
| processamento | objeto | O 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. |
| codigo | texto um de: PROCESSANDO, ACEITO, REJEITADO | O veredito sobre o conteúdo. REJEITADO com situacao TRANSMITIDO é caso real: chegou, foi protocolado, e nenhuma conta passou. |
| descricao | texto | O mesmo estado de processamento.codigo, em português, para mostrar a gente. O contrato é o código. |
| acao | texto | O que fazer agora. Em REJEITADO: corrigir e gerar lote NOVO, nunca retransmitir este. |
| motivo | texto | O motivo na língua da operadora (ex. "CM104 - NUMERO DE GUIA INVALIDO"). |
| em | texto | Quando soubemos do julgamento. |
| conformidade | objeto | Veredito do esquema oficial da ANS. Lote inválido é recusado na transmissão. |
| xsdValido | booleano | O documento passou no esquema oficial da ANS (XSD). Lote inválido é recusado antes de ir à operadora. |
| erros | — | O que falhou, item por item. |
| totais | objeto | Os totais do documento, já somados. |
| guias | inteiro | Quantas guias o lote leva. |
| procedimentos | inteiro | Quantas linhas de procedimento o lote leva, somando todas as guias. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| 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. |
| transmitidoEm | texto | Quando o lote foi transmitido à operadora, em ISO 8601 com fuso. |
| ultimoErro | texto | Texto para humano. O contrato é o código do erro, não esta frase. |
| criadoEm | texto | Quando 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_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.