API REST v1
Endpoints stables, versionnés, JSON. Pagination cursor-based, erreurs normalisées, request_id traçable.
Webhooks sortants
12 événements, signature HMAC-, retry exponentiel sur 7 tentatives.
Sécurité
Bearer tokens hashés, scopes granulaires, IP allowlist optionnelle, rate limiting strict.
Démarrage rapide
En quatre étapes
- 1
Souscrire au plan Cabinet
L'API publique est disponible à partir du plan Cabinet (4 990 € HT/mois). - 2
Générer une clé API
Depuis l'interface Kearmont, rubrique Intégrations → API Keys. Choisissez les scopes nécessaires et conservez la clé en lieu sûr. - 3
Tester l'authentification
curl https://kearmontpartners.fr/api/v1/me \ -H "Authorization: Bearer kpk_live_xxx"
- 4
Lister vos dossiers
curl https://kearmontpartners.fr/api/v1/dossiers?limit=10 \ -H "Authorization: Bearer kpk_live_xxx"
Référence
Endpoints principaux
/api/v1/health Health check (sans authentification).
/api/v1/me Informations sur l'API key et l'organisation.
/api/v1/dossiers Liste paginée des dossiers.
read:dossiers /api/v1/dossiers Créer un dossier.
write:dossiers /api/v1/dossiers/{id} Détail d'un dossier.
read:dossiers /api/v1/dossiers/{id} Mise à jour partielle.
write:dossiers /api/v1/dossiers/{id} Archivage (soft delete).
write:dossiers /api/v1/dossiers/{id}/rapports Liste des rapports.
read:rapports /api/v1/dossiers/{id}/taches Liste des tâches.
read:taches /api/v1/dossiers/{id}/taches Créer une tâche.
write:taches Référence complète et schémas dans la spécification OpenAPI .
Webhooks
Notifier votre SI en temps réel
Configurez un endpoint HTTPS dans votre interface Kearmont. À chaque événement souscrit, une requête POST signée HMAC- est envoyée à l'URL.
Vérification de signature
import crypto from 'crypto'; function verifyKearmontSignature(payload, signature, secret) { const expected = '=' + crypto.createHmac('', secret).update(payload).digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) );
} // Express handler
app.post('/webhooks/kearmont', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.headers['x-kearmont-signature']; if (!verifyKearmontSignature(req.body, sig, process.env.KEARMONT_WEBHOOK_SECRET)) { return res.status(401).end; } const event = JSON.parse(req.body.toString); console.log('Received', event.type, event.data); res.status(200).end;
}); Stratégie de retry
Sur erreur 5xx ou timeout : retry avec backoff exponentiel (1m, 5m, 30m, 2h, 12h, 24h, 72h). Après 7 tentatives échouées, l'événement est marqué gave_up et un email est envoyé aux administrateurs de l'organisation.
Erreurs
Format normalisé
{ "error": { "code": "invalid_request", "message": "Le champ 'name' est requis.", "request_id": "req_abc123" }
} - 400 invalid_request — 401 unauthorized — 403 forbidden
- 404 not_found — 409 conflict — 429 rate_limit_exceeded — 500 internal_error
Rate limiting
Limites par défaut
- • 60 requêtes / minute
- • 5 000 requêtes / heure
- • 50 000 requêtes / jour
- • 500 webhooks delivery / heure
Headers de réponse : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Cas d'usage
Trois intégrations typiques
Synchroniser vers le CRM
Webhook sur dossier.created. Créer la fiche correspondante dans Salesforce, HubSpot ou outil interne.
Archivage mensuel des rapports
Cron côté client : GET /api/v1/dossiers?status=closed puis téléchargement des PDF.
Pré-remplir un dossier
POST /api/v1/dossiers depuis votre outil métier; l'utilisateur final complète depuis Kearmont.
SDK officiels — bientôt
Un package @kearmont/sdk-node et kearmont-python sont en préparation. En attendant, tous les exemples utilisent curl.