Faturamento
/v1/itens-faturaveisO que foi realizado e ainda não foi cobrado
DUAS DIMENSÕES, DOIS FILTROS. situacao é onde o item está no ciclo do dinheiro; auditoria é o que a conferência concluiu. São independentes: situacao=A_FATURAR&auditoria=BLOQUEADO é a fila de quem conserta, e situacao=A_FATURAR&auditoria=APTO é o que pode virar guia agora.
totais vem do recorte inteiro, não da página: é o número que se usa para decidir o que fecha no mês.
- Escopo:
- faturavel:ler
- Resposta:
- 200
Pedido
Parâmetros de query
| Campo | Tipo | O que é |
|---|---|---|
| page | inteiro padrão 1 | A página a trazer, começando em 1. |
| pageSize | inteiro 0–200 · padrão 50 | Quantos registros por página. Máximo 200. |
| busca | texto até 120 caracteres | Texto a procurar. Casa por pedaço do nome e também pelo código, sem diferenciar acento nem caixa. |
| registroAns | texto 5–6 caracteres | Registro da operadora na ANS, seis dígitos, como consta no cadastro público. |
| 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. |
| de | texto | Início do período, AAAA-MM-DD. O intervalo é fechado: o dia informado entra. |
| ate | texto | Fim do período, AAAA-MM-DD. O intervalo é fechado: o dia inteiro entra. |
| situacao | texto um de: A_FATURAR, EM_GUIA, EM_LOTE, ENVIADO, EXCLUIDO | Onde o item está no ciclo do dinheiro: A_FATURAR, EM_GUIA, EM_LOTE, ENVIADO ou EXCLUIDO. |
| incluirFaturados | — um de: true, false, 1, 0, | Se false, esconde os exames que já viraram guia, lote ou foram transmitidos — a fila de quem ainda falta faturar. Ausente, a listagem traz todos. |
| auditoria | texto um de: NAO_AUDITADO, APTO, ALERTA, BLOQUEADO, DESATUALIZADO | O que a conferência concluiu: NAO_AUDITADO, APTO, ALERTA, BLOQUEADO ou DESATUALIZADO. É independente da situação — um item pode estar a faturar e bloqueado ao mesmo tempo. |
| comAchado | — um de: true, false, 1, 0, | Só os itens com alguma pendência de conferência ainda aberta — a fila de quem conserta. |
| familia | texto um de: BENEFICIARIO, AUTORIZACAO, PROCEDIMENTO, EXECUCAO, VALOR, DUPLICIDADE, DOCUMENTO, GUIA, PRAZO, REGRA | Família do problema de faturamento: AUTORIZACAO, VALOR, PROCEDIMENTO, EXECUCAO, DUPLICIDADE, BENEFICIARIO, GUIA, PRAZO, DOCUMENTO ou REGRA. Filtra os exames que têm pendência aberta daquela família. |
| codigoProblema | texto até 10 caracteres | Um problema específico do catálogo, como AUT-001. Filtra os exames com esse problema em aberto. |
| severidade | texto um de: BLOQUEIA, ALERTA, INFO | BLOQUEIA impede faturar; ALERTA deixa seguir com ressalva; INFO é observação. |
| responsavelUserId | texto até 64 caracteres | Quem está com o item na mão, pelo identificador do usuário no Miydas. |
| semResponsavel | — um de: true, false, 1, 0, | Só os exames que ainda não têm dono — a fila de quem vai pegar trabalho. |
| agrupamento | texto um de: requisicao, paciente, operadora, competencia | Como agrupar a resposta: requisicao, paciente, operadora ou competencia. Ausente, vem a lista de exames; presente, vêm os grupos com os totais de cada um. |
| ordenarPor | texto um de: dataExecucao, competencia, pacienteNome, descricao, codigoTuss, quantidade, valorTotal, valorUnitario, auditoria, situacao, createdAt, updatedAt | Por qual coluna ordenar: dataExecucao, competencia, pacienteNome, descricao, codigoTuss, quantidade, valorTotal, valorUnitario, auditoria, situacao, createdAt ou updatedAt. Sem ele, os mais antigos vêm primeiro — a fila é por espera. |
| direcao | texto um de: asc, desc | O sentido da ordenação: asc ou desc. Padrão desc. |
| paciente | texto até 120 caracteres | O paciente: na listagem, filtra pelo nome, por trecho. |
| carteira | texto até 30 caracteres | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| solicitante | texto até 70 caracteres | Quem pediu o procedimento. |
| guia | texto até 20 caracteres | A guia a que este registro pertence. |
| senha | texto até 20 caracteres | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| codigoTuss | texto até 10 caracteres | Código do procedimento na TUSS, a terminologia da ANS. |
| 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. |
| fonte | texto um de: LIS_API, REQUISICAO, PLANILHA, CONECTOR, MANUAL, ARQUIVO_TISS | De onde o exame veio: LIS_API, REQUISICAO, PLANILHA, CONECTOR ou MANUAL. |
* 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 GET https://api.miydas.com.br/v1/itens-faturaveis \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de ItemFaturavel | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde esta página está no total. Vem fora de data. |
Um procedimento realizado que ainda precisa ser cobrado. É a unidade do pré-faturamento: a conferência aponta nele, a guia o agrupa e a glosa, lá na frente, bate nele.
Campos de ItemFaturavel
| 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. |
| fonte | texto um de: LIS_API, REQUISICAO, PLANILHA | De onde o exame entrou: mandado pelo LIS, capturado numa requisição aqui, ou importado de planilha. |
| idNaOrigem | texto | O id que o exame tem NA ORIGEM. É a identidade do fato: reenviar o mesmo id atualiza a linha, nunca cria uma segunda cobrança. |
| paciente | objeto | Quem fez o exame, como a origem informou. |
| nome | texto | Nome do paciente como a origem o informou. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| cpf | texto | CPF, 11 dígitos. Aceito com ou sem máscara. |
| operadora | objeto | Para quem vai a cobrança. Tudo nulo = exame particular ou ainda sem destino. |
| registroAns | texto | Registro da operadora na ANS, seis dígitos, como consta no cadastro público. |
| nome | texto | Razão social da operadora como a ANS a publica. Informativo — a chave é o registro. |
| convenioId | texto | O convênio cadastrado que casa com o registro ANS, quando existe. |
| procedimento | objeto | O que foi feito. |
| tabela | texto | Qual tabela o código usa (22 = TUSS procedimentos, 00 = tabela própria da operadora). Padrão 22. |
| codigo | texto | Código do procedimento na tabela declarada. |
| descricao | texto | Descrição do procedimento, como a fonte a informou. |
| quantidade | inteiro | 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. |
| valorUnitario | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| valorTotal | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| dataExecucao | texto | Quando o exame foi feito. Nulo = a origem ainda não confirmou execução — o que é achado da conferência, não motivo para esconder o item. |
| competencia | texto | YYYY-MM (UTC) da data de NEGÓCIO: crédito na retenção, protocolo na glosa. Nunca da emissão. |
| situacao | texto um de: A_FATURAR, EM_GUIA, EM_LOTE, ENVIADO, EXCLUIDO | Onde o item está no ciclo do dinheiro. |
| auditoria | texto um de: NAO_AUDITADO, APTO, ALERTA, BLOQUEADO, DESATUALIZADO | O que a conferência concluiu. É INDEPENDENTE da situação: um item pode estar A_FATURAR e BLOQUEADO ao mesmo tempo — essa é a fila de trabalho. |
| auditadoEm | texto | Quando a última conferência válida rodou. Nulo = nunca foi conferido. |
| responsavelUserId | texto | Quem está com este item na mão. |
| requisicao | objeto | A requisição que capturou o exame, quando ele nasceu aqui dentro. |
| 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. |
| numero | texto | O número legível da requisição que capturou o exame, do prestador para o prestador. |
| autorizacao | objeto | A guia que autorizou ESTE exame. Nula = não há autorização vinculada — o que não quer dizer que não seja exigida. |
| guiaId | texto | A guia a que este registro se refere, pelo identificador do Miydas. |
| numeroGuiaPrestador | texto | 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. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| situacao | texto | Em que pé está a guia que autoriza este exame. |
| quantidadeAutorizada | texto | Quanto a operadora liberou deste procedimento. Comparar com a quantidade executada é o que revela cobrança a descoberto. |
| statusItem | texto | O que a operadora decidiu sobre ESTE procedimento dentro da guia. |
| achados | lista de objetos | O que a conferência encontrou de aberto neste item. Resolver um não encerra os outros. |
| 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. |
| codigo | texto | Código do catálogo interno: AUT-001, VAL-002. |
| familia | texto | A que grupo o problema pertence: autorização, valor, procedimento, execução, documentação. |
| severidade | texto um de: BLOQUEIA, ALERTA, INFO | BLOQUEIA impede faturar; ALERTA deixa seguir com ressalva; INFO é observação. |
| status | texto um de: ABERTO, EM_ANALISE, AGUARDANDO, RESOLVIDO, DISPENSADO | Em que ponto o processamento está. |
| mensagem | texto | O problema em uma frase, como o faturista o lê. |
Exemplo de retorno
{
"data": [
{
"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": []
}
],
"paginacao": {
"total": 1,
"limite": 20,
"deslocamento": 0,
"temMais": false
}
}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_listarA 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.