# HTTP API (/pl-PL/ontwikkelaars/http)

API Tillor to REST API. Uwierzytelniaj się kluczem API i wysyłaj odpowiednie nagłówki przy każdym żądaniu. Klucze API są przypisane **do konta** - jeden klucz działa dla wszystkich organizacji, do których masz dostęp.

## Dokumentacja API i OpenAPI [#api-referentie-en-openapi]

- **[Dokumentacja API](/api-referentie)** - Każdy endpoint z parametrami i przykładami; wypróbuj żądania bezpośrednio w przeglądarce
- **[Specyfikacja OpenAPI](https://tillor.eu/api/openapi.json)** - Pełna dokumentacja API w formacie JSON do generowania kodu lub importu do Postmana/Insomnii

---

## Klucze API [#api-sleutels]

### Tworzenie [#aanmaken]

Klucze API tworzysz w aplikacji Tillor w menu użytkownika w sekcji **Konto > Klucze API** (znacznik **1** = menu, znacznik **2** = Klucze API na zrzucie ekranu). Możesz je też utworzyć przez API z zalogowaną sesją (bez klucza API). Ścieżki oraz schematy żądań i odpowiedzi znajdziesz w [specyfikacji OpenAPI](https://tillor.eu/api/openapi.json) pod tagiem `api-keys`.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="Klucze API w ustawieniach konta" />

Surowy klucz jest zwracany **jednorazowo** przy tworzeniu lub ponownym generowaniu. Przechowuj go bezpiecznie; później nie można go już pobrać.

### Ograniczanie uprawnień [#rechten-beperken]

Domyślnie klucz może wszystko, co możesz Ty sam, w każdej organizacji, do której należysz. W oknie klucza włącz **Ogranicz do wybranych uprawnień** i wybierz uprawnienia potrzebne integracji, na przykład tylko odczyt faktur. Ograniczony klucz otrzymuje w każdej organizacji część wspólną swoich uprawnień i Twojego członkostwa w niej: klucz nigdy nie może więcej niż Ty. Wywołanie poza wybranymi uprawnieniami zwraca `403 Forbidden`, tak samo jak dla użytkownika bez tego uprawnienia. Zmiana uprawnień obowiązuje w ciągu minuty. Przez API: `scopes` (lista identyfikatorów uprawnień, takich jak `invoices:read`, albo `null` dla wszystkich) przy tworzeniu i aktualizacji klucza.

### Użycie [#gebruik]

Wysyłaj klucz API w nagłówku `x-api-key`:

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

Klucze mają prefiks `tkn_`. W endpointach organizacji identyfikator organizacji jest w ścieżce (`/orgs/org_abc123/...`); osobny nagłówek nie jest potrzebny.

### Limity żądań (rate limits) [#rate-limits]

- **Domyślnie:** 5000 żądań na 60 sekund na klucz
- Po przekroczeniu: `429 Too Many Requests` z `Retry-After`
- Każda odpowiedź dla klucza API zawiera nagłówki IETF `RateLimit-*`:

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

`RateLimit-Reset` to liczba sekund do rozpoczęcia nowego okna. Klienci w przeglądarce mogą odczytać te nagłówki przez CORS (`Access-Control-Expose-Headers`).

### Bezpieczeństwo [#beveiliging]

<Callout type="warn" title="Uwaga">
- **Nigdy** nie ujawniaj kluczy API w kodzie po stronie klienta ani w publicznych repozytoriach
- Regularnie generuj klucze ponownie przez **Wygeneruj ponownie** w aplikacji (OpenAPI: `POST /api/api-keys/:id/renew`)
- Usuwaj nieużywane klucze przez `DELETE /api/api-keys/:id`
</Callout>

---

## Base URL i kontekst organizacji [#base-url-en-organisatie-context]

**Base URL:** `https://tillor.eu` (lub adres URL Twojego wdrożenia; OpenAPI podaje `{APP_URL}/api`)

**Ścieżki organizacji:** dodaj identyfikator organizacji do ścieżki:

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

**Przykład:**

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

**Wymagany nagłówek dla endpointów organizacji:** `x-api-key: tkn_xxx`. Identyfikator organizacji jest w ścieżce.

---

## Przykład: 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"
```

---

## Integracje (marketplace) [#integraties-marketplace]

Integracje organizacji (dawniej „apps” w API) używają jednego zasobu na typ pod `/api/orgs/:orgId/integrations/{integrationType}`. Wymagane uprawnienia to `organization:integrations:read` i `organization:integrations:write` (zastępują `organization:apps:*`).

| Method | Pad | Beschrijving |
|--------|------|-------------|
| GET | `/integrations/{integrationType}` | Status (`installed`, `available`) i zredagowane `settings` |
| POST | `/integrations/{integrationType}` | Instalacja (opcjonalnie `settings` w body; OAuth może zwrócić `redirectUrl`) |
| PUT | `/integrations/{integrationType}` | Aktualizacja ustawień (`settings` w body) |
| DELETE | `/integrations/{integrationType}` | Odinstalowanie |

Przy `GET` i po `PUT` pole `settings` zawiera tylko pola **publiczne** oraz dla każdego pola tajnego `{ configured: true }`. Hasła, klucze API i tokeny OAuth nie są zwracane. Zostaw pola tajne puste przy `PUT`, aby zachować istniejącą wartość.

Dokładne schematy znajdziesz w [specyfikacji OpenAPI](https://tillor.eu/api/openapi.json) (tag `integrations`).

---

## Powiązane [#gerelateerd]

- [Dokumentacja API](/api-referentie) - Każdy endpoint, do wypróbowania w przeglądarce
- [OpenAPI](https://tillor.eu/api/openapi.json) - Specyfikacja API (JSON)
- [MCP](/ontwikkelaars/mcp) - Połącz Cursor, Claude, ChatGPT lub Gemini przez OAuth
- [Powiadomienia zewnętrzne](/ontwikkelaars/externe-notificaties) - Rejestruj e-maile wysłane przez Twój własny system
- [Webhooki](/ontwikkelaars/webhooks) - Odbieraj zdarzenia przez HTTP POST
- [Przychodzący webhook automatyzacji](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Uruchom automatyzację przez POST, bez klucza API
- [SSE](/ontwikkelaars/sse) - Strumieniuj zdarzenia przez Server-Sent Events
- [Przykłady](/ontwikkelaars/voorbeelden) - Przykłady kodu i payloadów