Ogmma Revenue

Faturamento

POST/v1/itens-faturaveis

Manda os exames realizados, para conferir antes de faturar

A porta de entrada do pré-faturamento. Até aqui o caminho vivo era o lote TISS pronto: nenhum procedimento individual entrava, e a conferência antes do envio não tinha sobre o que rodar. IDEMPOTENTE PELO idNaOrigem, que tem de ser estável no seu sistema: é por ele que a segunda remessa reconhece o mesmo exame em vez de cobrá-lo duas vezes. Reenviar o arquivo do dia atualiza as linhas e resumo diz quantas nasceram e quantas já existiam. O reenvio NÃO volta atrás no que já andou: situação de faturamento, resultado de auditoria e responsável são do Miydas. Um exame já posto em guia não retorna para A_FATURAR. Valor é opcional. Quando você manda unitário e total, os dois são gravados como vieram — o total pode trazer desconto ou pacote do seu contrato, e recalcular seria decidir por você quanto cobrar.

Escopo:
faturavel:registrar
Resposta:
201

Pedido

Corpo (JSON)

CampoTipoO que é
itens*lista de objetos
1–500 itens
Os exames realizados desta remessa. Até 500 por pedido.
idNaOrigem*texto
1–120 caracteres
O identificador do exame NO SEU SISTEMA. Tem de ser estável: é por ele que a remessa seguinte reconhece o mesmo exame em vez de cobrá-lo duas vezes.
descricao*texto
1–200 caracteres
Descrição do item, como a fonte a informou.
codigoTusstexto
até 10 caracteres
Código do procedimento na TUSS, a terminologia da ANS.
codigoTabelatexto
até 2 caracteres
Qual tabela o código usa (22 = TUSS procedimentos, 18/19/20 = materiais, taxas e medicamentos, 00 = tabela própria da operadora).
quantidadenúmero
0–99999
Quantas unidades, como o documento declarou. Vem em texto porque a operadora às vezes manda fracionado (1,5) e arredondar aqui mudaria o valor da conta.
tipoItemtexto
um de: PROCEDIMENTO, MATERIAL, MEDICAMENTO, TAXA, DIARIA, GAS, OPME
O que a linha é: PROCEDIMENTO (o padrão), MATERIAL, MEDICAMENTO, TAXA, DIARIA, GAS ou OPME. Procedimento e despesa dividem a mesma numeração dentro da guia, e é por ela que a operadora devolve o julgamento de cada um.
unidadeMedidatexto
até 20 caracteres
Unidade em que a quantidade é contada, no código de TRÊS dígitos da tabela 60 do TUSS (001 a 061). Obrigatória em despesa — o padrão TISS recusa despesa sem ela, e texto livre como "ampola" não serve.
itemVinculadotexto
até 120 caracteres
Em despesa: o idNaOrigem do procedimento que a consumiu. É o que permite à operadora julgar o material contra o exame que o usou.
codigoDespesatexto
até 10 caracteres
O tipo da despesa para a operadora (dm_outrasDespesas). Quando ausente, é deduzido de tipoItem.
registroAnvisatexto
até 15 caracteres
Registro ANVISA do material ou medicamento, quando a operadora o exige.
refFabricantetexto
até 60 caracteres
Referência do fabricante do material, quando a operadora a exige.
solicitanteNometexto
até 70 caracteres
Nome do médico solicitante. Em branco, a emissão usa o solicitante padrão cadastrado para o convênio.
solicitanteConselhotexto
até 10 caracteres
O conselho do solicitante (06 = CRM), como em dm_conselhoProfissional.
solicitanteNumerotexto
até 15 caracteres
O número do solicitante no conselho.
solicitanteUftexto
até 2 caracteres
A UF do conselho do solicitante — sigla ou código IBGE; a emissão converte.
solicitanteCbotexto
até 10 caracteres
O CBO do solicitante.
senhaInformadatexto
até 20 caracteres
A senha de autorização que VOCÊ já recebeu da operadora por outro canal. Diferente da autorização solicitada por nós no portal: esta é declarada, não conquistada aqui.
guiaOperadoraInformadatexto
até 20 caracteres
O número da guia na operadora, quando você já o tem.
validadeSenhaInformadatextoAté quando a senha informada vale, AAAA-MM-DD.
guiaPrestadorInformadatexto
até 20 caracteres
Número que a origem já atribuiu à guia. Mantém a mesma identidade do lote do cliente até a autorização e o lote daqui.
valorUnitario—Valor de uma unidade do procedimento, em reais, decimal em string.
valorTotal—Soma em reais, decimal em string com duas casas.
dataExecucaotextoData em que o procedimento foi executado, AAAA-MM-DD.
competenciatexto
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.
pacienteNometexto
até 120 caracteres
Nome do paciente como consta no seu sistema.
pacienteCpftexto
até 14 caracteres
CPF do paciente, com ou sem máscara.
pacienteCarteiratexto
até 30 caracteres
Número da carteirinha do paciente na operadora.
pacienteNascimentotextoData de nascimento do paciente, AAAA-MM-DD.
registroAnstexto
5–6 caracteres
Registro da operadora na ANS, seis dígitos, como consta no cadastro público.
fatorReducaoAcrescimo—st_decimal3-2 do XSD: 1,00 é o valor cheio. Reduz ou acresce o item por regra do contrato.
horaInicialtexto
até 8 caracteres
Hora de início do procedimento (hh:mm), exigida pelo XSD em alguns tipos de item.
horaFinaltexto
até 8 caracteres
Hora de término do procedimento (hh:mm), par de horaInicial.
atendimentoRNtexto
um de: S, N
Atendimento a recém-nascido: S quando o exame é do RN e corre na carteira da mãe.
dataAutorizacaotextoData em que a operadora autorizou, AAAA-MM-DD.
guiaPrincipaltexto
até 20 caracteres
Número da guia à qual esta se vincula, quando a autorização foi dividida em várias guias.
solicitanteDocumentotexto
até 14 caracteres
Documento do contratado solicitante (CNPJ ou CPF), quando o solicitante é pessoa jurídica.
solicitanteContratadoNometexto
até 70 caracteres
Nome do contratado solicitante, como a operadora o cadastrou.
dataSolicitacaotextoData em que a autorização foi solicitada, AAAA-MM-DD.
executanteNometexto
até 70 caracteres
Nome do profissional que executou o procedimento.
executanteConselhotexto
até 10 caracteres
Sigla do conselho do executante (CRM, CRO, CRF…).
executanteNumerotexto
até 15 caracteres
Número do conselho do executante.
executanteUftexto
até 2 caracteres
UF do conselho do executante.
executanteCbotexto
até 10 caracteres
CBO do executante — a ocupação, não a especialidade.
executanteCpftexto
até 11 caracteres
CPF do executante, exigido por algumas operadoras no lugar do conselho.
grauParticipacaotexto
até 2 caracteres
O papel do profissional no procedimento, no código TISS (ex. 00 = cirurgião).
cid10texto
até 10 caracteres
Código CID-10 relacionado ao procedimento.
indicacaoClinicatexto
até 500 caracteres
A justificativa clínica do pedido, em texto livre. É o que a operadora lê para decidir.
viaAcessotexto
até 1 caracteres
Via de acesso do procedimento, pela tabela 35 do TISS.
tecnicaUtilizadatexto
até 1 caracteres
Técnica utilizada (convencional ou videolaparoscopia), pela tabela 36 do TISS.
saudeOcupacionaltexto
até 1 caracteres
Tipo de atendimento em saúde ocupacional, pela tabela 61 do TISS.
caraterAtendimentotexto
até 1 caracteres
Caráter do atendimento: 1 eletivo, 2 urgência/emergência. Campo de cabeçalho da guia.
tipoAtendimentotexto
até 2 caracteres
Tipo de atendimento, pela tabela 50 do TISS. Campo de cabeçalho da guia.
regimeAtendimentotexto
até 2 caracteres
Regime de atendimento, pela tabela 51 do TISS. Campo de cabeçalho da guia.
indicacaoAcidentetexto
até 1 caracteres
Indicação de acidente, pela tabela 36 do TISS: trabalho, trânsito, outros, ou não é acidente.
observacaotexto
até 500 caracteres
Observação registrada, em texto livre.
dadosOrigemobjetoO registro como ele existe no seu sistema, inteiro. Guardado para auditoria e para reprocessar sem precisar pedir de novo.

