# OmniAPI Dashboard — API Reference

## Opis / Description

**OmniAPI Dashboard** to ujednolicona BI + data API do analityki floty kurierskiej
i rekrutacji wielodostawczej (Glovo/Arara recruitment funnel + Wolt courier fleet).

Serwis udostępnia:
- **SQLite read-model** utrzymywany świeży przez zadania headless sync, eksponowany
  jako sub-sekundowe endpointy REST.
- **Natural-language BI layer** — zadawanie pytań o dane rekrutacyjne w języku
  naturalnym (polskim lub angielskim).
- **OpenAI-compatible chat endpoint** — kompatybilny z klientami OpenAI.

---

## Authentication / Uwierzytelnianie

| Typ endpointu | Nagłówek | Przykład |
|---|---|---|
| Dane i BI (`/v1/health`, `/v1/leads/*`, `/v1/analytics/*`, `/v1/wolt/*`, `/v1/bi/*`) | `X-API-Key` | `X-API-Key: <your-key>` |
| OpenAI-compatible (`/v1/chat/completions`) | `X-API-Key` **lub** `Authorization: Bearer` | `Authorization: Bearer <your-key>` |
| Admin (`/v1/admin/*`) | `X-Admin-Key` | `X-Admin-Key: <admin-key>` |

Wszystkie endpointy (poza root `/`) wymagają odpowiedniego klucza.
Klucze API mają zakresy (`scopes`): `read` (odczyt) i `write` (zapis/akcje).

---

## Health

### `GET /v1/health`

Health check + status tokena Arara.

**Auth:** `X-API-Key`

**Response:** `HealthResponse` — `ok`, `version`, `arara_token_expires_in_sec`,
`tokens_valid_until`, `cf_authorization_present`, `workflows`, itp.

```bash
curl https://arara-api.s1.apppartner.pl/v1/health \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/workflows`

Lista skonfigurowanych workflow (rekrutacja).

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/workflows \
  -H ''X-API-Key: <your-key>''
```

---

## Recruitment Analytics (Glovo) / Analityka Rekrutacji

### `GET /v1/analytics/overview`

Jedno wywołanie zwracające pełny payload dashboardu: lejek, zatrudnieni,
zatrudnieni per dni, czas przebywania, insights, status sync.

**Auth:** `X-API-Key`

**Query params:** `workflow?` (opcjonalny klucz workflow)

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/overview \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/funnel`

Liczby w lejku (T0..T5 + HIRED/FAILED).

**Auth:** `X-API-Key`

**Query params:** `workflow?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/funnel \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/hired`

Liczby HIRED: today/yesterday/7d/30d/total lub własny zakres dat.

**Auth:** `X-API-Key`

**Query params:** `workflow?`, `since?` (YYYY-MM-DD), `until?` (YYYY-MM-DD)

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/hired \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/hired-by-day`

HIRED per dzień (od początku lub okno N dni).

**Auth:** `X-API-Key`

**Query params:** `workflow?`, `days_back?` (1–3650)

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/hired-by-day?days_back=30 \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/leads`

Paginowana lista leadów (kto na którym etapie).

**Auth:** `X-API-Key`

**Query params:** `stage?`, `workflow?`, `city?`, `q?`, `hide_not_interested?`,
`limit` (domyślnie 50), `offset` (domyślnie 0)

```bash
curl "https://arara-api.s1.apppartner.pl/v1/analytics/leads?stage=HIRED&limit=10" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/insights`

Wąskie gardła, trendy, potencjał + bullet insights.

**Auth:** `X-API-Key`

**Query params:** `workflow?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/insights \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/sync`

