# API HTTP (/ro-RO/ontwikkelaars/http)

API-ul Tillor este un API REST. Autentificați-vă cu o cheie API și trimiteți anteturile corecte la fiecare cerere. Cheile API sunt **pe cont** - o cheie funcționează pentru toate organizațiile la care aveți acces.

## Referința API și OpenAPI [#api-referentie-en-openapi]

- **[Referința API](/api-referentie)** - Fiecare endpoint cu parametri și exemple; încercați cererile direct în browser
- **[Specificația OpenAPI](https://tillor.eu/api/openapi.json)** - Documentația completă a API-ului în format JSON, pentru generare de cod sau import în Postman/Insomnia

---

## Chei API [#api-sleutels]

### Creare [#aanmaken]

Cheile API le creați în aplicația Tillor prin meniul utilizatorului, sub **Cont > Chei API** (marcajul **1** = meniul, marcajul **2** = Chei API în captura de ecran). Le puteți crea și prin API cu o sesiune autentificată (fără cheie API). Vezi [specificația OpenAPI](https://tillor.eu/api/openapi.json) sub eticheta `api-keys` pentru căi și scheme de cerere și de răspuns.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="Chei API în setările contului" />

Cheia brută este returnată **o singură dată** la creare sau regenerare. Păstrați-o în siguranță; după aceea nu o mai puteți prelua.

### Limitarea permisiunilor [#rechten-beperken]

Implicit, o cheie poate tot ce puteți și dumneavoastră, în fiecare organizație din care faceți parte. În fereastra cheii activați **Limitează la permisiunile selectate** și alegeți permisiunile de care are nevoie integrarea, de exemplu doar citirea facturilor. O cheie limitată primește în fiecare organizație intersecția dintre permisiunile ei și calitatea dumneavoastră de membru acolo: o cheie nu poate niciodată mai mult decât dumneavoastră. Un apel în afara permisiunilor alese primește `403 Forbidden`, ca un utilizator fără acea permisiune. O modificare a permisiunilor se aplică în mai puțin de un minut. Prin API: `scopes` (listă de id-uri de permisiuni precum `invoices:read`, sau `null` pentru tot) la crearea și actualizarea unei chei.

### Utilizare [#gebruik]

Trimiteți cheia API în antetul `x-api-key`:

```http
x-api-key: tkn_xxx
```

Cheile folosesc prefixul `tkn_`. La endpoint-urile organizației, ID-ul organizației se află în cale (`/orgs/org_abc123/...`); un antet separat nu este necesar.

### Limite de rată [#rate-limits]

- **Implicit:** 5000 de cereri la 60 de secunde per cheie
- La depășire: `429 Too Many Requests` cu `Retry-After`
- Fiecare răspuns la o cheie API conține anteturi IETF `RateLimit-*`:

```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```

`RateLimit-Reset` este numărul de secunde până când fereastra curentă începe din nou. Clienții din browser pot citi aceste anteturi prin CORS (`Access-Control-Expose-Headers`).

### Securitate [#beveiliging]

<Callout type="warn" title="Atenție">
- **Niciodată** nu expuneți cheile API în cod de pe partea clientului sau în depozite publice
- Regenerați periodic cheile prin **Regenerați** în aplicație (OpenAPI: `POST /api/api-keys/:id/renew`)
- Ștergeți cheile nefolosite cu `DELETE /api/api-keys/:id`
</Callout>

---

## URL de bază și contextul organizației [#base-url-en-organisatie-context]

**URL de bază:** `https://tillor.eu` (sau URL-ul instalării dumneavoastră; OpenAPI menționează `{APP_URL}/api`)

**Căi pentru organizație:** adăugați ID-ul organizației în cale:

```
/api/orgs/:orgId/...
```

**Exemplu:**

```
GET https://tillor.eu/api/orgs/org_abc123/customers
```

**Antet necesar pentru endpoint-urile organizației:** `x-api-key: tkn_xxx`. ID-ul organizației se află în cale.

---

## Exemplu: cURL [#voorbeeld-curl]

```bash
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
  -H "x-api-key: tkn_xxx" \
  -H "Content-Type: application/json"
```

---

## Integrări (marketplace) [#integraties-marketplace]

Integrările organizației (înainte „aplicații” în API) folosesc o singură resursă per tip sub `/api/orgs/:orgId/integrations/{integrationType}`. Permisiunile necesare sunt `organization:integrations:read` și `organization:integrations:write` (înlocuiește `organization:apps:*`).

| Metodă | Cale | Descriere |
|--------|------|-------------|
| GET | `/integrations/{integrationType}` | Status (`installed`, `available`) și `settings` cu date ascunse |
| POST | `/integrations/{integrationType}` | Instalare (opțional `settings` în corp; OAuth poate returna `redirectUrl`) |
| PUT | `/integrations/{integrationType}` | Actualizarea setărilor (`settings` în corp) |
| DELETE | `/integrations/{integrationType}` | Dezinstalare |

La `GET` și după `PUT`, `settings` conține doar câmpurile **publice**, plus `{ configured: true }` pentru fiecare câmp secret. Parolele, cheile API și tokenurile OAuth nu sunt returnate. Lăsați câmpurile secrete goale la `PUT` pentru a păstra valoarea existentă.

Vezi [specificația OpenAPI](https://tillor.eu/api/openapi.json) (eticheta `integrations`) pentru scheme exacte.

---

## Înrudite [#gerelateerd]

- [Referința API](/api-referentie) - Fiecare endpoint, de încercat în browser
- [OpenAPI](https://tillor.eu/api/openapi.json) - Specificația API (JSON)
- [MCP](/ontwikkelaars/mcp) - Conectați Cursor, Claude, ChatGPT sau Gemini prin OAuth
- [Notificări externe](/ontwikkelaars/externe-notificaties) - Înregistrați e-mailurile trimise de sistemul dumneavoastră
- [Webhook-uri](/ontwikkelaars/webhooks) - Primiți evenimente prin HTTP POST
- [Webhook de intrare al unei automatizări](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Porniți o automatizare cu un POST, fără cheie API
- [SSE](/ontwikkelaars/sse) - Transmiteți evenimente prin Server-Sent Events
- [Exemple](/ontwikkelaars/voorbeelden) - Exemple de cod și de payload