API
Leggi i dati del tuo team dal tuo codice, via HTTPS, con risposte JSON, e ricevi i suoi eventi come webhook firmati.
Autenticazione
Crea una chiave API nelle impostazioni del tuo team, in Chiavi API, e inviala come bearer token. Una chiave appartiene a un team, ha degli scope, può scadere e può essere revocata in qualsiasi momento. Viene mostrata una sola volta, quindi conservala in un posto sicuro.
curl https://app.farinu.com/api/v1/members \
-H "Authorization: Bearer $API_KEY"Endpoint
GET /api/v1/members- I membri del team. Richiede una chiave con lo scope read.
GET /api/v1/audit-log- Il registro attività del team. Richiede una chiave con lo scope read, con un piano che includa il registro attività.
POST /api/v1/webhooks/:id/test- Invia un evento di prova a uno degli endpoint webhook del team e restituisce l'ID del suo invio. Richiede una chiave con lo scope write, con un piano che includa i webhook.
GET /api/v1/assistant/instructions- Le istruzioni del team per l'assistente, null se non ne ha impostate. Richiede una chiave con lo scope read.
Ogni endpoint, parametro e risposta è descritto nel documento OpenAPI 3.1: openapi.json
Paginazione
Gli elenchi restituiscono una pagina di elementi, dal più vecchio, con il cursore da cui continuare e se ci sono altri elementi in attesa.
limit- Quanti elementi restituire, da 1 a 100. Il valore predefinito è 50.
after- Il cursore successivo di una pagina, per ottenere gli elementi che la seguono. Continua a interrogare con l'ultimo per ricevere i nuovi elementi man mano che arrivano.
{ "data": [ … ], "next": "1767225600000.…", "hasMore": true }Versioni
L'API ha versioni basate sulla data. Invia un header API-Version per fissarne una; senza, ottieni la versione attuale. Ogni risposta indica la sua versione in API-Version, e una versione sconosciuta restituisce un 400.
Le modifiche che potrebbero rompere il tuo codice (rimuovere o rinominare un campo, cambiare un tipo o un errore) escono con una nuova data. Le aggiunte, come nuovi campi, endpoint o eventi, arrivano in ogni versione. Una versione precedente continua a funzionare per almeno 12 mesi dopo l'uscita di una più recente.
curl https://app.farinu.com/api/v1/members \
-H "Authorization: Bearer $API_KEY" \
-H "API-Version: 2026-10-06"Idempotenza
Invia un header Idempotency-Key (fino a 255 caratteri stampabili, come un UUID) con una POST per ripeterla in sicurezza. Per 24 ore la stessa chiave e la stessa richiesta restituiscono di nuovo la prima risposta, con Idempotent-Replayed: true, senza eseguirla due volte; la stessa chiave con una richiesta diversa restituisce un 422, e una inviata mentre la prima è ancora in corso un 409.
curl -X POST https://app.farinu.com/api/v1/webhooks/$ENDPOINT_ID/test \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Webhook
Titolari e amministratori aggiungono endpoint HTTPS nelle impostazioni del team, in Webhook, e scelgono gli eventi da inviare. Ogni evento è una POST di JSON con il suo tipo, l'ora e i dati, firmata secondo Standard Webhooks. Rispondi con un qualsiasi 2xx entro 15 secondi; qualsiasi altra risposta viene ritentata dopo 1, 5, 25, 125 e 625 minuti, e un endpoint i cui invii continuano a fallire viene disattivato e i suoi amministratori ricevono un'email.
POST /your/endpoint
webhook-id: whd_…
webhook-timestamp: 1767225600
webhook-signature: v1,…
{ "type": "member.added", "timestamp": "2026-01-01T00:00:00.000Z", "data": { "orgId": "…", "memberId": "…", "userId": "…", "role": "member" } }Per verificare una richiesta, calcola l'HMAC-SHA256 in base64 di webhook-id, webhook-timestamp e del corpo grezzo uniti da punti, usando come chiave i byte del segreto dopo whsec_ (base64), e confrontalo in tempo costante con il valore dopo v1, in webhook-signature. Rifiuta un timestamp che si discosta di più di 5 minuti, e salta un webhook-id che hai già gestito.
Eventi: member.added, member.removed, subscription.changed, file.uploaded e webhook.test, più quelli del prodotto. Il documento OpenAPI descrive ogni corpo.
Errori
Un errore restituisce il suo codice di stato e un corpo JSON con un codice da controllare e un messaggio da mostrare.
{ "error": { "code": "forbidden", "message": "…" } }400 badRequest- Un parametro della query non è valido.
401 unauthorized- La chiave manca, è sbagliata, è stata revocata o è scaduta.
402 upgradeRequired- Il piano del team non include l'API o questo endpoint.
403 forbidden- La chiave non ha lo scope che serve a questo endpoint.
409 conflict- La risorsa è in uno stato che non lo consente, o una richiesta con la stessa Idempotency-Key è ancora in corso.
422 idempotencyMismatch- La Idempotency-Key è già stata usata per una richiesta diversa.
429 rateLimited- Troppe richieste. Ogni chiave può farne 100 al minuto; attendi i secondi indicati nell'header Retry-After.