Status sync: ostatni sync, przejścia, historia.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/sync \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/snapshot`

Liczby leadów (DB-backed, <1s).

**Auth:** `X-API-Key`

**Query params:** `workflow?`, `stage?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/snapshot \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/inflow`

Nowe leady per dzień (event-driven).

**Auth:** `X-API-Key`

**Query params:** `window_days` (domyślnie 30), `workflow?`, `city?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/inflow?window_days=14 \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/conversion`

Konwersja kohort do HIRED.

**Auth:** `X-API-Key`

**Query params:** `window_days` (domyślnie 30), `city?`, `workflow?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/conversion?window_days=30 \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/dwell`

Średni czas przebywanie na etapie (godziny).

**Auth:** `X-API-Key`

**Query params:** `workflow?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/dwell \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/analytics/lead/{lead_id}/timeline`

Timeline etapów dla pojedynczego leada.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/analytics/lead/UUID-HERE/timeline \
  -H ''X-API-Key: <your-key>''
```

---

## Lead Listing / Lista Leadow

### `GET /v1/leads/t4`

Lista dostępnych leadów T4.

**Auth:** `X-API-Key`

**Query params:** `workflow` (wymagany), `city?`, `limit?`

```bash
curl "https://arara-api.s1.apppartner.pl/v1/leads/t4?workflow=3pl_already_assigned" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/leads/by-stage`

Leady na dowolnym etapie.

**Auth:** `X-API-Key`

**Query params:** `workflow`, `stage` (T0..T5/HIRED/FAILED), `state?`, `city?`, `limit?`

```bash
curl "https://arara-api.s1.apppartner.pl/v1/leads/by-stage?workflow=3pl_already_assigned&stage=T3" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/leads/sync-snapshot`

Zgrupowany snapshot workflow×stage do synchronizacji zewnętrznej.

**Auth:** `X-API-Key`

**Query params:** `workflow?`, `stages?`, `include_archived?`, `state?`, `city?`,
`since?`, `until?`, `per_stage_limit?` (domyślnie 500)

```bash
curl "https://arara-api.s1.apppartner.pl/v1/leads/sync-snapshot?per_stage_limit=100" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/leads/search`

Szukaj leadów po emailu/telefonie/imieniu.

**Auth:** `X-API-Key`

**Query params:** `q` (wymagany, min 2 znaki), `workflow?`, `limit?` (domyślnie 50)

```bash
curl "https://arara-api.s1.apppartner.pl/v1/leads/search?q=jan" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/leads/id/{applicant_id}`

Szczegóły leada (etapy, labele, spotkania).

**Auth:** `X-API-Key`

**Query params:** `workflow?`

```bash
curl "https://arara-api.s1.apppartner.pl/v1/leads/id/UUID-HERE" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/leads/stats`

Statystyki T4 per workflow i miasto.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/leads/stats \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/stats/funnel`

Pełne liczby lejka per etap per workflow.

**Auth:** `X-API-Key`

**Query params:** `max_age_days?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/stats/funnel \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/reports/leads`

Zagregowany raport leadów per aktualny etap w zakresie dat.

**Auth:** `X-API-Key`

**Query params:** `since` (domyślnie 2026-01-01), `until?`, `workflow?`, `city?`,
`stages?`, `state?` (domyślnie "available"), `include_leads?` (domyślnie true)

```bash
curl "https://arara-api.s1.apppartner.pl/v1/reports/leads?since=2026-06-01&until=2026-06-22" \
  -H ''X-API-Key: <your-key>''
```

---

## Labels / Etykiety

### `GET /v1/labels/policy`

Polityka wymaganych etykiet per stage + skonfigurowane UUID.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/labels/policy \
  -H ''X-API-Key: <your-key>''
```

---

## Wolt Fleet / Flota Wolt

### `GET /v1/wolt/overview`

KPI floty Wolt: kurierzy, dostawy, średnie TAR/TCR/DPH.

**Auth:** `X-API-Key`

**Query params:** `since?` (YYYY-MM-DD), `until?` (YYYY-MM-DD)

```bash
curl https://arara-api.s1.apppartner.pl/v1/wolt/overview \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/couriers`

Wydajność per kurier (dostawy, godziny online, TAR, TCR, DPH, zarobki).

**Auth:** `X-API-Key`

