Faturamento
GET
/v1/lotes/{id}Um lote: se chegou à operadora, e o que ela fez com ele
- Escopo:
- lote: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/lotes/cmf3k2x9a0001aut \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | Lote | O recurso. Os campos estão na tabela abaixo. |
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": "TRANSMITIDO",
"descricao": "Recebido pela operadora, com protocolo. Veja `processamento` para o que ela fez com o conteudo.",
"podeEnviar": false
},
"processamento": {
"codigo": "REJEITADO",
"descricao": "A operadora recebeu o lote e recusou o conteudo. NENHUMA conta entrou.",
"acao": "Corrija o que o motivo aponta e gere um lote NOVO. Nao retransmita este: ele ja esta protocolado.",
"motivo": "CM104 - NUMERO DE GUIA INVALIDO",
"em": "2026-09-27T13:06:00.000Z"
},
"conformidade": {
"xsdValido": true,
"erros": null
},
"totais": {
"guias": 1,
"procedimentos": 1,
"valorTotal": "12.50"
},
"protocolo": "32568556",
"transmitidoEm": "2026-09-27T13:05:00.000Z",
"ultimoErro": null,
"criadoEm": "2026-09-27T13:00:00.000Z"
}
}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_obterA 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.