Demonstrativos
/v1/demonstrativos/{id}O documento inteiro: protocolos, guias, glosas e liquidação
A glosa devolvida aqui é a mesma de GET /v1/glosas/{id} — mesmo mapper, não uma segunda leitura.
Não existe campo liquido no topo: valorLiquido do documento é o liberado dele menos o imposto do DIA inteiro, e a operadora repete o bloco em cada demonstrativo daquela data (medido: liberado 587,97, débitos do dia 6.313,66, campo = −5.725,69). O líquido sai em liquidacao[], por data de crédito.
- Escopo:
- retorno:ler
- Resposta:
- 200
Pedido
Caminho
| {id}* | 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. |
Exemplo de chamada
curl -X GET https://api.miydas.com.br/v1/demonstrativos/cmf3k2x9a0001aut \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | DemonstrativoDetalhado | O recurso. Os campos estão na tabela abaixo. |
O documento inteiro: protocolos, guias e glosas — e a liquidação, quando é documento de pagamento.
Campos de DemonstrativoDetalhado
| 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. |
Exemplo de retorno
{
"data": {
"id": "cmf3k2x9a0001dem",
"tipo": "PAGAMENTO",
"operadora": {
"registroANS": "334561",
"nome": "Unimed Blumenau"
},
"numeroDemonstrativo": "202607150001",
"competencia": "2026-07",
"creditoEm": "2026-07-15",
"emitidoEm": "2026-08-02",
"completude": "FULL",
"profundidade": "C",
"versaoTiss": "4.01.00",
"valores": {
"informado": "3.65",
"processado": "3.65",
"liberado": "3.56",
"glosa": "0.09"
},
"protocolos": [
{
"numeroProtocolo": "4530775",
"numeroLotePrestador": "2026070112",
"dataProtocolo": "2026-07-10",
"situacao": null,
"valores": {
"informado": "3.65",
"processado": "3.65",
"liberado": "3.56",
"glosa": "0.09"
},
"glosas": [],
"guias": [
{
"numeroGuiaPrestador": "000123",
"numeroGuiaOperadora": "18700001",
"carteira": null,
"beneficiario": null,
"senha": "18700001",
"situacao": null,
"atendimentoDe": null,
"atendimentoAte": null,
"fonteOrdem": null,
"valores": {
"informado": null,
"processado": "3.65",
"liberado": "3.56",
"glosa": "0.09"
},
"glosas": []
}
],
"totalDeGuias": 42,
"temMaisGuias": false
}
],
"guias": 42,
"importadoEm": "2026-08-02T11:04:19.000Z",
"liquidacao": [
{
"creditoEm": "2026-07-15",
"forma": "CREDITO_EM_CONTA",
"banco": "756",
"agencia": "0101",
"conta": "000000-0",
"valores": {
"informado": "3.65",
"processado": "3.65",
"liberado": "3.56",
"glosa": "0.09"
},
"debitos": [
{
"tipo": "IMPOSTO",
"subtipo": "ISS",
"valor": "0.11"
}
],
"creditos": [],
"totalDebitos": "0.11",
"totalCreditos": "0.00",
"liquido": "3.45"
}
],
"avisos": [],
"fontes": [
{
"origem": "MENSAGEM_TISS",
"papel": "FULL",
"ordem": 0,
"arquivo": {
"id": "cmf3k2x9a0001tis",
"nome": "demonstrativoRetorno-202607150001.xml",
"extensao": "xml",
"formato": "TISS_XML",
"tamanhoBytes": null,
"importadoEm": "2026-08-02T11:04:19.000Z"
}
}
]
}
}Experimente sem chave
O sandbox devolve este mesmo corpo, sem autenticação e sem tocar na base de ninguém.
curl https://api.miydas.com.br/v1/sandbox/demonstrativos_detalheA chave de teste myd_test_… é outra coisa: ela opera na homologação da operadora e serve para escrever. Para ver o formato antes de ter credencial, convênio e varredura, é este sandbox.
Erros
| Código | HTTP | Quando | O que fazer |
|---|---|---|---|
| RECURSO_NAO_ENCONTRADO | 404 | O id não existe — ou é de outra empresa, o que a API não distingue de propósito. Também a rota inexistente na v1. | Confira o id. |
Toda falha tem o mesmo formato: { "error": "CODIGO", "message": "…", "details": { … } }. error é estável e serve para lógica; message é para gente e pode mudar. Erros comuns a toda rota com chave (lista completa) não se repetem aqui.