Faturamento
/v1/itens-faturaveisManda 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)
| Campo | Tipo | O 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. |
| codigoTuss | texto até 10 caracteres | Código do procedimento na TUSS, a terminologia da ANS. |
| codigoTabela | texto 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). |
| quantidade | nú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. |
| tipoItem | texto 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. |
| unidadeMedida | texto 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. |
| itemVinculado | texto 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. |
| codigoDespesa | texto até 10 caracteres | O tipo da despesa para a operadora (dm_outrasDespesas). Quando ausente, é deduzido de tipoItem. |
| registroAnvisa | texto até 15 caracteres | Registro ANVISA do material ou medicamento, quando a operadora o exige. |
| refFabricante | texto até 60 caracteres | Referência do fabricante do material, quando a operadora a exige. |
| solicitanteNome | texto até 70 caracteres | Nome do médico solicitante. Em branco, a emissão usa o solicitante padrão cadastrado para o convênio. |
| solicitanteConselho | texto até 10 caracteres | O conselho do solicitante (06 = CRM), como em dm_conselhoProfissional. |
| solicitanteNumero | texto até 15 caracteres | O número do solicitante no conselho. |
| solicitanteUf | texto até 2 caracteres | A UF do conselho do solicitante — sigla ou código IBGE; a emissão converte. |
| solicitanteCbo | texto até 10 caracteres | O CBO do solicitante. |
| senhaInformada | texto 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. |
| guiaOperadoraInformada | texto até 20 caracteres | O número da guia na operadora, quando você já o tem. |
| validadeSenhaInformada | texto | Até quando a senha informada vale, AAAA-MM-DD. |
| guiaPrestadorInformada | texto 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. |
| dataExecucao | texto | Data em que o procedimento foi executado, AAAA-MM-DD. |
| 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. |
| pacienteNome | texto até 120 caracteres | Nome do paciente como consta no seu sistema. |
| pacienteCpf | texto até 14 caracteres | CPF do paciente, com ou sem máscara. |
| pacienteCarteira | texto até 30 caracteres | Número da carteirinha do paciente na operadora. |
| pacienteNascimento | texto | Data de nascimento do paciente, AAAA-MM-DD. |
| registroAns | texto 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. |
| horaInicial | texto até 8 caracteres | Hora de início do procedimento (hh:mm), exigida pelo XSD em alguns tipos de item. |
| horaFinal | texto até 8 caracteres | Hora de término do procedimento (hh:mm), par de horaInicial. |
| atendimentoRN | texto um de: S, N | Atendimento a recém-nascido: S quando o exame é do RN e corre na carteira da mãe. |
| dataAutorizacao | texto | Data em que a operadora autorizou, AAAA-MM-DD. |
| guiaPrincipal | texto até 20 caracteres | Número da guia à qual esta se vincula, quando a autorização foi dividida em várias guias. |
| solicitanteDocumento | texto até 14 caracteres | Documento do contratado solicitante (CNPJ ou CPF), quando o solicitante é pessoa jurídica. |
| solicitanteContratadoNome | texto até 70 caracteres | Nome do contratado solicitante, como a operadora o cadastrou. |
| dataSolicitacao | texto | Data em que a autorização foi solicitada, AAAA-MM-DD. |
| executanteNome | texto até 70 caracteres | Nome do profissional que executou o procedimento. |
| executanteConselho | texto até 10 caracteres | Sigla do conselho do executante (CRM, CRO, CRF…). |
| executanteNumero | texto até 15 caracteres | Número do conselho do executante. |
| executanteUf | texto até 2 caracteres | UF do conselho do executante. |
| executanteCbo | texto até 10 caracteres | CBO do executante — a ocupação, não a especialidade. |
| executanteCpf | texto até 11 caracteres | CPF do executante, exigido por algumas operadoras no lugar do conselho. |
| grauParticipacao | texto até 2 caracteres | O papel do profissional no procedimento, no código TISS (ex. 00 = cirurgião). |
| cid10 | texto até 10 caracteres | Código CID-10 relacionado ao procedimento. |
| indicacaoClinica | texto até 500 caracteres | A justificativa clínica do pedido, em texto livre. É o que a operadora lê para decidir. |
| viaAcesso | texto até 1 caracteres | Via de acesso do procedimento, pela tabela 35 do TISS. |
| tecnicaUtilizada | texto até 1 caracteres | Técnica utilizada (convencional ou videolaparoscopia), pela tabela 36 do TISS. |
| saudeOcupacional | texto até 1 caracteres | Tipo de atendimento em saúde ocupacional, pela tabela 61 do TISS. |
| caraterAtendimento | texto até 1 caracteres | Caráter do atendimento: 1 eletivo, 2 urgência/emergência. Campo de cabeçalho da guia. |
| tipoAtendimento | texto até 2 caracteres | Tipo de atendimento, pela tabela 50 do TISS. Campo de cabeçalho da guia. |
| regimeAtendimento | texto até 2 caracteres | Regime de atendimento, pela tabela 51 do TISS. Campo de cabeçalho da guia. |
| indicacaoAcidente | texto até 1 caracteres | Indicação de acidente, pela tabela 36 do TISS: trabalho, trânsito, outros, ou não é acidente. |
| observacao | texto até 500 caracteres | Observação registrada, em texto livre. |
| dadosOrigem | objeto | O 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
| data | RemessaDeItensFaturaveis | O 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
| Campo | Tipo | O que é |
|---|---|---|
| itens | lista de ItemFaturavel | Os exames gravados, como ficaram. |
| resumo | objeto | A contagem da remessa. |
| criados | inteiro | Exames que não existiam e nasceram agora. |
| atualizados | inteiro | Exames 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_registrarO 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.