API HTTP
Chei API, URL de bază și autentificare pentru API-ul REST Tillor
Ultima actualizare la
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
- Referința API - Fiecare endpoint cu parametri și exemple; încercați cererile direct în browser
- Specificația OpenAPI - Documentația completă a API-ului în format JSON, pentru generare de cod sau import în Postman/Insomnia
Chei API
Creare
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 sub eticheta api-keys pentru căi și scheme de cerere și de răspuns.
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
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
Trimiteți cheia API în antetul x-api-key:
x-api-key: tkn_xxxCheile 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ă
- Implicit: 5000 de cereri la 60 de secunde per cheie
- La depășire:
429 Too Many RequestscuRetry-After - Fiecare răspuns la o cheie API conține anteturi IETF
RateLimit-*:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-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
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
URL de bază și contextul organizației
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/customersAntet necesar pentru endpoint-urile organizației: x-api-key: tkn_xxx. ID-ul organizației se află în cale.
Exemplu: cURL
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)
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 (eticheta integrations) pentru scheme exacte.
Înrudite
- Referința API - Fiecare endpoint, de încercat în browser
- OpenAPI - Specificația API (JSON)
- MCP - Conectați Cursor, Claude, ChatGPT sau Gemini prin OAuth
- Notificări externe - Înregistrați e-mailurile trimise de sistemul dumneavoastră
- Webhook-uri - Primiți evenimente prin HTTP POST
- Webhook de intrare al unei automatizări - Porniți o automatizare cu un POST, fără cheie API
- SSE - Transmiteți evenimente prin Server-Sent Events
- Exemple - Exemple de cod și de payload