Demonstrativos
/v1/demonstrativos/leiturasLê um arquivo TISS e devolve o demonstrativo
O Miydas é dono do parser TISS; quem integra é dono do arquivo. Esta rota existe para quem recebeu o demonstrativo por fora do portal (e-mail, download manual) e não quer escrever um segundo parser. NÃO fala com a operadora: é POST porque carrega corpo, não porque executa — não gasta cota, não cria execução e não aceita Prefer: wait. NÃO persiste: lê e devolve. O acervo é GET /v1/demonstrativos, e gravar aqui duplicaria o documento que já veio do portal, com dois ids para o mesmo protocolo. Buscar documento NOVO é POST /v1/retornos/sincronizacoes.
- Escopo:
- retorno:ler
- Resposta:
- 200
Pedido
Esta rota não recebe parâmetro nenhum — só a chave.
Exemplo de chamada
curl -X POST https://api.miydas.com.br/v1/demonstrativos/leituras \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | LeituraDeArquivo | O recurso. Os campos estão na tabela abaixo. |
O resultado de ler um arquivo. Nada foi gravado: o acervo e GET /v1/demonstrativos.
Campos de LeituraDeArquivo
| 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. |
Exemplo de retorno
{
"data": {
"arquivo": {
"nome": "demonstrativo-pagamento-202609.xml",
"formato": "XML",
"bytes": 184320
},
"demonstrativos": [
{
"tipo": "PAGAMENTO",
"numeroDemonstrativo": "000000187",
"protocolo": "PROTO-18700001",
"competencia": "2026-09",
"operadora": "UNIMED REGIONAL",
"emitidoEm": "2026-10-05",
"creditoEm": "2026-10-10",
"valores": {
"informado": "1200.00",
"processado": "1200.00",
"liberado": "1050.00",
"glosa": "150.00"
},
"valorPago": "1050.00",
"guias": [
{
"numeroGuiaPrestador": "88120",
"numeroGuiaOperadora": "2026000188120",
"senha": null,
"beneficiario": "BENEFICIARIO DE EXEMPLO",
"carteira": "00000000000000000",
"atendimentoEm": "2026-09-18",
"valores": {
"informado": "1200.00",
"processado": "1200.00",
"liberado": "1050.00",
"glosa": "150.00"
},
"glosas": [],
"itens": [
{
"tipo": "PROCEDIMENTO",
"sequencial": "1",
"codigoProcedimento": "40304361",
"codigoDespesa": null,
"descricao": "Hemograma com contagem de plaquetas",
"quantidade": "1",
"valores": {
"informado": "150.00",
"processado": "150.00",
"liberado": "0.00",
"glosa": "150.00"
},
"glosas": [
{
"codigo": "1308",
"descricao": "Procedimento nao consta no rol contratado",
"valor": "150.00"
}
]
}
]
}
],
"liquidacao": {
"totalDebitos": "48.30",
"totalCreditos": "0.00",
"lancamentos": [
{
"natureza": "DEBITO",
"tipo": "1",
"descricao": "IRPJ Prod Medica",
"valor": "15.75"
},
{
"natureza": "DEBITO",
"tipo": "3",
"descricao": "ISS",
"valor": "32.55"
}
]
}
}
],
"avisos": []
}
}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_leiturasO sandbox responde sempre em GET, mesmo para uma operação POST: ele devolve a forma da resposta, não executa nada.
A chave de teste myd_test_… é outra coisa: ela opera na homologação da operadora e serve para escrever. Para ver o formato antes de ter credencial, convênio e varredura, é este sandbox.
Erros
| Código | HTTP | Quando | O que fazer |
|---|---|---|---|
| ARQUIVO_AUSENTE | 400 | A leitura foi pedida sem arquivo, com mais de um arquivo, ou com o arquivo em outro campo. | Envie multipart/form-data com um arquivo só, no campo arquivo. |
| ARQUIVO_GRANDE | 413 | O arquivo passa do teto de leitura. details.limiteMb diz qual é. | Se for um ZIP com muitos documentos, divida-o e leia em partes. |
| FORMATO_NAO_LIDO | 415 | A extensão está fora da leitura estruturada (hoje .xml e .zip). PDF, imagem e planilha não viram dado. | Recusado de propósito, em vez de devolver lista vazia: use o arquivo XML que a operadora disponibiliza. |
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.