Documentação Orbi

Protocolo Unificado de Indicadores

O Protocolo Unificado de Indicadores (PUI) é o formato único que toda origem usa para alimentar o Orbi. Ele tem duas peças — a definição do indicador e a medição — e dois transportes — push (a origem envia) e pull (o Orbi busca). Qualquer fonte que fale esse protocolo vira uma origem, sem que o Orbi precise conhecer seu domínio.

Em todos os payloads, datas e horas trazem o fuso horário explícito (offset -03:00). O Orbi opera no fuso de São Paulo.

Definição de indicador

A definição descreve o indicador. A origem pode declará-la junto com as medições (origem self-describing): se o indicador ainda não existe, ele é criado; se já existe, é atualizado.

{
  "key": "fiscal.notas_emitidas",
  "name": "Notas fiscais emitidas",
  "description": "NFS-e emitidas com sucesso",
  "unit": "count",
  "value_type": "integer",
  "direction": "up_is_better",
  "aggregation": "sum",
  "default_period": "day",
  "tags": ["fiscal"],
  "dimensions": ["filial"]
}

Campos:

Campo Valores Descrição
key slug Identidade estável do indicador dentro da origem.
name texto Nome exibido.
description texto Opcional.
unit count, currency_brl, percent, ms, ratio, custom:<x> Unidade do valor.
value_type integer, decimal, percent, duration_ms, money Tipo do valor.
direction up_is_better, down_is_better, neutral O que conta como "bom".
aggregation sum, avg, last, min, max Como colapsar um período.
default_period minute, hour, day, week, month Granularidade natural.
tags lista Organização/agrupamento.
dimensions lista Chaves de recorte que as medições podem trazer.

Medição

Uma medição é um ponto na série.

{
  "source": "minha-origem",
  "key": "fiscal.notas_emitidas",
  "external_ref": "2026-06-09|isaec",
  "ts": "2026-06-09T18:00:00-03:00",
  "value": 142,
  "dimensions": { "filial": "isaec" },
  "meta": { "lote": "noturno" }
}
Campo Obrigatório Descrição
source sim Identificador da origem registrada no Orbi.
key sim O indicador, dentro da origem.
external_ref sim Chave de idempotência (veja abaixo).
ts sim Instante da medição, com fuso (-03:00).
value sim O número medido.
dimensions não Objeto de recortes (filial, setor…).
meta não Objeto livre, para contexto adicional.

Idempotência

O Orbi identifica cada medição pela tripla (source, key, external_ref). Reenviar a mesma medição atualiza o ponto existente, em vez de criar um duplicado. Isso torna seguro repetir o envio (re-execução, reprocessamento, falha de rede).

Como escolher o external_ref:

  • Snapshot recorrente (um número por período): use o período como referência — por exemplo 2026-06-09 para o total do dia. Reenviar o dia inteiro apenas corrige o valor.
  • Evento único (cada ocorrência é um ponto): use um identificador único do evento. Cada um vira um ponto novo.

Se houver dimensões, inclua-as na referência para manter um ponto por recorte — por exemplo 2026-06-09|isaec.

Auto-descoberta

Se uma medição chega com uma key que o Orbi ainda não conhece, o indicador é criado automaticamente no estado descoberto. A ingestão nunca é recusada por isso. Depois, um gestor promove, edita ou oculta o indicador descoberto. Assim você pode começar a enviar dados sem cadastrar nada antes.

Versionamento

Todo payload carrega protocol_version (atual: "1.0"). O Orbi rejeita apenas versões maiores e incompatíveis, garantindo que integrações existentes continuem funcionando.

Próximos passos