Demonstrativos
/v1/demonstrativosO retorno da operadora como acervo — análise de conta e pagamento
O que GET /execucoes/{id}/retornos não responde: ele é indexado pela execução que buscou o arquivo, e documento que entrou por importação manual não tem execução nenhuma. Aqui o recorte é o do negócio.
competencia é a data de NEGÓCIO — data do protocolo na análise, data do crédito no pagamento. Não é dataEmissao: o portal renderiza o documento no download, e medido na base inteira o mês da emissão difere do mês do protocolo em 96,1% dos documentos de análise e do mês do crédito em 89,5% dos de pagamento.
A lista traz o cabeçalho; protocolos, guias e glosas vêm no detalhe.
- Escopo:
- retorno:ler
- Resposta:
- 200
Pedido
Parâmetros de query
| 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. São duas respostas diferentes, em meses geralmente diferentes. |
| registroANS | texto 1–20 caracteres | 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 ou sem-data · formato AAAA-MM | Mês AAAA-MM da data de NEGÓCIO do documento, em UTC — crédito na retenção, protocolo na glosa. NUNCA a data de emissão: o portal renderiza o documento no download, então a emissão é o dia em que nós baixamos. |
| numeroProtocolo | texto 1–60 caracteres | O número do protocolo na operadora. |
| completude | texto um de: FULL, ACCEPTED_ONLY, GLOSA_ONLY | 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. |
| limite | inteiro 1–100 · padrão 50 | Quantos registros trazer nesta página. O teto varia por rota (50 a 200) e está nas regras do campo. |
| deslocamento | inteiro padrão 0 | Quantos registros pular, para a página seguinte. Use com paginacao.total da resposta; paginacao.temMais diz se vale pedir mais. |
* obrigatório. Campo desconhecido é recusado, não ignorado: a API responde VALIDATION_ERROR em vez de descartar em silêncio.
Exemplo de chamada
curl -X GET https://api.miydas.com.br/v1/demonstrativos \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de Demonstrativo | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde esta página está no total. Vem fora de data. |
O retorno da operadora como acervo: um documento de análise de conta ou de pagamento.
Campos de Demonstrativo
| 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. |
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": 1,
"guias": 42,
"importadoEm": "2026-08-02T11:04:19.000Z"
}
],
"paginacao": {
"total": 1,
"limite": 20,
"deslocamento": 0,
"temMais": false
}
}Experimente sem chave
O sandbox devolve este mesmo corpo, sem autenticação e sem tocar na base de ninguém.
curl https://api.miydas.com.br/v1/sandbox/demonstrativos_listarA chave de teste myd_test_… é outra coisa: ela opera na homologação da operadora e serve para escrever. Para ver o formato antes de ter credencial, convênio e varredura, é este sandbox.
Erros
Esta rota não tem erro próprio: só os comuns a qualquer chamada com chave — chave ausente ou inválida, escopo insuficiente, parâmetro recusado e erro interno.
Toda falha tem o mesmo formato: { "error": "CODIGO", "message": "…", "details": { … } }. error é estável e serve para lógica; message é para gente e pode mudar. Erros comuns a toda rota com chave (lista completa) não se repetem aqui.