Séries históricas e versões de fórmula

GET /v1/covenants/history · header iorq-fund-id · somente leitura

1. Um ponto por dia

A série de um covenant tem um ponto por dia. O ponto de um dia é a última apuração daquele dia, no horário de Brasília, gravada depois que o dia fecha.

• O dia de hoje não tem ponto. O valor de hoje está em GET /v1/covenants. O ponto do dia aparece na série a partir do dia seguinte.
• Dia sem arquivo novo repete o dado. Cada ponto é apurado sobre o arquivo mais recente que a administradora publicou. Em fim de semana e feriado ela não publica, e às vezes atrasa num dia útil; a apuração continua, e o ponto repete o valor e o as_of do ponto anterior até chegar um arquivo novo. Num fim de semana normal, sábado e domingo repetem o ponto de sexta (arquivo de quinta), e segunda traz o arquivo de sexta. Para série de dias úteis, descarte os pontos cujo as_of repete o do ponto anterior.
• Dia sem apuração não tem ponto. A série não interpola. Um intervalo sem pontos é um intervalo sem dado.

2. As datas de cada ponto

No ponto diário apuracao, as_of fica pelo menos um dia útil antes de date: um ponto com date 2026-09-29 (terça-feira) tem as_of 2026-09-28, e a distância cresce quando a administradora atrasa o arquivo. No ponto backfill_recalculo, as_of e date coincidem (ver a seção 3); no ponto monthly, as_of fica no mês do fechamento. Para comparar a série com o relatório da administradora, use as_of.

3. Pontos diários e pontos mensais

A apuração diária começou em 30/09/2026. Antes disso, a série traz um ponto por mês, recalculado sobre o fechamento mensal que a administradora publicou, e, a partir do primeiro arquivo diário da administradora, pontos diários reconstituídos depois do fato.

A emenda de 29 para 30/09. O ponto reconstituído usa a data do arquivo, e o ponto vivo usa o dia seguinte ao arquivo. Por isso o arquivo de 29/09 aparece duas vezes: no ponto de 29/09 (backfill_recalculo) e no de 30/09 (apuracao), com o mesmo as_of. Ao montar uma série por data do dado, agrupe por as_of.

Os pontos mensais e os reconstituídos têm estas limitações:

• Alguns covenants não têm ponto mensal nem reconstituído. patrimonio_minimo (média de 90 dias, que pede arquivo diário), primeira_operacao, over5, over15 e retorno_medio_30 começam na apuração diária.
• alocacao_dc e pdd_total começam em abril de 2026, quando a administradora passou a publicar a composição da carteira.
• Mês sem cotas emitidas não tem ponto, porque não há PL.

Use o parâmetro granularity para ler só um tipo de ponto.

4. Versões de fórmula

Cada ponto traz a formula_version com que foi calculado (v1, v2, ...). A versão muda quando a IORQ corrige ou ajusta a forma de calcular um covenant, por exemplo para seguir uma leitura mais precisa do regulamento.

• Ponto diário não é recalculado. Quando a versão muda, os pontos anteriores mantêm a versão e o valor com que foram gravados. A série mostra o degrau: até uma data, v2; a partir dela, v3.
• Ponto mensal e ponto reconstituído usam a fórmula e o limite vigentes na carga. Os pontos monthly e backfill_recalculo foram recalculados de uma vez, com a fórmula e o limite em vigor no momento da carga. A formula_version deles é essa versão, não a que vigorava na data do ponto.

Ao ler uma série que atravessa uma mudança de versão:

1. Separe os pontos por formula_version antes de calcular tendência ou média. Um salto no valor exatamente na data em que a versão muda é efeito da fórmula, não da carteira.
2. Compare cada ponto com o limit do próprio ponto, não com o limite de hoje: o limite também pode mudar ao longo da série.

5. Consultar a série

curl 'https://investor-api.iorq.com.br/v1/covenants/history?from=2026-08-01&to=2026-09-30&indicator=subordinacao_senior' \
  -H 'Authorization: Bearer eyJraWQiOiJyc2EtMjAyNiIs...' \
  -H 'iorq-fund-id: 6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f'

{
  "fund_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "series": [
    {
      "code": "subordinacao_senior",
      "name": "Índice de subordinação sênior",
      "category": "covenant",
      "base": "adm",
      "unit": "%",
      "points": [
        {
          "date": "2026-08-31",
          "as_of": "2026-08-31",
          "value": 63.2,
          "limit": 25,
          "limit_type": "min",
          "numerator_as_of": "2026-08-31",
          "denominator_as_of": "2026-08-31",
          "formula_version": "v1",
          "granularity": "monthly",
          "calculated_at": "2026-10-02T14:10:00Z",
          "source": "recalculo_fechamento_adm"
        },
        {
          "date": "2026-09-30",
          "as_of": "2026-09-29",
          "value": 63.5,
          "limit": 25,
          "limit_type": "min",
          "numerator_as_of": "2026-09-29",
          "denominator_as_of": "2026-09-29",
          "formula_version": "v1",
          "granularity": "daily",
          "calculated_at": "2026-10-01T02:50:00Z",
          "source": "apuracao"
        }
      ]
    }
  ],
  "next_page_token": null
}

• Por série: code, name, category e unit são os mesmos de GET /v1/covenants; a unidade vale para todos os pontos da série.
• Por ponto: os campos têm o mesmo significado do covenant corrente, mais granularity e source (pontos diários e mensais).
• Ordem e paginação: as séries vêm na ordem do catálogo e os pontos em ordem crescente de date. Uma série que não cabe numa página continua na seguinte. next_page_token vem null na última página.
• Erros: um indicator fora do catálogo do fundo responde 400 (COVENANT_NOT_PUBLISHED), e não uma série vazia; uma base diferente de adm responde 400 (BASE_NOT_PUBLISHED); janela inválida, page_size fora do intervalo ou page_token adulterado respondem 422. Ver os erros.