Faturamento
/v1/lotesMonta o lote: gera a mensagem TISS e valida no esquema oficial. NÃO transmite
Você descreve o faturamento — prestador, beneficiário, procedimentos — e o Miydas monta a mensagem TISS na versão que a operadora aceita. Montar é reversível e barato; transmitir é irreversível na operadora, e por isso é outro pedido (POST /v1/lotes/{id}/envios). Confira conformidade.xsdValido antes de enviar: lote inválido é recusado na transmissão. referenciaExterna é a chave de idempotência — repetir o POST devolve o mesmo lote, e um lote já transmitido não pode ser substituído (corrija criando outro, com nova referência).
- Escopo:
- lote:gerenciar
- Resposta:
- 201
- Idempotência:
- aceita
Idempotency-Key
Pedido
Corpo (JSON)
| Campo | Tipo | O que é |
|---|---|---|
| referenciaExterna* | texto 1–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. |
| operadora* | texto 1–100 caracteres | O nome da operadora como VOCÊ a chama. É rótulo, para você reencontrar o lote: quem resolve conector e credencial é o registroANS. |
| registroANS* | texto 1–10 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. |
| 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. |
| prestador* | objeto | Quem executou e está cobrando — a clínica, laboratório ou centro de imagem. |
| nome | texto até 100 caracteres | Razão social ou nome do prestador. |
| cnpj | texto até 18 caracteres | CNPJ, 14 dígitos. Aceito com ou sem máscara; devolvido sem. |
| cnes | texto até 10 caracteres | Código do estabelecimento no CNES, sete dígitos. |
| codigoNaOperadora | texto até 20 caracteres | O código deste prestador na operadora, como ela o cadastrou. |
| uf | texto até 2 caracteres | Sigla da unidade federativa, duas letras (ex. SC). |
| profissional | objeto | O profissional responsável, como ele vai no documento TISS. |
| nome | texto até 100 caracteres | Nome do profissional. |
| conselho | texto até 10 caracteres | Sigla do conselho profissional (CRM, CRO, COREN…). |
| numeroConselho | texto até 20 caracteres | Número de inscrição do profissional no conselho. |
| uf | texto até 2 caracteres | Sigla da unidade federativa, duas letras (ex. SC). |
| cbo | texto até 10 caracteres | Ocupação do profissional na CBO, seis dígitos. |
| guias* | lista de objetos 1–100 itens | As guias que compõem este lote. |
| numeroGuiaPrestador* | texto 1–20 caracteres | O número que VOCÊ deu à guia. O TISS não deixa repetir dentro do prestador, e é por ele que você reencontra a guia aqui. |
| autorizacao | texto até 20 caracteres | A senha de autorização concedida pela operadora, quando ela exigiu uma. |
| numeroGuiaOperadora | texto até 20 caracteres | O número que a OPERADORA deu à guia. Só existe depois que ela respondeu, e é o número que vale numa discussão com ela. |
| dataAutorizacao | texto formato AAAA-MM-DD | Data em que a operadora autorizou, AAAA-MM-DD. |
| dataValidadeSenha | texto formato AAAA-MM-DD | Último dia em que a senha de autorização pode ser usada, AAAA-MM-DD. |
| indicacaoClinica | texto até 500 caracteres | A justificativa clínica do pedido, em texto livre. É o que a operadora lê para decidir. |
| beneficiario* | objeto | O beneficiário do plano atendido nesta guia. |
| nome* | texto 1–100 caracteres | Nome do beneficiário como a operadora o devolveu — pode divergir do seu cadastro. |
| carteirinha | texto até 30 caracteres | Número da carteirinha do beneficiário na operadora, como está no cartão. |
| nascimento | texto formato AAAA-MM-DD | Data de nascimento, AAAA-MM-DD. |
| cpf | texto até 14 caracteres | CPF, 11 dígitos. Aceito com ou sem máscara. |
| sexo | texto até 1 caracteres | Sexo como a operadora o codifica: M, F ou I (indeterminado). |
| plano | texto até 60 caracteres | Nome do plano do beneficiário na operadora. |
| procedimentos* | lista de objetos | Os procedimentos executados nesta guia. |
| tuss* | texto 1–20 caracteres | Código do procedimento na TUSS, a terminologia da ANS. |
| descricao* | texto 1–200 caracteres | Descrição do procedimento, como ela vai no documento. |
| quantidade | inteiro padrão 1 | Quantas unidades do procedimento. Inteiro, a partir de 1. |
| valorUnitario* | número | Valor de uma unidade do procedimento, em reais, decimal em string. |
| dataExecucao | texto formato AAAA-MM-DD | Data em que o procedimento foi executado, AAAA-MM-DD. |
| valorTotal* | número | Soma em reais, decimal em string com duas casas. |
* 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 POST https://api.miydas.com.br/v1/lotes \
-H "Authorization: Bearer $MIYDAS_CHAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"referenciaExterna": "fatura-2026-09-0042",
"operadora": "Unimed Blumenau",
"registroANS": "334561",
"competencia": "2026-09",
"prestador": {
"nome": "Laboratório Exemplo",
"cnpj": "00000000000191",
"cnes": "0000000",
"codigoNaOperadora": "12345",
"uf": "42",
"profissional": {
"nome": "Médica Exemplo",
"conselho": "06",
"numeroConselho": "12345",
"uf": "42",
"cbo": "225124"
}
},
"guias": [
{
"numeroGuiaPrestador": "000123",
"autorizacao": "18700001",
"beneficiario": {
"nome": "PACIENTE EXEMPLO",
"carteirinha": "00000000000000000",
"nascimento": "1980-01-01"
},
"procedimentos": [
{
"tuss": "40304361",
"descricao": "Hemograma com contagem de plaquetas",
"quantidade": 1,
"valorUnitario": 12.5
}
],
"valorTotal": 12.5
}
]
}'Resposta 201
| 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": "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"
}
}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_criarO 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 |
|---|---|---|---|
| LOTE_JA_TRANSMITIDO | 409 | Já existe um lote com esta referenciaExterna e ele foi transmitido (ou está indeterminado). Lote transmitido é imutável. | Para corrigir, crie um lote NOVO com outra referenciaExterna. details traz o protocolo e a data do original. |
| LOTE_VAZIO | 400 | O lote não tem nenhum procedimento. | Inclua ao menos um procedimento em alguma guia. |
| OPERADORA_NAO_ENCONTRADA | 404 | A empresa não tem essa operadora (registro ANS) cadastrada. | Veja as operadoras em GET /v1/operadoras. |
| LOTE_REGRA_DA_OPERADORA | 422 | O lote é válido no esquema oficial, mas viola uma regra MEDIDA desta operadora — ela o recusaria na importação. Recusado aqui, antes de transmitir, porque transmitir é irreversível e gasta um protocolo. | Leia detalhes.violacoes: cada item traz o que corrigir e o código da crítica que a operadora devolveu quando isso passou. Corrija e repita o POST — nada foi transmitido. |
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.