API

Lisez les données de votre équipe depuis votre propre code, en HTTPS, avec des réponses JSON, et recevez ses événements sous forme de webhooks signés.

Authentification

Créez une clé API dans les paramètres de votre équipe, sous Clés API, et envoyez-la comme jeton bearer. Une clé appartient à une seule équipe, a des niveaux d'accès, peut expirer et peut être révoquée à tout moment. Elle n'est affichée qu'une fois : conservez-la en lieu sûr.

curl https://app.farinu.com/api/v1/members \
  -H "Authorization: Bearer $API_KEY"

Points de terminaison

GET /api/v1/members: Les membres de l'équipe. Nécessite une clé avec l'accès read.
GET /api/v1/audit-log: Le journal d'audit de l'équipe. Nécessite une clé avec l'accès read, avec une offre qui inclut le journal d'audit.
POST /api/v1/webhooks/:id/test: Envoie un événement de test à l'un des points de terminaison webhook de l'équipe et renvoie l'ID de sa livraison. Nécessite une clé avec l'accès write, avec une offre qui inclut les webhooks.
GET /api/v1/assistant/instructions: Les instructions de l'équipe à l'assistant, null si elle n'en a défini aucune. Nécessite une clé avec l'accès read.

Chaque point de terminaison, paramètre et réponse est décrit dans le document OpenAPI 3.1 : openapi.json

Pagination

Les listes renvoient une page d'éléments, du plus ancien au plus récent, avec le curseur à partir duquel continuer et l'indication d'éléments supplémentaires en attente.

limit: Le nombre d'éléments à renvoyer, de 1 à 100. La valeur par défaut est 50.
after: Le curseur suivant d'une page, pour obtenir les éléments qui la suivent. Continuez d'interroger avec le dernier pour recevoir les nouveaux éléments à mesure qu'ils arrivent.

{ "data": [ … ], "next": "1767225600000.…", "hasMore": true }

Versions

L'API est versionnée par date. Envoyez un en-tête API-Version pour en fixer une ; sans lui, vous obtenez la version actuelle. Chaque réponse indique sa version dans API-Version, et une version inconnue renvoie une erreur 400.

Les changements qui pourraient casser votre code (supprimer ou renommer un champ, changer un type ou une erreur) sont publiés sous une nouvelle date. Les ajouts, comme de nouveaux champs, points de terminaison ou événements, arrivent dans toutes les versions. Une ancienne version continue de fonctionner au moins 12 mois après la publication d'une plus récente.

curl https://app.farinu.com/api/v1/members \
  -H "Authorization: Bearer $API_KEY" \
  -H "API-Version: 2026-10-06"

Idempotence

Envoyez un en-tête Idempotency-Key (jusqu'à 255 caractères imprimables, comme un UUID) avec un POST pour le réessayer sans risque. Pendant 24 heures, la même clé et la même requête renvoient à nouveau la première réponse, avec Idempotent-Replayed: true, sans l'exécuter deux fois ; la même clé avec une requête différente renvoie une erreur 422, et une requête envoyée pendant que la première est encore en cours, une erreur 409.

curl -X POST https://app.farinu.com/api/v1/webhooks/$ENDPOINT_ID/test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Webhooks

Les propriétaires et les administrateurs ajoutent des points de terminaison HTTPS dans les paramètres de l'équipe, sous Webhooks, et choisissent les événements à envoyer. Chaque événement est un POST de JSON avec son type, son heure et ses données, signé selon Standard Webhooks. Répondez par n'importe quel code 2xx sous 15 secondes ; sinon, l'envoi est réessayé après 1, 5, 25, 125 et 625 minutes, et un point de terminaison dont les livraisons échouent sans cesse est désactivé et ses administrateurs prévenus par e-mail.

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" } }

Pour vérifier une requête, calculez le HMAC-SHA256 en base64 de webhook-id, webhook-timestamp et du corps brut joints par des points, avec pour clé les octets du secret après whsec_ (base64), et comparez-le en temps constant avec la valeur après v1, dans webhook-signature. Refusez un horodatage décalé de plus de 5 minutes, et ignorez un webhook-id que vous avez déjà traité.

Événements : member.added, member.removed, subscription.changed, file.uploaded et webhook.test, plus ceux du produit. Le document OpenAPI décrit chaque corps.

Erreurs

Une erreur renvoie son code de statut et un corps JSON avec un code à vérifier et un message à afficher.

{ "error": { "code": "forbidden", "message": "…" } }

400 badRequest: Un paramètre de requête n'est pas valide.
401 unauthorized: La clé est manquante, erronée, révoquée ou expirée.
402 upgradeRequired: L'offre de l'équipe n'inclut pas l'API ou ce point de terminaison.
403 forbidden: La clé n'a pas le niveau d'accès requis par ce point de terminaison.
409 conflict: La ressource est dans un état qui ne permet pas cette action, ou une requête avec la même Idempotency-Key est encore en cours.
422 idempotencyMismatch: L'Idempotency-Key a déjà été utilisée pour une requête différente.
429 rateLimited: Trop de requêtes. Chaque clé peut en faire 100 par minute ; attendez le nombre de secondes indiqué dans l'en-tête Retry-After.