Retenções
/v1/retencoes/demonstrativosA retenção demonstrativo por demonstrativo
Para conferir o consolidado linha a linha. competencia é a da emissão do documento, em UTC.
- Escopo:
- retencao:ler
- Resposta:
- 200
Pedido
Parâmetros de query
| Campo | Tipo | O que é |
|---|---|---|
| competencia | texto formato AAAA-MM | Mês AAAA-MM da data de NEGÓCIO do documento, em UTC — crédito na retenção, protocolo na glosa. NUNCA a data de emissão: o portal renderiza o documento no download, então a emissão é o dia em que nós baixamos. |
| 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. |
| limite | inteiro 1–200 · 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/retencoes/demonstrativos \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | lista de Retencao | O recurso. Os campos estão na tabela abaixo. |
| paginacao | Paginacao | Onde esta página está no total. Vem fora de data. |
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.
Campos de Retencao
| 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. |
Exemplo de retorno
{
"data": [
{
"demonstrativoId": "cmf3k2x9a0001dem",
"operadora": {
"registroANS": "334561",
"nome": "Unimed Blumenau"
},
"numeroDemonstrativo": "000123456",
"competencia": "2026-10",
"fonteCompetencia": "CREDITO",
"emitidoEm": "2026-09-30",
"creditoEm": "2026-10-18",
"total": "7856.44",
"decomposicao": {
"iss": "1926.94",
"pis": "4480.13",
"ir": "1445.20",
"inss": null,
"cofins": null,
"outros": "4.17",
"naoMapeados": null
},
"conferencia": {
"somaDosTributos": "7856.44",
"confere": true
},
"valorLiquidoDoDemonstrativo": "4871.03"
}
],
"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/retencoes_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.