API Fraikit

Mise à jour le 15 octobre 2026.

L'API relie Fraikit à votre logiciel de paie, votre ERP ou vos tableaux de bord : lire les dépenses et leurs justificatifs, déposer une facture pour un salarié, inviter des personnes, récupérer les écritures comptables d'un mois et être prévenu dès qu'une dépense est validée, refusée ou remboursée.

• Adresse de base : https://fraikit.fr/api/v1
• Spécification OpenAPI 3.1 : https://fraikit.fr/api/v1/openapi.json (à importer dans Postman, Insomnia ou un générateur de client)
• Format : JSON en UTF-8, montants en centimes d'euro (entiers), taux de TVA en points de base (20 % = 2000), dates au format AAAA-MM-JJ

Authentification

Un administrateur crée un jeton dans Paramètres > Développeurs : nom, autorisations, date d'expiration. Le jeton (fk_live_…) n'est affiché qu'une fois ; Fraikit n'en garde qu'une empreinte. Il donne accès à toutes les sociétés du compte, dans la limite des autorisations cochées, et se révoque en un clic. La date de dernière utilisation est visible à côté de chaque jeton.

curl https://fraikit.fr/api/v1/companies \
  -H "Authorization: Bearer fk_live_VOTRE_JETON"

• expenses:read : lire les dépenses, justificatifs, copies fiables, la liste des webhooks et leur journal
• expenses:write : déposer des justificatifs pour une personne, ajouter et supprimer des webhooks
• people:read et people:write : lire la liste des personnes, inviter
• exports:read : lire les écritures comptables
• clients:read et clients:write : lire et créer les clients (refacturation) et leurs projets

Les écritures (dépôt, invitation, création de client) sont faites au nom de l'administrateur qui a créé le jeton et figurent dans l'onglet Historique, avec le nom du jeton. Les sessions de l'appli et les jetons d'API sont distincts : un jeton n'ouvre pas l'appli, une session n'ouvre pas l'API.

Règles communes

• Les brouillons (dépenses pas encore envoyées par la personne) ne sont jamais renvoyés.
• Limite : 120 requêtes par minute et par jeton ; au-delà, réponse 429 : réessayez une minute plus tard.
• Erreurs : statut HTTP et corps {"error": "message", "code": "…"}. 401 jeton invalide, expiré ou révoqué ; 403 autorisation absente ; 404 introuvable (y compris pour les données d'un autre compte).
• Pagination par curseur : chaque page renvoie nextCursor, à repasser dans cursor jusqu'à obtenir null.

Dépenses et justificatifs

curl "https://fraikit.fr/api/v1/expenses?status=approved&from=2026-10-01&to=2026-10-31&limit=100" \
  -H "Authorization: Bearer $FRAIKIT_TOKEN"

{
  "data": [{
    "id": "8f0c…", "companyId": "1d2e…", "status": "approved", "kind": "receipt",
    "date": "2026-10-13", "category": "restaurant", "merchant": "Brasserie du Parc",
    "currency": "EUR", "totalTtc": 4230, "recoverableVat": 375, "paymentMethod": "personal",
    "hasReceipt": true, "einvoice": null, "pieceRef": null,
    "user": { "id": "5a7b…", "name": "Léa R.", "email": "lea@exemple.fr" }
  }],
  "nextCursor": "WyIyMDI2LTEwLTEzIiwiOGYwYyJd"
}

curl -OJ https://fraikit.fr/api/v1/expenses/8f0c…/receipt -H "Authorization: Bearer $FRAIKIT_TOKEN"

curl https://fraikit.fr/api/v1/expenses/receipts \
  -H "Authorization: Bearer $FRAIKIT_TOKEN" \
  -F companyId=1d2e… -F email=lea@exemple.fr \
  -F file=@facture-hotel.pdf

Personnes et clients

curl https://fraikit.fr/api/v1/invitations \
  -H "Authorization: Bearer $FRAIKIT_TOKEN" -H "Content-Type: application/json" \
  -d '{"companyId":"1d2e…","email":"nouveau@exemple.fr","name":"Nouvel Arrivant","role":"employee"}'

curl https://fraikit.fr/api/v1/clients -H "Authorization: Bearer $FRAIKIT_TOKEN" -H "Content-Type: application/json" \
  -d '{"companyId":"1d2e…","name":"Client Dupont","rebillMarkupPct":10}'

Écritures comptables

curl -o ecritures-2026-10.txt \
  "https://fraikit.fr/api/v1/accounting/entries?companyId=1d2e…&month=2026-10&format=fec" \
  -H "Authorization: Bearer $FRAIKIT_TOKEN"

Webhooks

Ajoutez une adresse https dans Paramètres > Développeurs (ou par POST /webhooks) et choisissez les événements :expense.approved, expense.rejected, expense.reimbursed. Un événement est envoyé par dépense.

POST https://erp.exemple.fr/fraikit
Content-Type: application/json
Fraikit-Event: expense.approved
Fraikit-Delivery: 3c1e…
Fraikit-Signature: t=1792065600,v1=5f2b9c…

{"id":"a41d…","type":"expense.approved","createdAt":"2026-10-15T09:20:00.000Z",
 "data":{"expense":{"id":"8f0c…","status":"approved","totalTtc":4230, …}}}

Vérifiez la signature avec le secret whsec_… affiché à la création de l'adresse : HMAC-SHA256 de <t>.<corps brut>, comparé en temps constant. Refusez les horodatages de plus de 5 minutes et dédoublonnez sur id.

import { createHmac, timingSafeEqual } from "node:crypto";

function fraikitSignatureOk(rawBody, header, secret) {
  const t = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(header)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Répondez par un statut 2xx en moins de 10 secondes. Sinon, Fraikit réessaie après 1 min, 5 min, 30 min, 2 h, 6 h et 24 h, puis abandonne. Le journal des livraisons (Paramètres > Développeurs, ou GET /webhooks/{id}/deliveries) montre chaque essai et permet de relancer un envoi.

Factures électroniques

Depuis septembre 2026, les factures fournisseurs arrivent en format électronique (Factur-X, UBL, CII). Déposé comme justificatif (appli, site, e-mail ou API), un tel fichier remplit la dépense à partir de ses données structurées : fournisseur, SIREN et TVA intracommunautaire, numéro, date, TVA par taux et total. La dépense est marquée « facture électronique » (champ einvoice) et l'original est conservé tel quel.

Questions

Écrivez à contact@fraikit.fr. Les évolutions incompatibles feront l'objet d'une nouvelle version (/v2) ; la version 1 restera disponible au moins 12 mois après.