**Query params:** `active_only?`, `q?`, `since?`, `until?`, `limit?` (domyślnie 100), `offset?`

```bash
curl "https://arara-api.s1.apppartner.pl/v1/wolt/couriers?active_only=true&limit=20" \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/couriers/{courier_id}`

Szczegóły pojedynczego kuriera + trend per dzień.

**Auth:** `X-API-Key`

**Query params:** `since?`, `until?`

```bash
curl https://arara-api.s1.apppartner.pl/v1/wolt/couriers/12345 \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/onboarding/funnel`

Lejek onboardingowy (Waiting/Error/Draft/Blocked).

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/wolt/onboarding/funnel \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/onboarding/errors`

Błędy onboardingowe pogrupowane przyczyną + sugestia naprawy.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/wolt/onboarding/errors \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/onboarding/waiting-per-city`

Leady czekające na aktywację, pogrupowane per miasto.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/wolt/onboarding/waiting-per-city \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/wolt/onboarding`

Rejestracje (tabela + Monday push).

**Auth:** `X-API-Key`

**Query params:** `status_label?`, `city?`, `limit?` (domyślnie 100), `offset?`

```bash
curl "https://arara-api.s1.apppartner.pl/v1/wolt/onboarding?limit=50" \
  -H ''X-API-Key: <your-key>''
```

---

## BI / Natural-language / BI w języku naturalnym

### `POST /v1/bi/query`

Zadaj pytanie analityczne w języku naturalnym.

**Auth:** `X-API-Key`

**Body:**
```json
{
  "question": "Jaka konwersja w Warszawie w 30 dni?"
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/bi/query \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"question": "Ile leadów na każdym etapie?"}''
```

### `GET /v1/bi/metrics`

Lista metryk, które BI assistant potrafi obsłużyć.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/bi/metrics \
  -H ''X-API-Key: <your-key>''
```

### `GET /v1/bi/suggestions`

Sugerowane tematy rozmowy z BI assistantem.

**Auth:** `X-API-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/bi/suggestions \
  -H ''X-API-Key: <your-key>''
```

---

## OpenAI-compatible / Kompatybilność z OpenAI

### `POST /v1/chat/completions`

OpenAI Chat Completions API — zadawaj pytania o dane floty/rekrutacji
w języku naturalnym przez dowolnego klienta OpenAI.

**Auth:** `X-API-Key` **lub** `Authorization: Bearer <your-key>`

**Body:**
```json
{
  "model": "omniapi-bi",
  "messages": [
    {"role": "user", "content": "Ilu kurierów online?"}
  ],
  "stream": false,
  "temperature": 0.7
}
```

**Response:**
```json
{
  "id": "chatcmpl-abc123...",
  "object": "chat.completion",
  "created": 1719000000,
  "model": "omniapi-bi",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}
```

**Przykład z X-API-Key:**
```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/chat/completions \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"model":"omniapi-bi","messages":[{"role":"user","content":"ile leadów w Warszawie?"}]}''
```

**Przykład z Bearer token:**
```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/chat/completions \
  -H ''Authorization: Bearer <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"model":"omniapi-bi","messages":[{"role":"user","content":"ile leadów w Warszawie?"}]}''
```

---

## Actions / Akcje

Wymagają klucza API ze scope `write`.

### `POST /v1/leads/push`

Przenieś pojedynczego kandydata do HIRED (z T3 lub T4).

**Auth:** `X-API-Key` (scope: write)

**Body:**
```json
{
  "workflow": "3pl_already_assigned",
  "applicant_id": "UUID-HERE",
  "from_stage": "T4"
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/leads/push \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"workflow":"3pl_already_assigned","applicant_id":"UUID","from_stage":"T4"}''
```

### `POST /v1/leads/push-batch`

Przenieś batch leadów T3/T4 do HIRED.

**Auth:** `X-API-Key` (scope: write)

