Ogmma Revenue

Faturamento

POST/v1/lotes

Monta 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)

CampoTipoO 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*objetoQuem executou e está cobrando — a clínica, laboratório ou centro de imagem.
nometexto
até 100 caracteres
Razão social ou nome do prestador.
cnpjtexto
até 18 caracteres
CNPJ, 14 dígitos. Aceito com ou sem máscara; devolvido sem.
cnestexto
até 10 caracteres
Código do estabelecimento no CNES, sete dígitos.
codigoNaOperadoratexto
até 20 caracteres
O código deste prestador na operadora, como ela o cadastrou.
uftexto
até 2 caracteres
Sigla da unidade federativa, duas letras (ex. SC).
profissionalobjetoO profissional responsável, como ele vai no documento TISS.
nometexto
até 100 caracteres
Nome do profissional.
conselhotexto
até 10 caracteres
Sigla do conselho profissional (CRM, CRO, COREN…).
numeroConselhotexto
até 20 caracteres
Número de inscrição do profissional no conselho.
uftexto
até 2 caracteres
Sigla da unidade federativa, duas letras (ex. SC).
cbotexto
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.
autorizacaotexto
até 20 caracteres
A senha de autorização concedida pela operadora, quando ela exigiu uma.
numeroGuiaOperadoratexto
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.
dataAutorizacaotexto
formato AAAA-MM-DD
Data em que a operadora autorizou, AAAA-MM-DD.
dataValidadeSenhatexto
formato AAAA-MM-DD
Último dia em que a senha de autorização pode ser usada, AAAA-MM-DD.
indicacaoClinicatexto
até 500 caracteres
A justificativa clínica do pedido, em texto livre. É o que a operadora lê para decidir.
beneficiario*objetoO 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.
carteirinhatexto
até 30 caracteres
Número da carteirinha do beneficiário na operadora, como está no cartão.
nascimentotexto
formato AAAA-MM-DD
Data de nascimento, AAAA-MM-DD.
cpftexto
até 14 caracteres
CPF, 11 dígitos. Aceito com ou sem máscara.
sexotexto
até 1 caracteres
Sexo como a operadora o codifica: M, F ou I (indeterminado).
planotexto
até 60 caracteres
Nome do plano do beneficiário na operadora.
procedimentos*lista de objetosOs 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.
quantidadeinteiro
padrão 1
Quantas unidades do procedimento. Inteiro, a partir de 1.
valorUnitario*númeroValor de uma unidade do procedimento, em reais, decimal em string.
dataExecucaotexto
formato AAAA-MM-DD
Data em que o procedimento foi executado, AAAA-MM-DD.
valorTotal*númeroSoma 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

dataLoteO 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

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"
  }
}

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_criar

O 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ódigoHTTPQuandoO que fazer
LOTE_JA_TRANSMITIDO409Já 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_VAZIO400O lote não tem nenhum procedimento.Inclua ao menos um procedimento em alguma guia.
OPERADORA_NAO_ENCONTRADA404A empresa não tem essa operadora (registro ANS) cadastrada.Veja as operadoras em GET /v1/operadoras.
LOTE_REGRA_DA_OPERADORA422O 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.