API HTTP
Chiavi API, base URL e autenticazione per la REST API di Tillor
Ultimo aggiornamento il
L'API di Tillor è una REST API. Autenticati con una chiave API e invia gli header giusti a ogni richiesta. Le chiavi API sono per account - una chiave vale per tutte le organizzazioni a cui hai accesso.
Riferimento API e OpenAPI
- Riferimento API - Ogni endpoint con parametri ed esempi; prova le richieste direttamente nel browser
- Specifica OpenAPI - Documentazione completa dell'API in formato JSON per la generazione di codice o l'importazione in Postman/Insomnia
Chiavi API
Creare
Le chiavi API le crei nell'app Tillor dal menu utente in Account > Chiavi API (indicatore 1 = menu, indicatore 2 = Chiavi API nello screenshot). Puoi crearle anche tramite l'API con una sessione effettuata (senza chiave API). Vedi la specifica OpenAPI sotto il tag api-keys per percorsi e schemi di richiesta e risposta.
La chiave in chiaro viene restituita una sola volta alla creazione o alla rigenerazione. Conservala con cura; dopo non potrai più recuperarla.
Limitare i permessi
Per impostazione predefinita una chiave può fare tutto ciò che puoi fare tu, in ogni organizzazione di cui sei membro. Nella finestra della chiave attiva Limita alle autorizzazioni selezionate e scegli i permessi di cui il collegamento ha bisogno, ad esempio solo la lettura delle fatture. Una chiave limitata ottiene in ogni organizzazione l'intersezione dei suoi permessi e della tua appartenenza lì: una chiave non può mai fare più di te. Una chiamata al di fuori dei permessi scelti riceve 403 Forbidden, proprio come un utente senza quel permesso. Una modifica dei permessi vale entro un minuto. Tramite l'API: scopes (elenco di id di permessi come invoices:read, oppure null per tutto) alla creazione e all'aggiornamento di una chiave.
Utilizzo
Invia la chiave API nell'header x-api-key:
x-api-key: tkn_xxxLe chiavi usano il prefisso tkn_. Negli endpoint dell'organizzazione l'ID dell'organizzazione è nel percorso (/orgs/org_abc123/...); non serve un header a parte.
Rate limit
- Predefinito: 5000 richieste ogni 60 secondi per chiave
- In caso di superamento:
429 Too Many RequestsconRetry-After - Ogni risposta con chiave API contiene gli header IETF
RateLimit-*:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset è il numero di secondi prima che la finestra attuale ricominci. I client browser possono leggere questi header tramite CORS (Access-Control-Expose-Headers).
Sicurezza
Attenzione
- Mai esporre le chiavi API nel codice lato client o in repository pubblici
- Rigenera periodicamente le chiavi con Rigenera nell'app (OpenAPI:
POST /api/api-keys/:id/renew) - Elimina le chiavi inutilizzate con
DELETE /api/api-keys/:id
Base URL e contesto dell'organizzazione
Base URL: https://tillor.eu (o l'URL del tuo deployment; OpenAPI indica {APP_URL}/api)
Percorsi dell'organizzazione: aggiungi l'ID dell'organizzazione nel percorso:
/api/orgs/:orgId/...Esempio:
GET https://tillor.eu/api/orgs/org_abc123/customersHeader richiesto per gli endpoint dell'organizzazione: x-api-key: tkn_xxx. L'ID dell'organizzazione è nel percorso.
Esempio: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integrazioni (marketplace)
Le integrazioni dell'organizzazione (prima "apps" nell'API) usano una risorsa per tipo sotto /api/orgs/:orgId/integrations/{integrationType}. I permessi richiesti sono organization:integrations:read e organization:integrations:write (sostituisce organization:apps:*).
| Method | Percorso | Descrizione |
|---|---|---|
| GET | /integrations/{integrationType} | Stato (installed, available) e settings oscurate |
| POST | /integrations/{integrationType} | Installare (settings facoltative nel body; OAuth può restituire redirectUrl) |
| PUT | /integrations/{integrationType} | Aggiornare le impostazioni (settings nel body) |
| DELETE | /integrations/{integrationType} | Disinstallare |
Con GET e dopo PUT, settings contiene solo campi pubblici più, per ogni campo segreto, { configured: true }. Password, chiavi API e token OAuth non vengono restituiti. Lascia vuoti i campi segreti con PUT per mantenere il valore esistente.
Vedi la specifica OpenAPI (tag integrations) per gli schemi esatti.
Correlati
- Riferimento API - Ogni endpoint, da provare nel browser
- OpenAPI - Specifica API (JSON)
- MCP - Collegare Cursor, Claude, ChatGPT o Gemini tramite OAuth
- Notifiche esterne - Registra le e-mail inviate dal tuo sistema
- Webhook - Ricevi eventi tramite HTTP POST
- Webhook in ingresso di un'automazione - Avvia un'automazione con una POST, senza chiave API
- SSE - Ricevi eventi in streaming con Server-Sent Events
- Esempi - Esempi di codice e di payload