Ogmma Revenue

Retenções

GET/v1/retencoes/{demonstrativoId}

A retenção de um demonstrativo

Responde 404 também quando o demonstrativo existe e não declara imposto retido.

Escopo:
retencao:ler
Resposta:
200

Pedido

Caminho

{demonstrativoId}*O demonstrativo a que este registro pertence, pelo identificador do Miydas.

Exemplo de chamada

curl -X GET https://api.miydas.com.br/v1/retencoes/cmf3k2x9a0001dem \
  -H "Authorization: Bearer $MIYDAS_CHAVE"

Resposta 200

dataRetencaoO recurso. Os campos estão na tabela abaixo.

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"
  }
}

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_obter

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

CódigoHTTPQuandoO que fazer
RECURSO_NAO_ENCONTRADO404O id não existe — ou é de outra empresa, o que a API não distingue de propósito. Também a rota inexistente na v1.Confira o id.

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.