# Prezentarea API-ului

Adresa de bază, autentificarea, formatul cererilor și al răspunsurilor, limitele și regulile comune tuturor rutelor.

## Adresa de bază

```text title="Adresa de bază"
https://app.ilustromania.com/nucleu
```

Rutele produsului au prefixul de versiune `/v1`. Excepțiile (5) sunt descoperirea OAuth (`/.well-known/…`) și verificarea de sănătate (`/sanatate`). Exemplu: `GET https://app.ilustromania.com/nucleu/v1/agentie/creatori`.

## Autentificarea

| Cine apelează | Cum se autentifică |
| --- | --- |
| Aplicația web (browserul) | cookie-ul de sesiune `__Host-sesiune`, pus la intrarea în cont |
| Un script sau un server al firmei | o [cheie API](#chei-api): `Authorization: Bearer ilk_…`, cu rol și expirare; deocamdată doar pe rutele de citire deschise cheilor |
| Un script care are nevoie de alte rute | cookie-ul de sesiune, trimis explicit în antetul `Cookie` |
| Un asistent AI prin MCP | `Authorization: Bearer mcp_…`, obținut prin [OAuth](#oauth) |
| Executorii de pe server | jeton de serviciu, cu rolul `executor` |

```bash title="O cerere cu sesiunea"
curl https://app.ilustromania.com/nucleu/v1/agentie/creatori \
  -H "Cookie: __Host-sesiune=$JETON_SESIUNE"
```

> [!WARNING]
> Jetonul de sesiune dă aceleași drepturi ca și contul tău. Nu îl pune în cod, în commituri sau în mesaje; ține-l într-o variabilă de mediu.

## Firma activă

Cererea lucrează pe firma activă a sesiunii. Când ai mai multe firme deschise în taburi diferite, aplicația trimite firma tabului în antetul `x-firma-tab`. Firma se verifică pe server: nu poți alege o firmă la care nu ai acces.

## Formatul

- Cererile și răspunsurile sunt JSON (`Content-Type: application/json`), în UTF-8.
- Corpul cererilor de scriere este validat cu o schemă. Un câmp lipsă sau de alt tip înseamnă `400`.
- Datele calendaristice sunt `AAAA-LL-ZZ`; momentele sunt ISO 8601 în UTC (`2026-11-11T10:24:05Z`).

## Răspunsurile de eroare

Orice eroare are un corp cu câmpul `eroare`, iar uneori și `motiv` sau alte detalii:

```json title="O eroare"
{ "eroare": "interzis" }
```

Cu antetul `Accept: application/problem+json`, aceeași eroare vine în formatul standard RFC 9457, cu un `cod` stabil. Lista completă a codurilor și formatul nou sunt în [Erori](#api-erori).

## Numărul cererii

Fiecare răspuns are antetul `x-request-id`. Poți trimite tu unul (8–64 de caractere: litere, cifre, `-` sau `_`) și platforma îl păstrează; altfel pune unul nou. Când raportezi o eroare, trimite acest număr.

## Scrierile repetate

Câteva rute care creează documente acceptă antetul `Idempotency-Key`: o scriere trimisă din nou cu aceeași cheie nu se aplică de două ori. Detaliile sunt în [Cereri repetate fără dubluri](#idempotenta).

## Accesul fiecărei rute

Fiecare rută din referință are o etichetă de acces:

| Etichetă | Înseamnă |
| --- | --- |
| `public` | fără autentificare |
| `sesiune` | orice cont intrat; modulul verifică apoi drepturile fine |
| `rol:admin` | doar administratorul firmei active |
| `rol:executor` | doar jetoanele de serviciu ale agenților |
| `intern` | dovadă verificată de modul (canal semnat), nu de sesiune |

## Limitele

Scrierile au o limită comună de 300 pe minut pe sesiune și 1200 pe minut pe IP; citirile, 1200 pe sesiune și 6000 pe IP. Fiecare scriere primește antetele `RateLimit` și `RateLimit-Policy`, cu câte cereri mai ai; peste prag, răspunsul este `429` cu `Retry-After`. Detaliile sunt în [Limite](#limite).

## Specificația OpenAPI

`GET /v1/openapi.json` întoarce specificația OpenAPI a rutelor descrise cu scheme. Ruta cere rolul `admin`. Din aceeași specificație vin, în referința de aici, tabelele de parametri, de corp și de răspuns și exemplele de corp și de răspuns, pe cele 86 de rute care au schemă; celelalte au descrierea și un exemplu de cerere.

## Versiunile

Versiunea curentă este `v1` și este singura. Adăugirile intră în `v1`; o schimbare care rupe ceva apare doar în `v2`, cu cel puțin 6 luni în care merg amândouă. Regula întreagă este în [Versiuni API](#versiuni); schimbările se anunță în [Noutăți](#note-versiune).