Ogmma Revenue

Retenções

GET/v1/retencoes

Imposto 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

CampoTipoO que é
competenciatexto
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.
registroANStexto
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

dataRetencaoConsolidadaO 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

CampoTipoO que é
competenciatextoO recorte pedido. Nulo = todas as competências.
recorteobjetoO 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.
registroANStextoRegistro 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.
demonstrativosinteiroQuantos demonstrativos entraram neste consolidado.
totaltextoDecimal em string, duas casas — dinheiro não é number.
porTributoobjetoTributos 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.
isstextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
pistextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
irtextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
insstextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
cofinstextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
outrostextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
naoMapeadosobjetoTributo 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.
semDecomposicaoobjetoQuanto do total chegou sem abertura por tributo. Não lance isto como ISS.
demonstrativosinteiroQuantos vieram só com o total, sem abertura por tributo.
totaltextoDecimal em string, duas casas — dinheiro não é number.
divergenciasinteiroDemonstrativos em que o total declarado não bate com a soma dos tributos.
porOperadoralista de objetosOs mesmos números, abertos por operadora.
registroANStextoRegistro 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.
nometextoRazão social da operadora, para exibição.
demonstrativosinteiroQuantos demonstrativos desta operadora entram no total.
totaltextoDecimal em string, duas casas — dinheiro não é number.
porCompetencialista de objetosOs mesmos números, abertos por mês de competência.
competenciatextoMê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.
demonstrativosinteiroQuantos demonstrativos deste mês entram no total.
totaltextoDecimal 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_consolidar

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

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.