* 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/itens-faturaveis \
  -H "Authorization: Bearer $MIYDAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "itens": [
      {
        "idNaOrigem": "LIS-2026-1042",
        "descricao": "Hemograma completo",
        "codigoTuss": "40304361",
        "quantidade": 1,
        "valorUnitario": "28.50",
        "dataExecucao": "2026-10-28",
        "pacienteNome": "MARIA DA SILVA SANTOS",
        "pacienteCarteira": "00000000000000",
        "registroAns": "343889"
      }
    ]
  }'

Resposta 201

dataRemessaDeItensFaturaveisO recurso. Os campos estão na tabela abaixo.

O que a remessa fez. Como a gravação é idempotente pelo idNaOrigem, o resumo é o que distingue exame novo de exame que já estava aqui — e é como você confere que um reenvio não cobrou nada duas vezes.

Campos de RemessaDeItensFaturaveis

CampoTipoO que é
itenslista de ItemFaturavelOs exames gravados, como ficaram.
resumoobjetoA contagem da remessa.
criadosinteiroExames que não existiam e nasceram agora.
atualizadosinteiroExames que já estavam gravados e foram atualizados pelo que veio.

Exemplo de retorno

{
  "data": {
    "itens": [
      {
        "id": "itf_01HQ8X",
        "fonte": "LIS_API",
        "idNaOrigem": "LIS-2026-1042",
        "paciente": {
          "nome": "MARIA DA SILVA SANTOS",
          "carteira": "00000000000000",
          "cpf": null
        },
        "operadora": {
          "registroAns": "343889",
          "nome": "Unimed Blumenau",
          "convenioId": "hp_01HQ"
        },
        "procedimento": {
          "tabela": "22",
          "codigo": "40304361",
          "descricao": "Hemograma completo",
          "quantidade": 1
        },
        "valorUnitario": "28.50",
        "valorTotal": "28.50",
        "dataExecucao": "2026-10-28T00:00:00.000Z",
        "competencia": "2026-10",
        "situacao": "A_FATURAR",
        "auditoria": "NAO_AUDITADO",
        "auditadoEm": null,
        "responsavelUserId": null,
        "requisicao": null,
        "autorizacao": null,
        "achados": []
      }
    ],
    "resumo": {
      "criados": 1,
      "atualizados": 0
    }
  }
}

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/itens_faturaveis_registrar

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

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.