Ogmma Revenue

Retenções

GET/v1/retencoes/demonstrativos

A 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

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.
limiteinteiro
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.
deslocamentointeiro
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

datalista de RetencaoO recurso. Os campos estão na tabela abaixo.
paginacaoPaginacaoOnde 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

CampoTipoO que é
demonstrativoIdtextoO demonstrativo a que este registro pertence, pelo identificador do Miydas.
operadoraobjetoA operadora do documento, identificada pelo registro ANS.
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 como a ANS a publica. Informativo — a chave é o registro.
numeroDemonstrativotextoO 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.
competenciatextoYYYY-MM (UTC) da data de NEGÓCIO: crédito na retenção, protocolo na glosa. Nunca da emissão.
fonteCompetenciatexto
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.
emitidoEmtextoData que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download.
creditoEmtextoData do primeiro crédito do demonstrativo. Vários créditos é caso real.
totaltextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
decomposicaoobjetoNulo quando a operadora mandou só o total (405 de 2.915 medidos).
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.
conferenciaobjetoConfere o total declarado contra a soma dos quatro tributos. Nulo quando falta um dos lados.
somaDosTributostextoDecimal em string, duas casas — dinheiro não é number.
conferebooleanofalse = 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.
valorLiquidoDoDemonstrativotextoDecimal 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_listar

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.