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-SHA256, 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/healthHealth check (sans authentification).
/api/v1/meInformations sur l'API key et l'organisation.
/api/v1/dossiersListe paginée des dossiers.
read:dossiers/api/v1/dossiersCré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}/rapportsListe des rapports.
read:rapports/api/v1/dossiers/{id}/tachesListe des tâches.
read:taches/api/v1/dossiers/{id}/tachesCréer une tâche.
write:tachesRé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-SHA256 est envoyée à l'URL.
Vérification de signature
import crypto from 'crypto';
function verifyKearmontSignature(payload, signature, secret) {
const expected = 'sha256=' + crypto.createHmac('sha256', 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.