Retenções
/v1/retencoesImposto retido na fonte, consolidado por competência e tributo
ISS, PIS, INSS e COFINS que a operadora retém e declara no demonstrativo de pagamento. Medido em produção: R$ 16.557.116,27 em 2.915 demonstrativos, com decomposição em 2.510. Sem competencia, consolida tudo e devolve a quebra por mês em porCompetencia.
semDecomposicao diz quanto do total chegou sem abertura por tributo, e divergencias em quantos demonstrativos o total declarado não bate com a soma dos quatro. Os dois existem para que ninguém lance na contabilidade um valor que a operadora não abriu, nem um que não fecha.
- 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. |
* 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 \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 200
| data | RetencaoConsolidada | O recurso. Os campos estão na tabela abaixo. |
O consolidado fiscal do recorte pedido, com o que NÃO fecha declarado em semDecomposicao e divergencias.
Campos de RetencaoConsolidada
| 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. |
Exemplo de retorno
{
"data": {
"competencia": "2026-09",
"recorte": {
"registroANS": null
},
"demonstrativos": 112,
"total": "58412.77",
"porTributo": {
"iss": "14284.19",
"pis": "28487.11",
"ir": "9823.04",
"inss": "6152.80",
"cofins": "9488.67",
"outros": "176.96",
"naoMapeados": null
},
"semDecomposicao": {
"demonstrativos": 9,
"total": "1201.44"
},
"divergencias": 0,
"porOperadora": [
{
"registroANS": "334561",
"nome": "Unimed Blumenau",
"demonstrativos": 84,
"total": "41905.22"
}
],
"porCompetencia": [
{
"competencia": "2026-09",
"demonstrativos": 112,
"total": "58412.77"
}
]
}
}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_consolidarA 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.