Faturamento
/v1/lotes/{id}/enviosTransmite o lote à operadora e registra o protocolo
É idempotente por estado: lote já transmitido devolve o que tem, sem falar com a operadora de novo — repetir o pedido é seguro, inclusive depois de um timeout seu. Se a transmissão sair e a resposta não chegar, o lote fica INDETERMINADO e o reenvio é BLOQUEADO: a operadora pode ter recebido, e reenviar cobraria a mesma guia duas vezes. Nesse caso, confirme no portal e registre em POST /v1/lotes/{id}/resolucoes.
- Escopo:
- lote:enviar
- Resposta:
- 200 ou 202
- Idempotência:
- aceita
Idempotency-Key - Espera:
- aceita
Prefer: wait=N
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 POST https://api.miydas.com.br/v1/lotes/cmf3k2x9a0001aut/envios \
-H "Authorization: Bearer $MIYDAS_CHAVE" \
-H "Prefer: wait=20" \
-H "Idempotency-Key: $(uuidgen)"Resposta 200 / 202
| 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": "PROCESSANDO",
"descricao": "A operadora recebeu e esta importando o lote.",
"acao": "Aguarde e consulte o lote. Nao gere lote novo.",
"motivo": null,
"em": "2026-09-27T13:05:10.000Z"
},
"conformidade": {
"xsdValido": true,
"erros": null
},
"totais": {
"guias": 1,
"procedimentos": 1,
"valorTotal": "12.50"
},
"protocolo": "PROTO-18700001",
"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_enviarO sandbox responde sempre em GET, mesmo para uma operação POST: ele devolve a forma da resposta, não executa nada.
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
| 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. |
| LOTE_INDETERMINADO | 409 | A transmissão deste lote começou e a resposta da operadora não chegou. Ela PODE ter recebido. | NÃO reenvie. Confirme no portal da operadora se o lote entrou e registre o resultado em POST /v1/lotes/{id}/resolucoes. Reenviar sem confirmar cobra a mesma guia duas vezes. |
| LOTE_XSD_INVALIDO | 409 | A transmissão foi pedida para um lote que não passou no esquema oficial. | Veja conformidade.erros no lote e crie um lote novo corrigido. A operadora recusaria. |
| LOTE_SEM_ANS | 400 | O lote não tem registro ANS, então não há como resolver a operadora. | Informe registroANS ao criar o lote. |
| AMBIENTE_SEM_ENVIO | 409 | Uma chave de teste (myd_test_) pediu a transmissão de um lote. Chave de teste opera só na homologação da operadora, e a homologação ainda não é alcançável por esta rota. | Monte e valide o lote com a chave de teste — isso não toca a operadora. Para transmitir, use uma chave de produção. |
| LOTE_TRANSMITINDO | 409 | A transmissão deste lote já está em curso no portal da operadora. Envio por portal é assíncrono, diferente do envio por webservice. | Aguarde e consulte o lote — o desfecho chega sem nova ação. Não repita o pedido: abriria uma segunda transmissão da mesma guia. |
| CONECTOR_SEM_SUBMIT | 400 | O conector desta operadora não envia lote. | Veja o que ela faz em GET /v1/operadoras/{registroANS}/capacidades. |
| OPERADORA_NAO_CONFIGURADA | 422 | A operadora do lote não tem conexão com credencial configurada. | Configure a conexão em POST /v1/conexoes e grave a credencial. |
| LOTE_RECUSADO | 422 | A operadora respondeu recusando o lote, com código e descrição TISS. O lote NÃO entrou. | Leia a mensagem, corrija o faturamento e crie um lote novo. Reenviar o mesmo terá o mesmo desfecho. |
| OPERADORA_NAO_ENCONTRADA | 404 | A empresa não tem essa operadora (registro ANS) cadastrada. | Veja as operadoras em GET /v1/operadoras. |
| OPERACAO_NAO_COBERTA | 422 | A operadora não oferece esta operação. details.operacoesDisponiveis lista o que ela oferece. | Não repita: a resposta não muda. |
| CREDENCIAL_AUSENTE | 422 | A empresa não cadastrou a credencial desta operadora. | Cadastre a credencial no Miydas e repita. |
| AMBIENTE_TESTE_INDISPONIVEL | 422 | A chave é de teste (myd_test_…) e o pedido não cabe na homologação: a empresa não tem homologação configurada para esta operadora; ou a operação grava dado de produção (lote, retorno, recurso de glosa, cancelamento por número, anexos, documentos, cadastro de convênio); ou tenta trocar o endereço, o conector ou a agenda da conexão de homologação. A chave de teste nunca opera em produção. | Configure a homologação da operadora no Miydas; para autorização e elegibilidade use /v1/autorizacoes e /v1/elegibilidades; o resto, com a chave de produção. |
| LIMITE_EXCEDIDO | 429 | Muitas operações em andamento para esta operadora nesta empresa. | Espere e repita — com a mesma Idempotency-Key, se for escrita. |
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.