Integrando uma origem

Há duas formas de levar dados ao Orbi, ambas usando o mesmo protocolo:

Push — a sua origem envia as medições para o Orbi quando elas acontecem.
Pull — a sua origem publica um endereço de leitura e o Orbi busca as medições periodicamente.

Escolha push quando o evento já está no seu lado (você sabe quando emitiu a nota, fechou o chamado etc.). Escolha pull quando é mais simples expor um número atual e deixar o Orbi coletar no ritmo dele.

Antes de começar

No Orbi, cadastre a origem (menu Origens → Adicionar) escolhendo o tipo (push, pull, sql, manual ou webhook) e dê a ela um nome estável.
Para push (e para pull com autenticação), emita um token de ingestão da instância. Guarde-o com segurança — ele é mostrado apenas na criação.

Push — enviando medições

Envie um POST para /api/v1/measurements com o token no cabeçalho Authorization: Bearer <token>. O corpo declara os indicadores (opcional, para origem self-describing) e a lista de medições.

POST /api/v1/measurements
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "protocol_version": "1.0",
  "indicators": [
    {
      "key": "fiscal.notas_emitidas",
      "name": "Notas fiscais emitidas",
      "unit": "count",
      "value_type": "integer",
      "direction": "up_is_better",
      "aggregation": "sum",
      "default_period": "day",
      "dimensions": ["filial"]
    }
  ],
  "measurements": [
    {
      "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" }
    }
  ]
}

Resposta

O envio é em lote parcial: itens válidos são aceitos mesmo que outros falhem — nunca tudo falha por causa de um item. A resposta resume o que aconteceu e detalha os erros por item.

{
  "created": 1,
  "updated": 0,
  "rejected": 0,
  "errors": []
}

Lotes grandes

Para volumes grandes, use POST /api/v1/measurements:bulk, enviando uma medição por linha (formato NDJSON). A semântica de idempotência e lote parcial é a mesma.

Pull — publicando para o Orbi coletar

No modo pull, a sua origem expõe um endereço GET /api/indicators que devolve as definições e uma janela recente de medições (ou um snapshot atual). O Orbi coleta esse endereço no intervalo configurado.

{
  "source": "minha-origem",
  "protocol_version": "1.0",
  "indicators": [
    {
      "key": "fiscal.notas_emitidas",
      "name": "Notas fiscais emitidas",
      "unit": "count",
      "value_type": "integer",
      "direction": "up_is_better",
      "aggregation": "sum",
      "default_period": "day"
    }
  ],
  "measurements": [
    {
      "source": "minha-origem",
      "key": "fiscal.notas_emitidas",
      "external_ref": "2026-06-09",
      "ts": "2026-06-09T18:00:00-03:00",
      "value": 142
    }
  ]
}

Ao cadastrar a origem pull no Orbi, informe a URL do endereço de leitura e o intervalo de coleta. Se o endereço exigir autenticação, registre o token junto. O Orbi ingere o conteúdo pela mesma camada do push — então idempotência e auto-descoberta valem igual.

Outras formas de origem

SQL / consulta — uma medição vinda de uma consulta parametrizada, executada pelo coletor no intervalo definido; o resultado é mapeado para value e dimensions.
Webhook / API genérica — qualquer script, planilha ou automação faz o mesmo POST /api/v1/measurements com um token.
Manual — lance medições e metas diretamente pela tela, quando o número não tem fonte automática.

Boas práticas

Reenvie sem medo: com external_ref consistente, repetir o envio corrige o valor em vez de duplicar.
Sempre com fuso: todo ts traz o offset -03:00.
Declare o indicador junto: assim a origem é autossuficiente e novos indicadores aparecem sozinhos (em estado descoberto) para revisão.