**Body:**
```json
{
  "workflow": "3pl_already_assigned",
  "city": null,
  "limit": 50,
  "dry_run": false,
  "from_stage": "T4"
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/leads/push-batch \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"workflow":"3pl_already_assigned","limit":10,"dry_run":true,"from_stage":"T4"}''
```

### `POST /v1/labels/ensure`

Zastosuj wymagane etykiety dla danego etapu na batch kandydatów.

**Auth:** `X-API-Key` (scope: write)

**Body:**
```json
{
  "applicant_ids": ["UUID-1", "UUID-2"],
  "stage": "T4",
  "dry_run": false
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/labels/ensure \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"applicant_ids":["UUID-1"],"stage":"T4","dry_run":true}''
```

### `POST /v1/labels/ensure/by-stage`

Bulk-label wszystkich leadów na danym etapie (workflow-scoped).

**Auth:** `X-API-Key` (scope: write)

**Query params:** `workflow`, `stage`, `city?`, `limit?`, `dry_run?`

```bash
curl -X POST "https://arara-api.s1.apppartner.pl/v1/labels/ensure/by-stage?workflow=3pl_already_assigned&stage=T4&dry_run=true" \
  -H ''X-API-Key: <your-key>''
```

### `POST /v1/labels/waiting-list`

Zastosuj TYLKO etykietę "waiting list" (odseparowana od push/sweep).

**Auth:** `X-API-Key` (scope: write)

**Body:**
```json
{
  "workflow": "3pl_already_assigned",
  "stages": ["T4"],
  "city": null,
  "applicant_ids": null,
  "dry_run": false
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/labels/waiting-list \
  -H ''X-API-Key: <your-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"workflow":"3pl_already_assigned","stages":["T4"],"dry_run":true}''
```

---

## Admin / Administracja

Wymagają osobnego nagłówka `X-Admin-Key`.

### `GET /v1/admin/config`

Podgląd stanu credentiali.

**Auth:** `X-Admin-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/admin/config \
  -H ''X-Admin-Key: <admin-key>''
```

### `POST /v1/admin/cf-auth`

Aktualizacja CF_Authorization cookie.

**Auth:** `X-Admin-Key`

**Body:**
```json
{
  "cf_authorization": "CF_Authorization-value-here"
}
```

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/cf-auth \
  -H ''X-Admin-Key: <admin-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"cf_authorization":"VALUE"}''
```

### `POST /v1/admin/tokens`

Aktualizacja tokenów Arara (dowolny podzbiór).

**Auth:** `X-Admin-Key`

**Body:** przynajmniej jedno z: `access_token`, `refresh_token`, `cf_authorization`, `api_key`.

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/tokens \
  -H ''X-Admin-Key: <admin-key>'' \
  -H ''Content-Type: application/json'' \
  -d ''{"access_token":"NEW_TOKEN"}''
```

### `POST /v1/admin/refresh`

Wymuszony refresh tokena Arara.

**Auth:** `X-Admin-Key`

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/refresh \
  -H ''X-Admin-Key: <admin-key>''
```

### `POST /v1/admin/sweep`

Wywołanie natychmiastowego sweep (T4+T3→HIRED, labele + push).

**Auth:** `X-Admin-Key`

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/sweep \
  -H ''X-Admin-Key: <admin-key>''
```

### `GET /v1/admin/sweep-status`

Status ostatniego background sweep.

**Auth:** `X-Admin-Key`

```bash
curl https://arara-api.s1.apppartner.pl/v1/admin/sweep-status \
  -H ''X-Admin-Key: <admin-key>''
```

### `POST /v1/admin/backfill`

Pełny snapshot load każdego workflow×stage do DB analitycznej.

**Auth:** `X-Admin-Key`

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/backfill \
  -H ''X-Admin-Key: <admin-key>''
```

### `POST /v1/admin/synthesize-events`

Seed transition logu z aktualnego snapshotu (idempotentne).

**Auth:** `X-Admin-Key`

```bash
curl -X POST https://arara-api.s1.apppartner.pl/v1/admin/synthesize-events \
  -H ''X-Admin-Key: <admin-key>''
```