# 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`

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

```json
{
  "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`.

```json
{ "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.

```json
{
  "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.

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

```json
{ "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.

```json
{ "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) |