Objetos da resposta
O que cada campo é, e não só de que tipo ele é. Todo campo tem definição — é verificado por teste na API, e campo sem definição não entra no contrato.
Dinheiro vem como string decimal com duas casas, nunca como número. Ausência é null, nunca "0.00": zero é um valor que a operadora declarou, e tratá-los igual é como se perde glosa de vista.
Paginacao
Onde esta página está dentro do total. Vem ao lado de data, fora dele.
| Campo | Tipo | O que é |
|---|---|---|
| total | inteiro | Quantos registros existem no filtro pedido — não quantos vieram nesta página. |
| limite | inteiro | O teto aplicado nesta resposta, seja o que você pediu ou o padrão da rota. |
| deslocamento | inteiro | Quantos registros foram pulados para chegar nesta página. |
| temMais | booleano | Há página seguinte. Equivale a deslocamento + itens < total, já calculado. |
LeituraDeArquivo
O resultado de ler um arquivo. Nada foi gravado: o acervo e GET /v1/demonstrativos.
Devolvido por:POST /v1/demonstrativos/leituras
| Campo | Tipo | O que é |
|---|---|---|
| arquivo | objeto | O arquivo de onde o dado veio. |
| nome | texto | Nome do arquivo de onde o dado veio, como a operadora o nomeou. |
| formato | texto um de: XML, ZIP | O involucro. Num ZIP, cada XML interno foi lido. |
| bytes | inteiro | Tamanho do arquivo recebido. |
| demonstrativos | lista de objetos | Um por documento encontrado no arquivo. Um ZIP com varios XML devolve varios; um XML, normalmente um. |
| tipo | texto um de: ANALISE, PAGAMENTO | ANALISE: o julgamento da conta — o que a operadora reconheceu e o que glosou. PAGAMENTO: o caixa — o que ela creditou. Duas respostas distintas, quase sempre em meses distintos. |
| numeroDemonstrativo | texto | O número que a operadora deu ao demonstrativo. NÃO identifica o documento: ele se repete entre operadoras e entre competências. A identidade de um retorno é o protocolo mais a data. |
| 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. |
| competencia | texto | YYYY-MM, como o documento a declara. |
| operadora | texto | O nome da operadora como o documento o escreve — nao e o catalogo ANS. |
| emitidoEm | texto | Data que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download. |
| creditoEm | texto | Data do credito. So em documento de pagamento. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| valorPago | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| guias | lista de objetos | As guias do documento. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| atendimentoEm | texto | Data de realizacao do atendimento, como o documento a declara. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosas | lista de objetos | Glosas de nivel GUIA — as de item estao em itens[].glosas. |
| codigo | texto | Codigo da glosa na tabela 38 do TISS, como o documento o trouxe. |
| descricao | texto | O significado do codigo. Preenchido da tabela 38 quando o documento manda so o codigo. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| itens | lista de objetos | Procedimentos e despesas da guia, como o documento os lista. |
| tipo | texto um de: PROCEDIMENTO, DESPESA | PROCEDIMENTO: a tabela de procedimentos. DESPESA: material, medicamento, taxa, diaria, OPME. |
| sequencial | texto | A ordem do registro dentro do documento, como a operadora a numerou. |
| codigoProcedimento | texto | Código do procedimento na tabela declarada em codigoTabela. |
| codigoDespesa | texto | So em item de despesa. |
| descricao | texto | Descrição do item, como a fonte a informou. |
| quantidade | texto | 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. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosas | lista de objetos | As glosas deste item — o nivel em que o recurso e montado, porque no TISS ele e item a item. |
| codigo | texto | Codigo da glosa na tabela 38 do TISS, como o documento o trouxe. |
| descricao | texto | O significado do codigo. Preenchido da tabela 38 quando o documento manda so o codigo. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liquidacao | objeto | O acerto financeiro do documento. AUSENTE em documento de analise: analise nao fecha pagamento, e um bloco vazio ali diria "sem imposto" onde o certo e "este documento nao trata disso". |
| totalDebitos | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| totalCreditos | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| lancamentos | lista de objetos | Linha a linha do que foi descontado e somado ao credito. |
| natureza | texto um de: DEBITO, CREDITO | Nulo quando o documento manda um indicador fora de 1 (debito) e 2 (credito): chamar credito o que e debito inverteria o sinal do dinheiro. |
| tipo | texto | O codigo do tipo de debito ou credito, como a operadora o declara. |
| descricao | texto | O texto do lancamento (ex. "IRPJ Prod Medica"). |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| avisos | lista de texto | Vazio quando a leitura saiu limpa. Arquivo que nao produziu demonstrativo nenhum devolve demonstrativos: [] COM aviso — nunca 204, que o integrador leria como sucesso silencioso. |
Processamento
Andamento com a operadora. CONCLUIDO = a operadora respondeu; o desfecho está no recurso.
| Campo | Tipo | O que é |
|---|---|---|
| status | texto um de: PENDENTE, PROCESSANDO, CONCLUIDO, FALHOU | Em que ponto o processamento está. |
| iniciadoEm | texto | Quando o processamento começou, em ISO 8601 com fuso. |
| concluidoEm | texto | Quando o processamento terminou, em ISO 8601 com fuso. null = ainda corre. |
| erro | objeto | O que falhou. null quando não falhou nada. |
| error | texto | Código estável do erro, feito para lógica. É o contrato — a mensagem não é. |
| message | texto | O erro em português, para humano. Pode mudar sem aviso. |
| podeRepetir | booleano | Repetir o mesmo pedido pode dar outro resultado. false = o erro é definitivo, corrija antes. |
Lote
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.
Devolvido por:POST /v1/lotesGET /v1/lotesGET /v1/lotes/{id}POST /v1/lotes/{id}/enviosPOST /v1/lotes/{id}/resolucoes
| 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. |
Retencao
Imposto retido na fonte pela operadora, declarado no demonstrativo de pagamento. Recurso próprio porque quem pergunta é a contabilidade, e a pergunta dela é por competência.
Devolvido por:GET /v1/retencoes/demonstrativosGET /v1/retencoes/{demonstrativoId}
| Campo | Tipo | O que é |
|---|---|---|
| demonstrativoId | texto | O demonstrativo a que este registro pertence, pelo identificador do Miydas. |
| 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. |
| numeroDemonstrativo | texto | O número que a operadora deu ao demonstrativo. NÃO identifica o documento: ele se repete entre operadoras e entre competências. A identidade de um retorno é o protocolo mais a data. |
| competencia | texto | YYYY-MM (UTC) da data de NEGÓCIO: crédito na retenção, protocolo na glosa. Nunca da emissão. |
| fonteCompetencia | texto um de: CREDITO, AUSENTE | De onde saiu a competência: a data do CRÉDITO (a primeira, quando há mais de uma), ou AUSENTE quando a operadora não declarou crédito. Era a emissão até 24/10/2026, e estava errado — o portal renderiza o documento no download, e o mês da emissão difere do mês do crédito em 89,5% dos documentos. |
| emitidoEm | texto | Data que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download. |
| creditoEm | texto | Data do primeiro crédito do demonstrativo. Vários créditos é caso real. |
| total | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| decomposicao | objeto | Nulo quando a operadora mandou só o total (405 de 2.915 medidos). |
| iss | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| pis | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| ir | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| inss | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| cofins | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| outros | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| naoMapeados | objeto | Tributo que a operadora declarou e que não está nos seis conhecidos, com a própria chave do documento. Ele soma na conferência — tributo novo aparece aqui em vez de virar divergência falsa. |
| conferencia | objeto | Confere o total declarado contra a soma dos quatro tributos. Nulo quando falta um dos lados. |
| somaDosTributos | texto | Decimal em string, duas casas — dinheiro não é number. |
| confere | booleano | false = o total declarado não bate com a soma dos tributos. Não é erro nosso: é o documento que não fecha, e vale conferir antes de lançar. |
| valorLiquidoDoDemonstrativo | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
RetencaoConsolidada
O consolidado fiscal do recorte pedido, com o que NÃO fecha declarado em semDecomposicao e divergencias.
Devolvido por:GET /v1/retencoes
| Campo | Tipo | O que é |
|---|---|---|
| competencia | texto | O recorte pedido. Nulo = todas as competências. |
| recorte | objeto | O filtro que produziu estes números, devolvido junto. Total sem recorte ao lado é número solto: é por aqui que você confere que somou o que queria. |
| 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. |
| demonstrativos | inteiro | Quantos demonstrativos entraram neste consolidado. |
| total | texto | Decimal em string, duas casas — dinheiro não é number. |
| porTributo | objeto | Tributos retidos na fonte. Campo nulo = a operadora não abriu aquele tributo. Medido em produção: ISS em 2.341 demonstrativos, PIS 2.038, IR 2.032, Outros 1.772, INSS 309, COFINS 6. naoMapeados carrega qualquer tributo novo com a própria chave do documento — ele soma na conferência, para que um tributo desconhecido apareça em vez de virar divergência falsa. |
| iss | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| pis | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| ir | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| inss | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| cofins | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| outros | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| naoMapeados | objeto | Tributo que a operadora declarou e que não está nos seis conhecidos, com a própria chave do documento. Ele soma na conferência — tributo novo aparece aqui em vez de virar divergência falsa. |
| semDecomposicao | objeto | Quanto do total chegou sem abertura por tributo. Não lance isto como ISS. |
| demonstrativos | inteiro | Quantos vieram só com o total, sem abertura por tributo. |
| total | texto | Decimal em string, duas casas — dinheiro não é number. |
| divergencias | inteiro | Demonstrativos em que o total declarado não bate com a soma dos tributos. |
| porOperadora | lista de objetos | Os mesmos números, abertos por operadora. |
| 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, para exibição. |
| demonstrativos | inteiro | Quantos demonstrativos desta operadora entram no total. |
| total | texto | Decimal em string, duas casas — dinheiro não é number. |
| porCompetencia | lista de objetos | Os mesmos números, abertos por mês de competência. |
| competencia | texto | 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. |
| demonstrativos | inteiro | Quantos demonstrativos deste mês entram no total. |
| total | texto | Decimal em string, duas casas — dinheiro não é number. |
Glosa
Uma glosa, no nível em que a operadora a declarou, com o significado oficial do motivo.
Devolvido por:GET /v1/glosasGET /v1/glosas/{id}
| 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. |
| nivel | texto um de: PROTOCOLO, GUIA, ITEM | Em que nível a glosa pende: ITEM, GUIA ou PROTOCOLO. Medido na base: 56.709 em item, 262 em guia, nenhuma em protocolo — o recurso TISS é item a item, e é no item que a glosa quase sempre mora. |
| motivo | objeto | O motivo como a operadora o deu. significado vem da Tabela 38 da ANS quando o código existe lá. |
| codigo | texto | O código do motivo, como a operadora o emitiu. |
| significado | texto | Termo oficial da Tabela 38. Nulo quando o código não existe na tabela. |
| tipo | texto um de: TABELA_ANS, CODIGO_OPERADORA, CATEGORIA, TEXTO_LIVRE, NENHUM | Derivado do que está presente, não do campo tipoMotivo do banco — que está nulo em 93 % das linhas. |
| tipoDeclarado | texto | O que o parser gravou em tipoMotivo. Para auditar o parser, não para decidir. |
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| categoria | texto | O agrupamento que a operadora deu ao motivo, quando ela agrupa. Mais grosso que o código e, em operadora que não usa a Tabela 38, às vezes a única pista. |
| notaAuditor | texto | Argumento do auditor da operadora. Insumo direto de recurso. |
| descricao | texto | O texto livre que a operadora escreveu sobre esta glosa, além do motivo codificado. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| 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 (UTC) da data de NEGÓCIO: crédito na retenção, protocolo na glosa. Nunca da emissão. |
| 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. |
| guia | objeto | A guia a que este registro pertence. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| item | objeto | O item glosado. Nulo em glosa de nível GUIA ou PROTOCOLO — e é por ele que se monta o recurso, que no TISS é item a item. |
| codigoTabela | texto | Qual tabela o código usa (22 = TUSS procedimentos, 18/19/20 = materiais, taxas e medicamentos, 00 = tabela própria da operadora). |
| codigoProcedimento | texto | Código do procedimento na tabela declarada em codigoTabela. |
| descricao | texto | A descrição do procedimento glosado, como o documento a trouxe. |
| evidencia | objeto | O documento de onde a glosa saiu, com até onde ele veio. |
| demonstrativoId | texto | O demonstrativo a que este registro pertence, pelo identificador do Miydas. |
| emitidoEm | texto | Quando NÓS recebemos o documento — o portal o renderiza no download. |
| protocoloEm | texto | A data de negócio do protocolo, de onde sai a competência. |
| fonteOrdem | inteiro | Qual arquivo do demonstrativo composto trouxe esta glosa. |
| completude | texto | FULL | ACCEPTED_ONLY | GLOSA_ONLY — o que o conjunto de arquivos permite afirmar. |
| profundidade | texto | Até onde o documento desce: PROTOCOLO, GUIA ou ITEM. Documento que para na guia não permite recurso item a item. |
| registradaEm | texto | Quando o Miydas registrou o fato, em ISO 8601 com fuso. Não é quando ele aconteceu na operadora. |
ResumoDeGlosas
O retrato agregado do recorte: quanto, em que nível, e quanto veio sem motivo.
Devolvido por:GET /v1/glosas/resumo
| Campo | Tipo | O que é |
|---|---|---|
| recorte | objeto | O filtro que produziu estes números, devolvido junto. Total sem recorte ao lado é número solto: é por aqui que você confere que somou o que queria. |
| 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. |
| competencia | texto | 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. |
| glosas | inteiro | Quantas glosas no recorte. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| comSignificadoOficial | objeto | Quantas têm código que existe na Tabela 38. proporcao é 0–1, não percentual. |
| glosas | inteiro | Quantas trazem código que existe na Tabela 38 da ANS. |
| proporcao | número | A fração delas sobre o total, de 0 a 1. 0.62 é 62% — não é percentual. |
| semCodigo | objeto | A operadora cortou e não disse por quê. Material de recurso. |
| glosas | inteiro | Quantas vieram sem motivo codificado. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| porNivel | lista de objetos | Os mesmos números, abertos pelo nível em que a glosa pende. |
| nivel | texto | O nível em que a glosa pende: ITEM, GUIA ou PROTOCOLO. |
| glosas | inteiro | Quantas glosas pendem deste nível. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| maioresPorValor | lista de objetos | Os motivos que mais custaram, do mais caro para o mais barato. É por onde se começa a recorrer. |
| codigo | texto | O código do motivo. Nulo agrupa tudo que veio sem código. |
| significado | texto | O termo da Tabela 38, quando o código existe nela. |
| glosas | inteiro | Quantas glosas têm este motivo. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
Demonstrativo
O retorno da operadora como acervo: um documento de análise de conta ou de pagamento.
Devolvido por:GET /v1/demonstrativos
| 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. |
| tipo | texto um de: ANALISE, PAGAMENTO | ANALISE: o julgamento da conta — o que a operadora reconheceu e o que glosou. PAGAMENTO: o caixa — o que ela creditou. Duas respostas distintas, quase sempre em meses distintos. |
| 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. |
| numeroDemonstrativo | texto | O número que a operadora deu ao demonstrativo. NÃO identifica o documento: ele se repete entre operadoras e entre competências. A identidade de um retorno é o protocolo mais a data. |
| competencia | texto | YYYY-MM (UTC) da data de NEGÓCIO: data do protocolo na análise, data do crédito no pagamento. Nunca da emissão. |
| creditoEm | texto | Data do crédito. Só em documento de pagamento. |
| emitidoEm | texto | Quando NÓS recebemos o documento — o portal o renderiza no download. |
| completude | texto | FULL | ACCEPTED_ONLY | GLOSA_ONLY — o que o conjunto de arquivos permite afirmar. Num GLOSA_ONLY o cobrado e o liberado NÃO chegaram: não são zero. |
| profundidade | texto | Até onde a fonte desce: A (item + motivo) · B (item) · C (guia) · D (protocolo) · E (overlay) · F (só o fechamento financeiro). |
| versaoTiss | texto | Versão do padrão TISS do documento (ex. 4.01.00). Quem dita a versão é a operadora. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| protocolos | inteiro | Quantos protocolos o documento cobre. A lista deles vem no detalhe. |
| guias | inteiro | Quantas guias o documento cobre. A lista delas vem no detalhe. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
DemonstrativoDetalhado
O documento inteiro: protocolos, guias e glosas — e a liquidação, quando é documento de pagamento.
Devolvido por:GET /v1/demonstrativos/{id}
| 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. |
| tipo | texto um de: ANALISE, PAGAMENTO | ANALISE: o julgamento da conta — o que a operadora reconheceu e o que glosou. PAGAMENTO: o caixa — o que ela creditou. Duas respostas distintas, quase sempre em meses distintos. |
| 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. |
| numeroDemonstrativo | texto | O número que a operadora deu ao demonstrativo. NÃO identifica o documento: ele se repete entre operadoras e entre competências. A identidade de um retorno é o protocolo mais a data. |
| competencia | texto | YYYY-MM (UTC) da data de NEGÓCIO: data do protocolo na análise, data do crédito no pagamento. Nunca da emissão. |
| creditoEm | texto | Data em que o dinheiro caiu — a data de NEGÓCIO do documento de pagamento, e a que define a competência dele. |
| emitidoEm | texto | Data que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download. |
| completude | texto | FULL | ACCEPTED_ONLY | GLOSA_ONLY — o que o conjunto de arquivos permite afirmar. Num GLOSA_ONLY o cobrado e o liberado NÃO chegaram: não são zero. |
| profundidade | texto | Até onde a fonte desce: A (item + motivo) · B (item) · C (guia) · D (protocolo) · E (overlay) · F (só o fechamento financeiro). |
| versaoTiss | texto | Versão do padrão TISS do documento (ex. 4.01.00). Quem dita a versão é a operadora. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| guias | inteiro | Total de guias do documento, inclusive as que a paginação não trouxe. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
| avisos | lista de texto | O que impede ler este documento errado — por exemplo, que um GLOSA_ONLY não declara o cobrado. |
| fontes | lista de objetos | Os documentos que compõem este demonstrativo. Mais de um é normal: operadora que manda o aceito e o glosado em arquivos separados aparece aqui com dois. |
| origem | texto um de: ARQUIVO, MENSAGEM_TISS | ARQUIVO: um arquivo que chegou à caixa de entrada. MENSAGEM_TISS: a resposta estruturada do webservice. A segunda domina — 2.900 contra 440 na análise. |
| papel | texto | ACCEPTED (só o aceito) | GLOSA (só o recusado) | FULL (o documento inteiro). |
| ordem | inteiro | A posição deste registro na sequência, a partir de 1. |
| arquivo | objeto | O arquivo de onde o dado veio. |
| id | texto | O id a passar em /demonstrativos/{id}/arquivos/{arquivoId}. |
| nome | texto | Nome do arquivo de onde o dado veio, como a operadora o nomeou. |
| extensao | texto | O invólucro. formato é o que conseguimos ler dele. |
| formato | texto | Em que formato o dado chegou. |
| tamanhoBytes | inteiro | Tamanho do arquivo em bytes. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
| protocolos | lista de objetos | Os protocolos que este documento cobre. |
| numeroProtocolo | texto | O número do protocolo na operadora. |
| numeroLotePrestador | texto | O número que o prestador deu ao lote no arquivo enviado. |
| dataProtocolo | texto | A data do protocolo na operadora — a data de NEGÓCIO do documento de análise, e a que define a competência. |
| situacao | texto | O estado do protocolo na língua da operadora, sem tradução. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosas | lista de Glosa | Glosas de nível PROTOCOLO. Não são distribuídas pelas guias: o documento não as atribuiu. |
| guias | lista de objetos | As guias do documento. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| situacao | texto | O estado da guia na língua da operadora, sem tradução — cada uma tem o seu vocabulário. |
| atendimentoDe | texto | Primeiro dia do atendimento coberto pela guia. |
| atendimentoAte | texto | Último dia do atendimento coberto pela guia. Igual a atendimentoDe quando foi um dia só. |
| fonteOrdem | inteiro | Qual dos arquivos do demonstrativo composto trouxe esta guia. Cruze com fontes[].ordem. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosas | lista de Glosa | As glosas desta guia dentro deste documento. |
| totalDeGuias | inteiro | Quantas guias o protocolo tem ao todo — inclusive as que o teto de 200 por resposta não trouxe. |
| temMaisGuias | booleano | O protocolo tem mais guias do que o teto de 200 por resposta. |
| liquidacao | lista de objetos | O fechamento financeiro, UMA ENTRADA POR DATA DE CRÉDITO. Só em documento de pagamento; vazio na análise. |
| creditoEm | texto | Data em que o dinheiro caiu — a data de NEGÓCIO do documento de pagamento, e a que define a competência dele. |
| forma | texto | Como o dinheiro foi pago, como a operadora declarou (ex. crédito em conta). |
| banco | texto | Banco do crédito, como o documento o informa. |
| agencia | texto | Agência do crédito, como o documento a informa. |
| conta | texto | Conta do crédito, como o documento a informa. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| debitos | lista de objetos | O que foi descontado do crédito do dia: impostos, taxas, acertos de período anterior. |
| tipo | texto | A natureza do lançamento, como a operadora a nomeia (ex. imposto, taxa, glosa de período anterior). |
| subtipo | texto | O detalhamento do tipo, quando a operadora o abre. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| creditos | lista de objetos | O que foi somado ao crédito do dia, fora as guias. |
| tipo | texto | A natureza do lançamento, como a operadora a nomeia (ex. imposto, taxa, glosa de período anterior). |
| subtipo | texto | O detalhamento do tipo, quando a operadora o abre. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| totalDebitos | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| totalCreditos | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liquido | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
Guia
A guia pelas três camadas que a atravessam: envio, análise e pagamento.
Devolvido por:GET /v1/guiasGET /v1/guias/{id}
| 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. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| numeroProtocolo | texto | O número do protocolo na operadora. |
| 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. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| dataExecucao | texto | Data em que o procedimento foi executado, AAAA-MM-DD. |
| creditoEm | texto | Data em que o dinheiro caiu — a data de NEGÓCIO do documento de pagamento, e a que define a competência dele. |
| camadas | objeto | Quais documentos existem para esta guia. MEDIDO nas tabelas de retorno, não inferido da coluna: o motor grava zero e não nulo, então a coluna não distingue "não mandou" de "mandou zero". |
| envio | booleano | O lote saiu daqui. Falso em 40.746 das 40.760 guias — o portal devolve julgamento, não o arquivo enviado. |
| analise | booleano | Existe documento de análise para esta guia — a operadora já julgou a conta. |
| pagamento | booleano | Existe documento de pagamento — ela já declarou o crédito. Sem esta camada, pago é nulo. |
| completudeAnalise | texto | A completude do documento de análise que chegou. Num GLOSA_ONLY, o cobrado e o liberado não vieram — não são zero. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| cobradoDaOperadora | booleano | Sem envio, o cobrado é a palavra da operadora — a única testemunha que sobrou. |
| processado | texto | O que a operadora reconheceu como devido. |
| liberado | texto | O que ela aceitou pagar — julgamento da análise. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| pago | texto | O que o demonstrativo de PAGAMENTO declara. Nulo enquanto essa camada não existir. |
| diferenca | texto | cobrado − liberado. Nulo quando um dos lados falta: indeterminada não é zero. |
| divergenciaPagamento | texto | pago − liberado. Positivo = pagou mais. |
| situacaoPagamento | objeto | DERIVADA de pago × liberado. A coluna statusPagamento está nula em 39.131 de 39.131 linhas. |
| codigo | texto um de: PAGO_INTEGRAL, PAGO_PARCIAL, PAGO_A_MAIOR, NAO_PAGO | O confronto entre o que foi pago e o que foi liberado. PAGO_A_MAIOR existe e costuma ser reemissão contada duas vezes — confira pagamentos. |
| descricao | texto | O mesmo veredito em português, para exibir. |
| pagamentos | inteiro | Quantas datas de crédito somaram em pago. >1 merece conferência. |
| temGlosaDeclarada | booleano | A operadora declarou glosa nesta guia. Diferente de ter pago a menor sem declarar — isso é glosa silenciosa. |
| motivos | lista de objetos | Os motivos de glosa que pesam sobre esta guia, somando os do nível da guia e os dos itens dela. |
| codigo | texto | O código do motivo, como a operadora o emitiu. Na glosa, é o código da Tabela 38 da ANS quando ela usa o oficial. |
| descricao | texto | O motivo em texto, na língua da operadora — não traduzido. |
| origem | texto | De que nível o motivo veio: GUIA ou ITEM. |
| itens | objeto | Quantas linhas cada lado tem. Números diferentes já indicam divergência antes de abrir os itens. |
| envio | inteiro | Quantos itens saíram daqui. Nulo quando não há camada de envio. |
| retorno | inteiro | Quantos itens a operadora devolveu. |
ItemDoDemonstrativo
O item como a operadora o declarou — o nível mais fundo do retorno, e onde a glosa mora em 56.709 das 56.971 glosas medidas. O motivo vai junto, e não num segundo pedido.
Devolvido por:GET /v1/demonstrativos/{id}/itens
| 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. |
| guia | objeto | A guia a que este registro pertence. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| 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. |
| sequencial | inteiro | A ordem do registro dentro do documento, como a operadora a numerou. |
| tipo | texto | PROCEDIMENTO | DESPESA (material, medicamento, taxa). |
| procedimento | objeto | O procedimento a que a linha se refere. |
| 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 | O que a operadora escreveu. |
| termoOficial | texto | O termo da TUSS. Divergir do anterior é informação, não erro. |
| despesa | objeto | Só em item do tipo DESPESA: procedimento não tem código de despesa nem registro ANVISA. |
| codigo | texto | Código do material, medicamento ou taxa na tabela declarada. |
| registroANVISA | texto | Registro do produto na ANVISA, quando a linha é material ou medicamento. |
| grauParticipacao | texto | O papel do profissional no procedimento, no código TISS (ex. 00 = cirurgião). |
| unidadeMedida | texto | 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. |
| realizadoEm | texto | Quando o procedimento foi realizado. |
| quantidade | texto | 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. |
| valores | objeto | A glosa é a SOMA das glosas do item — não há coluna de glosa no item, a recusa mora na tabela de glosas. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| total | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| fonteOrdem | inteiro | Qual dos arquivos do demonstrativo composto trouxe esta linha. Cruze com fontes[].ordem do detalhe. |
| motivos | lista de objetos | Por que esta linha foi cortada, na palavra da operadora e no termo oficial. Vem junto, e não num segundo pedido — é o insumo do recurso. |
| codigo | texto | O código do motivo, como a operadora o emitiu. Na glosa, é o código da Tabela 38 da ANS quando ela usa o oficial. |
| significado | texto | O termo oficial da Tabela 38 da ANS, quando o código existe nela. |
| tipo | texto um de: TABELA_ANS, CODIGO_OPERADORA, CATEGORIA, TEXTO_LIVRE, NENHUM | Que espécie de motivo é este, derivado do que veio preenchido. NENHUM = cortaram sem dizer por quê. |
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| categoria | texto | O agrupamento que a operadora deu ao motivo, quando ela agrupa. |
| notaAuditor | texto | O argumento do auditor. Insumo direto do recurso. |
| descricao | texto | O motivo em texto, na língua da operadora — não traduzido. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
ItemConciliado
O item pelas três camadas, com o veredito do motor: a chave que casou, a diferença, o split e a decisão do faturista. É o cruzamento que o Revenue faz, não o que a operadora disse.
Devolvido por:GET /v1/guias/{id}/itens
| 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. |
| chave | texto | A chave que casou os dois lados: operadora + guia + código. |
| tipoDeMatch | texto | Como os dois lados casaram: pelo código do procedimento, pela sequência na guia, ou por aproximação. Casamento fraco merece conferência antes de virar decisão. |
| envio | objeto | Nulo é o caso dominante: o portal devolve julgamento, não o arquivo que o prestador mandou. |
| sequencial | inteiro | A ordem do registro dentro do documento, como a operadora a numerou. |
| tipo | texto | Natureza da linha enviada: PROCEDIMENTO ou DESPESA. |
| tabela | texto | Qual tabela o código usa (22 = TUSS procedimentos, 00 = tabela própria da operadora). Padrão 22. |
| codigo | texto | O código que VOCÊ cobrou. |
| descricao | texto | A descrição que você enviou. Compare com a da análise: operadora que renomeia costuma ter traduzido para o código dela. |
| quantidade | texto | 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. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| executadoEm | texto | Quando a execução ocorreu, em ISO 8601 com fuso. |
| analise | objeto | Nulo quando o item saiu daqui e a operadora não o mencionou. |
| sequencial | inteiro | A ordem do registro dentro do documento, como a operadora a numerou. |
| tabela | texto | Qual tabela o código usa (22 = TUSS procedimentos, 00 = tabela própria da operadora). Padrão 22. |
| codigo | texto | O código que a OPERADORA devolveu. Diferente do enviado quando ela traduziu para a tabela dela. |
| descricao | texto | A descrição que a operadora devolveu. |
| quantidade | texto | 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. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| realizadoEm | texto | Quando o procedimento foi realizado. |
| pagamento | objeto | Vem da GUIA de pagamento: o demonstrativo de pagamento desce até a guia em 2.929 de 2.929 documentos, nunca até o item. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| diferenca | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| split | objeto | A operadora quebrou o item em dois — liberou parte da quantidade. |
| detectado | booleano | A operadora liberou parte da quantidade e cortou o resto, quebrando a linha em duas. |
| detalhe | texto | Detalhe em texto livre, para humano. Não é contrato. |
| decisao | objeto | Do faturista, não da operadora: ACEITA | EM_RECURSO. A glosa mora no item, e o recurso TISS é item a item. |
| valor | texto | Valor em reais, decimal em string com duas casas — dinheiro não trafega como number. |
| em | texto | Quando este fato foi registrado, em ISO 8601 com fuso. |
| nota | texto | A nota escrita por quem registrou o fato — fica no histórico do recurso. |
TermoTuss
Um termo da terminologia TUSS. Por padrão só o vigente: código revogado numa guia é recusa certa.
Devolvido por:GET /v1/referencias/tuss
| Campo | Tipo | O que é |
|---|---|---|
| codigo | texto | O código do termo na tabela. Único dentro da tabela, não entre tabelas. |
| termo | texto | O termo como a tabela oficial o nomeia. |
| descricaoDetalhada | texto | A descrição longa do termo, quando a tabela oficial traz uma. |
| tabela | inteiro | 22 = procedimentos · 38 = motivos de glosa · 19/20 = materiais e medicamentos. |
| tipoDaTabela | texto | A tabela TUSS de onde o termo vem, pelo número oficial da ANS. |
| vigenteDe | texto | Primeiro dia em que o termo vale na tabela oficial. |
| vigenteAte | texto | Nulo = vigente. Preenchido no passado = revogado. |
| apresentacao | texto | Como o produto se apresenta (ex. frasco 10 ml). Só em material e medicamento. |
| fabricante | texto | Fabricante do produto. Só em material e medicamento. |
| registroANVISA | texto | Registro do produto na ANVISA, quando a linha é material ou medicamento. |
| porte | texto | O porte do procedimento na tabela, quando ela o classifica — entra no cálculo de honorário. |
| capitulo | texto | O capítulo da tabela a que o termo pertence. |
| grupo | texto | O grupo dentro do capítulo. |
OperadoraAns
Operadora registrada na ANS. É aqui que se acha o registroANS a partir do CNPJ ou do nome.
Devolvido por:GET /v1/referencias/operadoras-ans
| Campo | Tipo | O que é |
|---|---|---|
| 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. |
| cnpj | texto | CNPJ, 14 dígitos. Aceito com ou sem máscara; devolvido sem. |
| razaoSocial | texto | Razão social, como consta no cadastro público. |
| nomeFantasia | texto | Nome fantasia, quando o cadastro informa. |
| modalidade | texto | A natureza da operadora na classificação da ANS (ex. cooperativa médica, medicina de grupo, seguradora). |
| cidade | texto | Município, por extenso. |
| uf | texto | Sigla da unidade federativa, duas letras (ex. SC). |
| registradaEm | texto | Quando o Miydas registrou o fato, em ISO 8601 com fuso. Não é quando ele aconteceu na operadora. |
EstabelecimentoCnes
Estabelecimento de saúde no CNES — o código que a guia TISS exige do prestador.
Devolvido por:GET /v1/referencias/cnes
| Campo | Tipo | O que é |
|---|---|---|
| codigoCNES | texto | Código do estabelecimento no CNES, sete dígitos. |
| cnpj | texto | CNPJ, 14 dígitos. Aceito com ou sem máscara; devolvido sem. |
| razaoSocial | texto | Razão social, como consta no cadastro público. |
| nomeFantasia | texto | Nome fantasia, quando o cadastro informa. |
| tipoUnidade | objeto | A espécie de estabelecimento na classificação do CNES. |
| codigo | inteiro | O código do tipo no CNES (7 = hospital geral, 22 = clínica especializada, 39 = SADT). |
| descricao | texto | O tipo por extenso. |
| cidade | texto | Município, por extenso. |
| codigoMunicipioIBGE | texto | Código do município no IBGE, sete dígitos. |
| uf | texto | Sigla da unidade federativa, duas letras (ex. SC). |
DocumentoRecebido
Tudo que chegou, por portal ou por upload — inclusive o que NÃO virou dado. Medido: de 14.838 arquivos, 1.413 pararam (946 sem identificação da operadora, 455 com erro, 12 rejeitados).
Devolvido por:GET /v1/documentos-recebidosGET /v1/documentos-recebidos/{id}
| 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. |
| nomeArquivo | texto | O nome do arquivo como a fonte o nomeou. |
| extensao | texto | O invólucro. formato é o que conseguimos ler dele. |
| formato | texto | Em que formato o dado chegou. |
| tipoDocumento | texto | O que o identificador reconheceu no arquivo (ex. DEMONSTRATIVO_ANALISE). Nulo quando ele não reconheceu — e esses 946 arquivos são o motivo de esta rota existir. |
| tamanhoBytes | inteiro | Tamanho do arquivo em bytes. |
| situacao | objeto | Quatro valores públicos sobre quinze estados internos: a esteira é nossa, a pergunta é sua. |
| codigo | texto um de: EM_ANDAMENTO, PROCESSADO, PENDENTE, FALHOU | PROCESSADO virou dado consultável. PENDENTE parou esperando gente. FALHOU quebrou. Os dois últimos somam parados no resumo. |
| descricao | texto | O mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar. |
| estadoInterno | texto | Não é contrato — pode mudar. É o que o suporte pede quando algo trava. |
| 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. |
| competencia | texto | 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. |
| recebidoEm | texto | Quando o arquivo chegou ao Miydas, em ISO 8601 com fuso. |
| processadoEm | texto | Quando o arquivo virou dado consultável, em ISO 8601 com fuso. null = ainda não virou. |
| totais | objeto | O que o leitor extraiu. Nulo em documento que não virou dado. |
| guias | inteiro | As guias do documento. |
| itens | inteiro | Quantas linhas de item o leitor extraiu do documento. |
| faturado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| pago | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| confianca | número | Quanto o identificador confiou no palpite, de 0 a 1. |
| erro | texto | Prefixado pela FASE em que parou: triagem, processamento ou distribuição. |
| avisos | — | Avisos do leitor, no formato que o handler produziu. |
ResumoDeDocumentos
De tudo que chegou, quanto virou dado — e quanto parou.
Devolvido por:GET /v1/documentos-recebidos/resumo
| Campo | Tipo | O que é |
|---|---|---|
| total | inteiro | O total do recorte pedido. |
| parados | inteiro | PENDENTE + FALHOU: chegou e não virou dado. É o número que importa. |
| porSituacao | lista de objetos | Os mesmos números, abertos por situação. |
| situacao | texto | A situação, no código que a rota devolve. |
| documentos | inteiro | Quantos documentos estão nesta situação. |
| porEstadoInterno | lista de objetos | A mesma contagem pelos quinze estados da nossa esteira. Não é contrato — serve para pedir suporte sabendo onde parou. |
| estadoInterno | texto | O estado da esteira interna. Pode mudar sem aviso. |
| documentos | inteiro | Quantos documentos estão neste estado interno. |
PassosDaExecucao
Onde o robô esteve e onde parou. Quando uma execução falha, é aqui que se vê se nem chegou a logar, se logou e não achou o documento, ou se achou e o download caiu.
Devolvido por:GET /v1/execucoes/{id}/passos
| Campo | Tipo | O que é |
|---|---|---|
| execucaoId | texto | A execução que produziu este registro, pelo identificador do Miydas. |
| tentativas | inteiro | Quantas execuções a cadeia tem: a raiz mais as retentativas. |
| passos | lista de objetos | A trilha, em ordem. É aqui que se vê se o robô nem chegou a logar, se logou e não achou o documento, ou se achou e o download caiu. |
| tentativa | inteiro | Qual tentativa produziu este passo. |
| numero | inteiro | A ordem do passo dentro da tentativa, a partir de 1. |
| nome | texto | O que o passo faz, em uma linha (ex. login, buscar documento, baixar). |
| tipo | texto | A categoria do passo — navegação, requisição, extração. |
| situacao | texto um de: PENDING, RUNNING, SUCCESS, FAILED, SKIPPED | Como este passo terminou. O primeiro FAILED da lista é onde a execução realmente parou. |
| iniciadoEm | texto | Quando o processamento começou, em ISO 8601 com fuso. |
| concluidoEm | texto | Quando o processamento terminou, em ISO 8601 com fuso. null = ainda corre. |
| duracaoMs | inteiro | Quanto durou, em milissegundos. |
| erro | texto | O que falhou. null quando não falhou nada. |
CodigoDaOperadora
De-para do código próprio da operadora para a TUSS. Quando o retorno vem com o código dela, não há o que fazer sem esta tradução.
Devolvido por:GET /v1/operadoras/{registroANS}/codigos
| Campo | Tipo | O que é |
|---|---|---|
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| codigoTuss | texto | Código do procedimento na TUSS, a terminologia da ANS. |
| descricao | texto | A descrição que acompanha o código nos retornos da operadora. |
| origem | texto | DERIVADO = observado nos retornos, não declarado pela operadora. |
| ocorrencias | inteiro | Quantas vezes o par apareceu. Com 1, é palpite; com 40, é fato. O número sai para você decidir. |
DocumentosDaOperadora
O que a operadora publica, e se conseguimos ler.
Devolvido por:GET /v1/operadoras/{registroANS}/documentos
| Campo | Tipo | O que é |
|---|---|---|
| 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. |
| documentos | lista de objetos | O que esta operadora publica — e, em cada um, se já sabemos traduzir. |
| nome | texto | Como a operadora chama o documento no portal dela. |
| tipoDocumento | texto | Para que tipo nosso ele mapeia (ex. DEMONSTRATIVO_PAGAMENTO). |
| formato | texto | Em que formato o dado chegou. |
| periodicidade | texto | De quanto em quanto tempo ela publica, quando há regra (ex. mensal, quinzenal). |
| leitura | texto | NAO_IMPLEMENTADO = a operadora publica e ainda não traduzimos: o documento chega e para na caixa de entrada como PENDENTE. |
LoteImportado
O lote que o prestador IMPORTOU — o XML que ele mandou à operadora. Não é o mesmo de /v1/lotes, que é o lote montado por esta API: os dois não se cruzam. É daqui que vem a camada de envio das guias.
Devolvido por:GET /v1/lotes-importados
| 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. |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| competencia | texto | 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. |
| tipoGuia | texto | Tipo de guia TISS: SP_SADT, CONSULTA, RESUMO_INTERNACAO, HONORARIO. |
| versaoTiss | texto | Versão do padrão TISS do documento (ex. 4.01.00). Quem dita a versão é a operadora. |
| origem | texto | IMPORTADO (veio de arquivo) | GERADO (montado aqui). |
| situacao | texto | O estado do lote importado aqui dentro — se foi lido, validado e distribuído em guias. |
| 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. |
| emitidoEm | texto | Data que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download. |
| transmitidoEm | texto | Quando o lote foi transmitido à operadora, em ISO 8601 com fuso. |
| valorTotal | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| conformidade | objeto | O veredito do esquema oficial da ANS sobre o XML importado. |
| xsdValido | booleano | O documento passou no esquema oficial da ANS (XSD). Lote inválido é recusado antes de ir à operadora. |
| guias | inteiro | As guias do documento. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
ItemFaturavel
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.
Devolvido por:GET /v1/itens-faturaveis
| 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ê. |
RemessaDeItensFaturaveis
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.
Devolvido por:POST /v1/itens-faturaveis
| 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. |
GuiasDoLote
As guias do lote com os itens de cada uma — SP/SADT e Consulta na mesma lista, distinguidas por tipo.
Devolvido por:GET /v1/lotes-importados/{id}/guias
| Campo | Tipo | O que é |
|---|---|---|
| loteId | texto | O lote a que esta guia pertence, pelo identificador do Miydas. |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| guias | lista de objetos | As guias do documento. |
| tipo | texto um de: SP_SADT, CONSULTA | O tipo da guia TISS. CONSULTA não tem itens: a consulta é o próprio procedimento. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| autorizadaEm | texto | Quando a operadora autorizou, em ISO 8601 com fuso. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| itens | lista de objetos | Vazio em CONSULTA: a consulta É o procedimento, e não tem item. |
| sequencial | inteiro | A ordem do registro dentro do documento, como a operadora a numerou. |
| tipo | texto | Natureza da linha: PROCEDIMENTO ou DESPESA (material, medicamento, taxa). |
| 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 item na tabela declarada. |
| descricao | texto | Descrição do item, como a fonte a informou. |
| quantidade | texto | 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. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| executadoEm | texto | Quando a execução ocorreu, em ISO 8601 com fuso. |
| atendidaEm | texto | Data do atendimento declarada no documento. |
ProcedenciaDaGuia
De onde veio cada número desta guia — o arquivo de envio e os documentos de retorno, com o que cada um sabia.
Devolvido por:GET /v1/guias/{id}/procedencia
| Campo | Tipo | O que é |
|---|---|---|
| guia | objeto | A guia a que este registro pertence. |
| 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. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| numeroLote | texto | O número do lote, como ele foi transmitido à operadora. |
| numeroProtocolo | texto | O número do protocolo na operadora. |
| operadora | texto | 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. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteirinha | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. |
| dataExecucao | texto | Data em que o procedimento foi executado, AAAA-MM-DD. |
| statusConciliacao | inteiro | O veredito do motor de conciliação sobre esta guia. |
| conciliadaEm | texto | Quando a conciliação rodou sobre este registro, em ISO 8601 com fuso. |
| justificativa | texto | A justificativa registrada, em texto livre. |
| observacao | texto | Observação registrada, em texto livre. |
| envio | objeto | Nulo quando a guia nasceu do retorno: o portal não guarda o arquivo que o prestador mandou. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| itens | inteiro | Quantas linhas o arquivo de envio trazia para esta guia. |
| arquivo | objeto | O arquivo de onde o dado veio. |
| 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. |
| nome | texto | Nome do arquivo de onde o dado veio, como a operadora o nomeou. |
| extensao | texto | Extensão do arquivo, sem o ponto. |
| formato | texto | Em que formato o dado chegou. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
| analise | lista de objetos | Cada documento de ANÁLISE que falou desta guia. Mais de um é normal: a operadora reemite, e cada reemissão é uma linha aqui. |
| 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. |
| demonstrativo | texto | O número do demonstrativo de onde este número veio. |
| emitidoEm | texto | A data do PROTOCOLO, não a emissão do demonstrativo — essa é o dia do download. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| completude | texto | O quanto do documento a operadora mandou: FULL (a conta toda), ACCEPTED_ONLY (só o aceito) ou GLOSA_ONLY (só o recusado). Somar valores de documentos de completudes diferentes dá número errado. |
| profundidade | texto | Até onde o documento desce: PROTOCOLO, GUIA ou ITEM. Documento que para na guia não permite recurso item a item. |
| fontes | lista de objetos | Os arquivos que compõem este documento — é o caminho de volta ao papel. |
| papel | texto | O que este arquivo carrega: ACCEPTED (só o aceito), GLOSA (só o recusado) ou FULL (o documento inteiro). |
| arquivo | objeto | O arquivo de onde o dado veio. |
| 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. |
| nome | texto | Nome do arquivo de onde o dado veio, como a operadora o nomeou. |
| extensao | texto | Extensão do arquivo, sem o ponto. |
| formato | texto | Em que formato o dado chegou. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
| pagamento | lista de objetos | Cada documento de PAGAMENTO que falou desta guia. Mais de uma linha com datas de crédito diferentes é parcela; com a mesma data, é reemissão. |
| 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. |
| demonstrativo | texto | O número do demonstrativo de onde este número veio. |
| pagoEm | texto | Sem reserva: ausente é ausente. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liquidoDoDemonstrativo | texto | NÃO é o líquido desta guia. É o do documento, e os débitos são do DIA inteiro — costuma vir negativo. |
| completude | texto | O quanto do documento a operadora mandou: FULL (a conta toda), ACCEPTED_ONLY (só o aceito) ou GLOSA_ONLY (só o recusado). Somar valores de documentos de completudes diferentes dá número errado. |
| profundidade | texto | Até onde o documento desce: PROTOCOLO, GUIA ou ITEM. Documento que para na guia não permite recurso item a item. |
| fontes | lista de objetos | Os arquivos que compõem este documento — é o caminho de volta ao papel. |
| papel | texto | O que este arquivo carrega: ACCEPTED (só o aceito), GLOSA (só o recusado) ou FULL (o documento inteiro). |
| arquivo | objeto | O arquivo de onde o dado veio. |
| 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. |
| nome | texto | Nome do arquivo de onde o dado veio, como a operadora o nomeou. |
| extensao | texto | Extensão do arquivo, sem o ponto. |
| formato | texto | Em que formato o dado chegou. |
| importadoEm | texto | Quando este documento entrou no Miydas, em ISO 8601 com fuso. |
RetornoSemVinculo
Julgamento da operadora que não casou com guia nenhuma. Medido: 4.666 linhas, R$ 65.244,35 em disputa. Não é o mesmo que guia sem envio — essa existe e aparece em /v1/guias.
Devolvido por:GET /v1/retornos-sem-vinculo
| Campo | Tipo | O que é |
|---|---|---|
| tipo | texto um de: ANALISE, PAGAMENTO | ANALISE: o julgamento da conta — o que a operadora reconheceu e o que glosou. PAGAMENTO: o caixa — o que ela creditou. Duas respostas distintas, quase sempre em meses distintos. |
| motivo | texto um de: GUIA_DESCONHECIDA, OPERADORA_DIVERGENTE, SEM_NUMERO_DE_GUIA | OPERADORA_DIVERGENTE pede corrigir cadastro; GUIA_DESCONHECIDA pede procurar a guia. Ações opostas. |
| 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. |
| demonstrativoId | texto | Abre em GET /v1/demonstrativos/{id} — o caminho de volta à prova. |
| 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. |
| competencia | texto | YYYY-MM (UTC) da data de NEGÓCIO: data do protocolo na análise, data do crédito no pagamento. Nunca da emissão. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| beneficiario | texto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| valores | objeto | Ausência é null, nunca "0.00": zero é valor que a operadora declarou. |
| informado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| processado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosa | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
ResumoDeRetornosSemVinculo
Quanto está solto, e onde. Não é paginado: somar meia competência daria um total errado.
Devolvido por:GET /v1/retornos-sem-vinculo/resumo
| Campo | Tipo | O que é |
|---|---|---|
| total | inteiro | O total do recorte pedido. |
| montante | texto | Glosa quando há; senão o liberado — o valor em disputa na linha. |
| porMotivo | lista de objetos | Os mesmos números, abertos por motivo. |
| motivo | texto | O motivo, como a operadora o nomeou. |
| linhas | inteiro | Quantas linhas o recorte tem. |
| montante | texto | O montante deste motivo, em reais, decimal em string. |
| porOperadora | lista de objetos | Os mesmos números, abertos por operadora. |
| 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, para exibição. |
| linhas | inteiro | Quantas linhas o recorte tem. |
| montante | texto | O montante desta operadora, em reais, decimal em string. |
| porCompetencia | lista de objetos | Os mesmos números, abertos por mês de competência. |
| competencia | texto | 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. |
| linhas | inteiro | Quantas linhas o recorte tem. |
| montante | texto | O montante deste mês, em reais, decimal em string. |
MotivoDeGlosa
Um motivo distinto recebido por esta clínica, com quanto custou. Ordenado por valor.
Devolvido por:GET /v1/glosas/motivos
| Campo | Tipo | O que é |
|---|---|---|
| codigo | texto | O código do motivo. Nulo é o agrupamento de tudo que veio sem código. |
| significado | texto | Da Tabela 38, ou o texto da categoria quando o motivo veio sem código. |
| tipo | texto um de: TABELA_ANS, CODIGO_OPERADORA, CATEGORIA | De onde o código vem: a tabela oficial da ANS, a tabela própria da operadora, ou só uma categoria. |
| glosas | inteiro | Quantas glosas esta clínica recebeu com este motivo. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
GlosaSilenciosa
Pagaram a menor e não declararam glosa. Não aparece em relatório de glosa justamente por isso. Medido em produção: 82 guias, R$ 52.198,49.
Devolvido por:GET /v1/glosas/silenciosas
| Campo | Tipo | O que é |
|---|---|---|
| guiaId | texto | A guia a que este registro se refere, pelo identificador do Miydas. |
| 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. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| 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. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| executadoEm | texto | Quando a execução ocorreu, em ISO 8601 com fuso. |
| pagoEm | texto | Data do crédito do pagamento. |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| diferenca | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| percentual | número | Percentual já calculado, com duas casas. 12.50 é doze e meio por cento. |
| situacaoConciliacao | inteiro | 0–7. Ver situacao.codigo da guia do beneficiário para o significado. |
Beneficiario
O histórico de uma carteirinha nesta clínica. A pergunta que nenhum sistema respondia.
Devolvido por:GET /v1/beneficiarios/{carteira}
| Campo | Tipo | O que é |
|---|---|---|
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| nome | texto | A operadora frequentemente não manda. A carteirinha é a chave; o nome é enriquecimento. |
| operadoras | lista de objetos | As operadoras alcançadas pelo recorte pedido. |
| 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. |
| resumo | objeto | O histórico desta carteirinha nesta clínica, somado. |
| guias | inteiro | As guias do documento. |
| cobrado | texto | Decimal em string, duas casas — dinheiro não é number. |
| liberado | texto | Decimal em string, duas casas — dinheiro não é number. |
| glosado | objeto | Dois números, os dois verdade: declarado é o que a operadora chamou de glosa; derivado é cobrado menos liberado. |
| declarado | texto | Decimal em string, duas casas — dinheiro não é number. |
| derivado | texto | Decimal em string, duas casas — dinheiro não é number. |
| taxaGlosa | número | Proporção 0–1 do derivado sobre o cobrado. 0 quando não houve cobrança. |
| guiasComGlosaDeclarada | inteiro | Em quantas guias a operadora declarou glosa. |
| guiasPagas | inteiro | Em quantas guias já houve crédito declarado. |
| primeiraGuia | texto | Data da primeira guia desta carteirinha aqui. |
| ultimaGuia | texto | Data da guia mais recente desta carteirinha aqui. |
| glosas | objeto | As glosas desta carteirinha, somadas. |
| total | inteiro | O total do recorte pedido. |
| valorTotal | texto | Decimal em string, duas casas — dinheiro não é number. |
| alertas | lista de objetos | Sinal medido no histórico desta carteirinha, não previsão de modelo. |
| tipo | texto | Que sinal é este (ex. taxa de glosa acima da média, guia parada sem retorno). |
| detalhe | texto | Detalhe em texto livre, para humano. Não é contrato. |
BeneficiarioEncontrado
Devolvido por:GET /v1/beneficiarios
| Campo | Tipo | O que é |
|---|---|---|
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| nome | texto | Nome do beneficiário. A operadora frequentemente não manda — a chave é a carteirinha. |
| 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. |
| ultimaGuia | texto | Data da guia mais recente desta carteirinha, para distinguir homônimos na busca. |
GuiaDoBeneficiario
A guia pelo olhar da conciliação: os valores e o veredito do casamento entre cobrado e pago.
Devolvido por:GET /v1/beneficiarios/{carteira}/guias
| Campo | Tipo | O que é |
|---|---|---|
| guiaId | texto | A guia a que este registro se refere, pelo identificador do Miydas. |
| 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. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| lote | texto | O número do lote em que esta guia foi enviada. |
| 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. |
| executadoEm | texto | Quando a execução ocorreu, em ISO 8601 com fuso. |
| pagoEm | texto | Data do crédito do pagamento. |
| valores | objeto | Os quatro números da guia. Ausência é null, nunca "0.00". |
| cobrado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| liberado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| glosado | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| diferenca | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| conciliacao | objeto | O cruzamento que o Miydas fez entre o cobrado e o pago — não é o que a operadora disse. |
| situacao | objeto | O veredito do motor de conciliação sobre a guia, como código e por extenso. |
| codigo | inteiro | O código do veredito, de 0 a 7. descricao traz o mesmo em português — use o código na lógica. |
| descricao | texto | O mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar. |
| glosaDeclarada | booleano | A operadora declarou glosa. false com diferença a menor é glosa silenciosa: cortaram sem dizer. |
| direcaoDiferenca | texto | A_MENOR | A_MAIOR | null. |
| percentualGlosa | número | Quanto da cobrança virou glosa, em percentual com duas casas. |
| scoreConfianca | número | O quanto o casamento entre o que foi cobrado e o que foi pago é confiável. |
| prioridadeRevisao | texto | O quanto esta guia merece atenção humana, combinando valor em jogo e confiança do casamento. |
GlosaDoBeneficiario
Devolvido por:GET /v1/beneficiarios/{carteira}/glosas
| Campo | Tipo | O que é |
|---|---|---|
| glosaId | texto | A glosa a que este registro se refere, pelo identificador do Miydas. |
| nivel | texto | Em que nível a glosa pende: ITEM, GUIA ou PROTOCOLO. Medido na base: 56.709 em item, 262 em guia, nenhuma em protocolo — o recurso TISS é item a item, e é no item que a glosa quase sempre mora. |
| motivo | objeto | Por que cortaram, na palavra da operadora e no termo oficial. |
| codigo | texto | O código do motivo, como a operadora o emitiu. |
| significado | texto | O termo oficial da Tabela 38 da ANS, quando o código existe nela. |
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| categoria | texto | O agrupamento que a operadora deu ao motivo, quando ela agrupa. |
| descricao | texto | O texto livre que a operadora escreveu sobre esta glosa. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| procedimento | objeto | O procedimento a que a linha se refere. |
| codigo | texto | Código do procedimento na tabela declarada. |
| descricao | texto | Descrição do procedimento, como a fonte a informou. |
| registradaEm | texto | Quando o Miydas registrou o fato, em ISO 8601 com fuso. Não é quando ele aconteceu na operadora. |
ElegibilidadeResumida
Elegibilidade já consultada. Leitura: não fala com a operadora.
Devolvido por:GET /v1/beneficiarios/{carteira}/elegibilidades
| Campo | Tipo | O que é |
|---|---|---|
| elegibilidadeId | texto | A consulta de elegibilidade, pelo identificador do Miydas. |
| 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. |
| elegivel | booleano | A operadora respondeu que o beneficiário pode ser atendido. |
| alcance | texto | CARTEIRINHA | PROCEDIMENTO — até onde a operadora respondeu. |
| motivoNaoElegivel | texto | O que a operadora respondeu quando negou o atendimento, na língua dela. |
| plano | texto | Nome do plano do beneficiário na operadora. |
| validadeCarteira | texto | Último dia de validade da carteirinha informado pela operadora. |
| consultadaEm | texto | Quando a consulta à operadora aconteceu, em ISO 8601 com fuso. |
AutorizacaoResumida
Devolvido por:GET /v1/beneficiarios/{carteira}/autorizacoes
| Campo | Tipo | O que é |
|---|---|---|
| autorizacaoId | texto | A autorização, pelo identificador do Miydas. |
| 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. |
| situacao | objeto | O veredito da operadora sobre a guia, no nosso vocabulário e no dela. |
| codigo | texto | O veredito traduzido (AUTORIZADA, NEGADA, EM_ANALISE…). Nulo enquanto ela não respondeu. |
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| validadeSenha | texto | Último dia em que a senha de autorização pode ser usada. Passou disso, a guia volta para a fila. |
| autorizadaEm | texto | Quando a operadora autorizou, em ISO 8601 com fuso. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| solicitadaEm | texto | Quando a solicitação foi feita, em ISO 8601 com fuso. |
EloDaLinhaDoTempo
Um elo com o instante em que o fato ACONTECEU, não em que foi registrado — guia pela execução, pagamento pelo crédito. Elo sem data é omitido em vez de receber data inventada.
Devolvido por:GET /v1/beneficiarios/{carteira}/linha-do-tempo
| Campo | Tipo | O que é |
|---|---|---|
| em | texto | Quando este fato foi registrado, em ISO 8601 com fuso. |
| tipo | texto um de: GUIA_EXECUTADA, GUIA_PAGA, GLOSA, ELEGIBILIDADE, AUTORIZACAO | Que fato é este elo. |
| titulo | texto | O fato em uma linha, pronto para exibir na linha do tempo. |
| valor | texto | Decimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes. |
| referencia | texto | O número de guia, quando há. Senão o id do recurso. |
Autorizacao
Devolvido por:POST /v1/autorizacoesGET /v1/autorizacoesPOST /v1/autorizacoes/consultasGET /v1/autorizacoes/{id}POST /v1/autorizacoes/{id}/consultasPOST /v1/autorizacoes/{id}/envioPATCH /v1/autorizacoes/{id}POST /v1/autorizacoes/{id}/cancelamentoPUT /v1/autorizacoes/{id}/executadosPOST /v1/autorizacoes/{id}/execucao
| 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. |
| 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. |
| 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. |
| numeroGuiaOperadora | texto | 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. |
| processamento | Processamento | O andamento do pedido COM A OPERADORA. Enquanto ele não concluir, a situação abaixo é nula — o recurso existe, a resposta ainda não. |
| situacao | objeto | Nula até a operadora responder. codigoOperadora é o que ela mandou. |
| codigo | texto um de: A_ENVIAR, ENVIANDO, EM_ANALISE, AUTORIZADA, PARCIALMENTE_AUTORIZADA, NEGADA, AGUARDANDO_JUSTIFICATIVA, AGUARDANDO_DOCUMENTACAO, CANCELADA, NAO_EXIGE_AUTORIZACAO, INDETERMINADA | O veredito traduzido. NAO_EXIGE_AUTORIZACAO não é negativa: é a operadora dizendo que o procedimento passa direto. |
| descricao | texto | O mesmo estado de situacao.codigo, em português, para mostrar a gente. O contrato é o código; esta frase pode mudar. |
| codigoOperadora | texto | O código do prestador NA operadora. Cada operadora tem o seu, e é ele que a operadora exige no documento — não o CNPJ. |
| senha | texto | A senha de autorização que a operadora concedeu. É ela que autoriza a execução. |
| validadeSenha | texto | Último dia em que a senha de autorização pode ser usada. Passou disso, a guia volta para a fila. |
| dataAutorizacao | texto | Data em que a operadora autorizou, AAAA-MM-DD. |
| dataSolicitacao | texto | O dia em que a autorização foi pedida. É por ele que de e ate recortam a listagem. |
| beneficiario | objeto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| nome | texto | Nome do beneficiário como a operadora o devolveu — pode divergir do seu cadastro. |
| solicitante | objeto | Quem pediu o procedimento. |
| nome | texto | Nome do profissional solicitante. |
| conselho | texto | Sigla do conselho profissional (CRM, CRO, COREN…). |
| numero | texto | Número de inscrição do solicitante no conselho. |
| uf | texto | Sigla da unidade federativa, duas letras (ex. SC). |
| cbo | texto | Ocupação do profissional na CBO, seis dígitos. |
| pedido | objeto | O que foi pedido, como está gravado agora — e é isto que PATCH /v1/autorizacoes/{id} corrige enquanto a guia não foi autorizada. Vem junto porque campo corrigível sem o valor atual ao lado se lê como "não preenchido", e quem corrige reescreve por cima do que havia. |
| carater | texto um de: ELETIVO, URGENCIA | Eletivo ou urgência/emergência. |
| indicacaoClinica | texto | A justificativa clínica do pedido, como foi enviada. |
| observacao | texto | Observação livre para o auditor da operadora. |
| numeroGuiaPrincipal | texto | A guia principal, quando esta é continuação de outra. |
| coberturaEspecial | texto | Cobertura especial (dm_tipoCoberturaEspecial): gestante, aidético ou recém-nascido. |
| recemNascido | booleano | Atendimento a recém-nascido na mesma guia da mãe. |
| atendimento | objeto | Tipo e regime de atendimento e indicação de acidente, nos domínios TISS. null quando a operadora não os pede. |
| tipoAtendimento | texto | Tipo de atendimento (dm_tipoAtendimento). Exame de laboratório costuma ser 23. |
| regimeAtendimento | texto | Regime de atendimento (dm_regimeAtendimento): ambulatorial, hospitalar, domiciliar. |
| indicacaoAcidente | texto | Indicação de acidente (dm_indicacaoAcidente). 9 é "não é acidente". |
| saudeOcupacional | texto | Tipo de saúde ocupacional (dm_tipoSaudeOcupacional), quando o exame é admissional, periódico ou demissional. |
| portal | objeto | Campos que só certos portais pedem — CID-10, tempo de doença, data do acidente. null quando nenhum foi informado. |
| cid | texto | CID-10 da hipótese diagnóstica, quando o portal o exige. |
| tempoDoenca | texto | Há quanto tempo o quadro dura, no formato que o portal pede. |
| dataAcidente | texto | O dia do acidente, quando houve (AAAA-MM-DD). |
| evidencias | objeto | O que existe de PROVA sobre o desfecho — e não as URLs. Os arquivos são privados; os bytes saem por GET /autorizacoes/{id}/evidencia/{tela|guia}, que confere a empresa. URL assinada aqui entraria no histórico de toda consulta de lista. |
| tela | booleano | Há print do portal no momento em que ele respondeu — autorizada, negada ou erro. Capturado no envio; guias enviadas antes de 20/11/2026 não têm. |
| guia | booleano | Há o PDF que a própria operadora imprime, baixado no ato da autorização. Só onde o portal oferece impressão nativa. |
| procedimentos | lista de objetos | Os procedimentos do documento. |
| id | texto | Identifica este procedimento. É o que se manda em refazItem ao pedir de novo o que foi negado. |
| 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 ela vai no documento. |
| quantidadeSolicitada | número | Quantas unidades você pediu. |
| quantidadeAutorizada | número | Quantas a operadora liberou. Menor que a solicitada é autorização parcial — execute só o autorizado, ou a diferença vira glosa. |
| quantidadeExecutada | número | Quantas foram REALMENTE executadas, quando já se declarou. null é "ainda não declarado" e 0 é "conferi e não executei" — a diferença importa. Item com quantidadeAutorizada nula e esta preenchida é exame acrescentado na execução. |
| motivos | lista de texto | O que a operadora alegou sobre ESTE procedimento. |
| refazItem | texto | O id do procedimento que este refaz, numa guia anterior. null é a primeira tentativa. É por esta cadeia que se sabe quantas vezes o mesmo exame foi pedido. |
| motivos | lista de texto | O que a operadora alegou sobre a guia inteira. |
| requisicao | objeto | A requisição que originou a guia. null quando ela nasceu direto. parte/partes respondem "por que três guias?" — a operadora limita exames por guia, e a requisição foi dividida. |
| id | texto | A requisição, para abrir o papel que originou esta guia. |
| numero | texto | O número legível da requisição, do prestador para o prestador (REQ-2026-0412). |
| parte | número | Qual das guias desta requisição é esta. null quando a requisição gerou uma só. |
| partes | número | Em quantas guias a requisição foi dividida pelo limite de exames da operadora. |
| proximaAcao | objeto | O que fazer agora com esta guia. Decidido pelo servidor: só ele sabe quantos dias de silêncio deixam de ser normais, o que cada código de negativa significa e se a senha está vencendo. Mostre; não recalcule. |
| codigo | texto | ENVIAR, CONSULTAR, IMPRIMIR_GUIA, REFAZER_COM_CAPTURA… — para a interface decidir o botão. |
| texto | texto | A frase pronta, escrita para quem está no balcão. |
| precisaDeMim | booleano | Esta guia espera alguém AGORA. Guia em análise dentro do prazo responde false — enchê-la na fila é como se esconde a que precisa. |
| execucao | objeto | A execução do exame, nas operadoras que exigem registrá-la depois do atendimento. null não afirma que o exame não foi feito: afirma que não foi executado pelo Miydas — pode ter sido registrado à mão no portal da operadora. |
| executada | booleano | A operadora registrou o atendimento. |
| parcial | booleano | Parte do pedido entrou na guia; o resto continua pendente. |
| guiaGerada | texto | A guia de serviço que a operadora emitiu ao executar — número NOVO, diferente de numeroGuiaOperadora, e é ele que o faturamento cobra. |
| situacaoOperadora | texto | O rótulo que a operadora deu à execução (ex.: "Executada"). |
| mensagem | texto | O que a operadora respondeu à execução, na frase dela — inclusive a recusa, quando houve. |
| em | texto | Quando a execução foi registrada. |
| historico | lista de objetos | O que já se fez com esta guia, em ordem — a solicitação e cada consulta ou cancelamento depois dela. |
| ocorridoEm | texto | Quando o fato aconteceu, em ISO 8601 com fuso. |
| tipo | texto um de: SOLICITACAO, CONSULTA, CANCELAMENTO | Que ação foi esta. |
| origem | texto um de: SOLICITACAO, CONSULTA | SOLICITACAO: a guia nasceu aqui. CONSULTA: foi pedida fora do Miydas e importada depois. |
| etapa | texto um de: PREVIA, EXECUCAO | Como a guia foi pedida: PREVIA antes de executar (o caso normal) ou EXECUCAO com o exame já feito. Decide se a operadora cobra a confirmação de presença do beneficiário — por isso quem vai transmitir uma guia A_ENVIAR precisa saber antes de enviar. |
| teste | booleano | true: criado por chave de teste (myd_test_…), executado na homologação da operadora e visível só para chaves de teste. |
| proximaConsultaEm | texto | Quando o acompanhamento automático volta a perguntar à operadora. null quando a guia não está em acompanhamento — porque já tem desfecho, ou porque ainda não saiu daqui. Serve para não consultar à mão o que o robô já ia consultar. |
| consultasAutomaticas | número | Quantas vezes o Miydas já reconsultou esta guia por conta própria. |
| criadaEm | texto | Quando o registro nasceu no Miydas, em ISO 8601 com fuso. |
| atualizadaEm | texto | Quando o registro mudou pela última vez no Miydas, em ISO 8601 com fuso. |
Elegibilidade
Devolvido por:POST /v1/elegibilidadesGET /v1/elegibilidadesGET /v1/elegibilidades/{id}
| 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. |
| 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. |
| carteira | texto | Número da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador. |
| processamento | Processamento | O andamento da consulta COM A OPERADORA. Enquanto ele não concluir, elegivel é nulo. |
| elegivel | booleano | A operadora respondeu que o beneficiário pode ser atendido. |
| alcance | texto um de: CARTEIRINHA, PROCEDIMENTO | Até onde a operadora respondeu: pela carteirinha, ou por procedimento. |
| beneficiario | objeto | O nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica. |
| nome | texto | Nome do beneficiário como a operadora o devolveu — pode divergir do seu cadastro. |
| validadeCarteira | texto | Último dia de validade da carteirinha informado pela operadora. |
| plano | texto | Nome do plano do beneficiário na operadora. |
| procedimentosPedidos | lista de texto | Os códigos que você perguntou. Devolvidos de volta para que a ausência de um deles em procedimentos seja visível: operadora que só responde pela carteirinha não respondeu por procedimento nenhum. |
| procedimentos | lista de objetos | Os procedimentos do documento. |
| codigo | texto | Código do procedimento na tabela declarada. |
| descricao | texto | Descrição do procedimento, como ela vai no documento. |
| elegivel | booleano | A operadora cobre ESTE procedimento para este beneficiário. |
| motivos | lista de texto | O que ela alegou sobre este procedimento. |
| foraDoContrato | booleano | Não está no contrato do prestador com a operadora |
| motivos | lista de texto | O que a operadora alegou sobre a elegibilidade como um todo. |
| avisos | lista de texto | O que você precisa saber para não ler esta resposta errado — por exemplo, que a operadora respondeu só pela carteirinha. |
| teste | booleano | true: criado por chave de teste (myd_test_…), executado na homologação da operadora e visível só para chaves de teste. |
| criadaEm | texto | Quando o registro nasceu no Miydas, em ISO 8601 com fuso. |
Evento
Devolvido por:GET /v1/eventos
| Campo | Tipo | O que é |
|---|---|---|
| nome | texto | O nome do evento, no formato recurso.fato (ex. autorizacao.concluida). É o que se assina. |
| recurso | texto | A que família de recurso este evento pertence — é o prefixo do nome. |
| quando | texto | Em que momento do ciclo este evento é emitido. |
| escopoNecessario | texto | Escopo que a chave precisa ter para receber |
Assinatura
Devolvido por:GET /v1/assinaturasGET /v1/assinaturas/{id}
| 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. |
| url | texto | A URL, com esquema. |
| eventos | lista de texto | Nomes exatos, recurso.* ou * |
| descricao | texto | Para que serve esta assinatura. É o que distingue uma da outra na lista. |
| ativa | booleano | A assinatura está recebendo eventos. |
| criadaEm | texto | Quando o registro nasceu no Miydas, em ISO 8601 com fuso. |
| atualizadaEm | texto | Quando o registro mudou pela última vez no Miydas, em ISO 8601 com fuso. |
AssinaturaCriada
Devolvido por:POST /v1/assinaturas
| 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. |
| url | texto | A URL, com esquema. |
| eventos | lista de texto | Nomes exatos, recurso.* ou * |
| descricao | texto | Para que serve esta assinatura. É o que distingue uma da outra na lista. |
| ativa | booleano | A assinatura está recebendo eventos. |
| criadaEm | texto | Quando o registro nasceu no Miydas, em ISO 8601 com fuso. |
| atualizadaEm | texto | Quando o registro mudou pela última vez no Miydas, em ISO 8601 com fuso. |
| segredo | texto | Só nesta resposta. Guarde: é com ele que se confere miydas-assinatura. |
SegredoAssinatura
O segredo novo depois da troca. O anterior para de valer na hora.
Devolvido por:POST /v1/assinaturas/{id}/segredo
| 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. |
| segredo | texto | Só nesta resposta. Guarde: é com ele que se confere o cabeçalho miydas-assinatura. |
Entrega
Devolvido por:GET /v1/assinaturas/{id}/entregas
| 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. |
| evento | texto | O nome do evento, no formato recurso.fato. |
| recurso | objeto | Que tipo de recurso este registro descreve. |
| tipo | texto | Que tipo de recurso o evento descreve (ex. autorizacao, lote). |
| 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. |
| status | texto um de: PENDENTE, ENTREGUE, FALHOU | Em que ponto o processamento está. |
| tentativas | inteiro | Quantas vezes já tentamos. |
| httpStatus | inteiro | O código HTTP que o seu endpoint devolveu na entrega. |
| erro | texto | O que falhou. null quando não falhou nada. |
| criadaEm | texto | Quando o registro nasceu no Miydas, em ISO 8601 com fuso. |
| entregueEm | texto | Quando a entrega do evento foi aceita pelo seu endpoint, em ISO 8601 com fuso. |
| proximaTentativaEm | texto | Quando sai a próxima tentativa de entrega. null = não há outra. |
ResultadoTeste
Devolvido por:POST /v1/assinaturas/{id}/teste
| Campo | Tipo | O que é |
|---|---|---|
| entrega | texto | O id da entrega de teste — acompanhe por ele em /assinaturas/{id}/entregas. |
| entregue | booleano | O seu endpoint aceitou (2xx). false com httpStatus nulo = não respondeu a tempo. |
| httpStatus | inteiro | O código HTTP que o seu endpoint devolveu na entrega. |
| erro | texto | O que falhou. null quando não falhou nada. |