API server-to-server

Base: https://seu-dominio/api/v1 Autenticação: Authorization: Bearer {chave-secreta-do-projeto} (a chave está em Configurações → Instalação)

Todas as respostas são JSON. Valores com sufixo _cents estão em centavos.

Parâmetros de período

Aceitos por /metrics, /ranking, /comparison e /orders:

Parâmetro	Valores
`period`	`today`, `yesterday`, `last_7`, `last_14`, `last_30`, `last_90`, `this_week`, `last_week`, `this_month`, `last_month`, `this_year`, `last_year`
`start` + `end`	`YYYY-MM-DD` (têm prioridade sobre `period`)

`GET /metrics`

curl -H "Authorization: Bearer $KEY" \
  "https://seu-dominio/api/v1/metrics?period=last_30&granularity=day"

{
  "period": { "label": "Últimos 30 dias", "start_date": "…", "days": 30 },
  "metrics": {
    "sessions": 16391, "visitors": 16391, "orders_approved": 731,
    "revenue_cents": 46854700, "net_cents": 39012000, "profit_cents": 30627131,
    "spend_cents": 4189200, "conversion_rate": 4.46, "approval_rate": 80.4,
    "avg_ticket_cents": 64097, "roas": 11.18, "roi": 631.2,
    "cac_cents": 5731, "ltv_cents": 64097, "ltv_cac_ratio": 11.18
  },
  "series": [{ "bucket": "2026-07-03", "revenue_cents": 1250000, "…": 0 }]
}

granularity: hour, day, week, month (padrão: automático).

`GET /ranking`

Parâmetro	Valores
`dimension`	`source`, `medium`, `campaign`, `adset`, `ad`, `content`, `term`, `product`, `checkout`, `payment`, `country`, `device`
`order_by`	`revenue_cents`, `profit_cents`, `orders_approved`, `roas`, `roi`, `conversion_rate`, `sessions`, `avg_ticket_cents`, `spend_cents`
`limit`	1–200 (padrão 50)

`GET /comparison`

Compara o período com o anterior equivalente. against=last_year compara com o mesmo intervalo do ano passado.

`GET /orders`

status (opcional): approved, refused, pending, refunded, chargeback. limit: 1–500.

`POST /orders`

Cria ou atualiza um pedido sem passar por webhook. Mesmo formato do webhook genérico (veja o README). Idempotente por order_id.

{ "order_id": "abc123", "status": "approved", "total": 497.00,
  "tracking": { "vid": "…", "sid": "…" } }

Resposta 201 se criou, 200 se atualizou.

`POST /ad-spend`

Importa investimento em mídia. Aceita lote de até 5.000 linhas — use isto para sincronizar Meta Ads / Google Ads diariamente.

{
  "rows": [
    { "date": "2026-08-01", "source": "facebook",
      "campaign_id": "120210000000001", "campaign_name": "Black Friday",
      "ad_id": "120210000000001-ad1", "ad_name": "Criativo A",
      "spend": 450.00, "impressions": 38000, "clicks": 620, "status": "ACTIVE" }
  ]
}

Idempotente por (data, source, campaign_id, adset_id, ad_id) — reenviar o mesmo dia atualiza em vez de duplicar. As métricas do dia são recalculadas automaticamente.

`POST /ask`

Pergunta ao assistente de IA.

{ "question": "Qual campanha teve o melhor ROI nos últimos 7 dias?",
  "conversation_id": null }

{ "answer": "…", "conversation_id": 12,
  "tools_used": ["get_ranking", "compare_periods"] }

Responde 503 se a IA não estiver configurada.

`GET /health`

Sem autenticação — para o load balancer. 200 saudável, 503 degradado.

Endpoints públicos

`POST /collect`

Coleta de eventos. Normalmente usado pelo track.js, mas pode ser chamado do servidor para eventos que não passam pelo navegador.

{ "k": "CHAVE_PUBLICA", "vid": "uuid", "sid": "uuid",
  "event": "pageview", "url": "https://…", "props": {}, "value": 0 }

`POST /webhook/{gateway}/{chave-secreta}`

Recebe vendas. Responde 200 imediatamente e processa na fila.

Erros

Código	Significado
`401`	Chave ausente ou inválida
`403`	Sem permissão
`404`	Recurso inexistente
`419`	Token CSRF inválido (rotas do painel)
`422`	Parâmetro inválido — o corpo traz `error`
`429`	Limite de requisições
`503`	Recurso indisponível (ex.: IA não configurada)