Domínios e entidades

Mapa dos conceitos do Arena usados pela API — o que é empresa, campanha, vendedor e lançamento.

Modelo mental

A API opera sempre no contexto de uma empresa (tenant), resolvida automaticamente pela API Key. Você não envia company_id no body.

Empresa (API Key)
  └── Campanha (ativa ou campaign_id)
        └── Vendedor (seller)
              └── Lançamento / Entry (venda)

Entidades

Entidade	Onde vive	Papel na API
Empresa	`companies`	Tenant. Identificada pela API Key.
Campanha	`ranking_campaigns`	Período + métrica + meta opcional (`target_amount`). Pode ser informada ou usa a ativa.
Vendedor	`ranking_sellers`	Participante do ranking. Resolve por e-mail, `seller_id` ou `external_seller_id`.
Usuário	`users`	Login no App. Pode estar vinculado ao vendedor (`user_id`) — foto/avatar no telão.
Lançamento	`ranking_entries`	Valor creditado na campanha (o que a API cria).
Meta individual	`ranking_goals`	Meta por vendedor/time (opcional). Se vazia, usa meta da campanha.
API Key	`company_api_keys`	Credencial de integração. Hash no banco; plaintext só na criação.

Campanha

Ativa: no máximo uma por empresa (is_active = 1). Default da API se omitir campaign_id.
Métrica: valor (R$), quantidade ou pontos.
Meta da campanha: campo target_amount (ex.: 30.000) — progresso agregado no Ranking/Telão.
Monitor Telão: URL pública por monitor_token (sem login).

Vendedor — como a API resolve

Envie um destes identificadores (nessa ordem de uso):

Campo	Descrição
`seller_id`	ID interno em `ranking_sellers`
`seller_email`	E-mail do seller ou do usuário vinculado
`external_seller_id`	ID numérico do seller ou `user_id`

O vendedor precisa estar ativo (is_active = 1) na mesma empresa da chave.

Idempotência

Tabela ranking_entry_idempotency guarda (company_id, idempotency_key) → entry_id. Reenvio com a mesma chave devolve o lançamento já criado (200 + idempotent: true), sem duplicar no ranking.

Ir para API Ranking