HTTP API
Klucze API, base URL i uwierzytelnianie dla REST API Tillor
Ostatnio zaktualizowano
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
- Dokumentacja API - Każdy endpoint z parametrami i przykładami; wypróbuj żądania bezpośrednio w przeglądarce
- Specyfikacja OpenAPI - Pełna dokumentacja API w formacie JSON do generowania kodu lub importu do Postmana/Insomnii
Klucze API
Tworzenie
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 pod tagiem api-keys.
Surowy klucz jest zwracany jednorazowo przy tworzeniu lub ponownym generowaniu. Przechowuj go bezpiecznie; później nie można go już pobrać.
Ograniczanie uprawnień
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
Wysyłaj klucz API w nagłówku x-api-key:
x-api-key: tkn_xxxKlucze 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)
- Domyślnie: 5000 żądań na 60 sekund na klucz
- Po przekroczeniu:
429 Too Many RequestszRetry-After - Każda odpowiedź dla klucza API zawiera nagłówki IETF
RateLimit-*:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-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
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
Base URL i kontekst organizacji
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/customersWymagany nagłówek dla endpointów organizacji: x-api-key: tkn_xxx. Identyfikator organizacji jest w ścieżce.
Przykład: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integracje (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 (tag integrations).
Powiązane
- Dokumentacja API - Każdy endpoint, do wypróbowania w przeglądarce
- OpenAPI - Specyfikacja API (JSON)
- MCP - Połącz Cursor, Claude, ChatGPT lub Gemini przez OAuth
- Powiadomienia zewnętrzne - Rejestruj e-maile wysłane przez Twój własny system
- Webhooki - Odbieraj zdarzenia przez HTTP POST
- Przychodzący webhook automatyzacji - Uruchom automatyzację przez POST, bez klucza API
- SSE - Strumieniuj zdarzenia przez Server-Sent Events
- Przykłady - Przykłady kodu i payloadów