API et webhooks

Avec API et webhooks, vos propres systèmes (ERP, entrepôt de données, backend de site web, outils d'automatisation) travaillent avec votre workspace NextCRM :

• l'API REST lit et modifie les leads, contacts, tâches et notes, et lit les entonnoirs, les envois de formulaires, les campagnes et les membres de l'équipe ;
• les webhooks préviennent votre serveur dès qu'un événement se produit, par exemple un nouveau lead ou un changement d'étape.

Remarque : Seuls les Admins du workspace peuvent ouvrir Paramètres > API et webhooks. L'accès à l'API est inclus dans les forfaits Business, Agency et Enterprise. Avec les autres forfaits, les clés et endpoints existants restent visibles, mais vous ne pouvez pas en créer de nouveaux et les appels à l'API sont refusés.

Où trouver chaque valeur

Tout provient de NextCRM lui-même ; aucun compte tiers n'est nécessaire.

Valeur	Où la trouver
Clé API	Paramètres > API et webhooks > Créer une clé API. La clé complète n'est affichée qu'une seule fois ; copiez-la dans votre intégration (par exemple n8n, Zapier, Make ou votre propre code) comme jeton Bearer.
Secret de signature	Affiché une fois lorsque vous ajoutez un endpoint de webhook, puis à nouveau après Renouveler le secret. Conservez-le sur le serveur qui reçoit les webhooks.
URL de l'endpoint	Provient de votre propre système ou outil d'automatisation, par exemple l'URL de production d'un nœud Webhook n8n. Elle doit utiliser https.

Ordre de configuration : créer une clé API avec les autorisations nécessaires > faire un premier appel > ajouter un endpoint de webhook avec ses événements > vérifier la signature sur votre serveur > envoyer un événement de test.

Créer une clé API

1. Cliquez sur votre carte de profil en bas de la barre latérale, choisissez Paramètres, ouvrez la carte API et webhooks (ouvrir API et webhooks) et restez sur l'onglet Clés API.
2. Cliquez sur Créer une clé API.
3. Saisissez un Nom qui indique où la clé est utilisée, par exemple « Synchronisation ERP ».
4. Sous Autorisations, choisissez Lecture et/ou Écriture par domaine. Ne choisissez que ce dont l'intégration a réellement besoin.
5. Si vous le souhaitez, définissez une expiration sous Expiration (30, 90 ou 365 jours, ou une date).
6. Cliquez sur Créer la clé et copiez-la immédiatement avec Copier.

Attention : La clé n'est affichée qu'une seule fois. NextCRM n'en conserve qu'une empreinte (hash) : personne, pas même le support, ne peut vous la réafficher. Si elle est perdue, révoquez-la et créez-en une nouvelle.

La liste affiche chaque clé avec son préfixe (par exemple ncrm_live_1a2b3c4d), ses autorisations, la personne qui l'a créée, sa dernière utilisation et son expiration. Révoquer bloque une clé immédiatement.

Ce qu'une clé peut faire

Une clé agit pour votre workspace avec les droits d'un Admin du workspace, limités aux autorisations choisies :

Autorisation	Permet
Leads (lecture / écriture)	Lister et lire les leads ; créer, modifier, déplacer vers une étape, attribuer, placer dans la corbeille et restaurer
Contacts (lecture / écriture)	Lister, lire, créer, modifier et supprimer des contacts
Tâches (lecture / écriture)	Lister et lire les tâches ; créer, modifier, terminer et archiver
Entonnoirs et étapes (lecture)	Lire les entonnoirs et leurs étapes
Envois de formulaires (lecture)	Lire les formulaires et leurs envois
Campagnes (lecture)	Lire les campagnes et leurs résultats
Notes et activités (lecture / écriture)	Lire les notes et l'historique d'un lead ; ajouter des notes et enregistrer des appels
Membres de l'équipe (lecture)	Lire les noms, e-mails et rôles des membres (pour attribuer leads et tâches)
Webhooks (lecture / écriture)	Lire, enregistrer et supprimer des endpoints de webhook

Les mêmes règles que dans l'application s'appliquent : limites du forfait (un nouveau lead au-delà de votre limite de leads actifs arrive dans la Boîte de réception des leads), la corbeille (un lead dans la corbeille doit être restauré avant d'être modifié ; une suppression via l'API place toujours dans la corbeille) et les données ne passent jamais dans un autre workspace. Ce que seules les personnes peuvent faire - gérer l'équipe, les rôles, la facturation ou les clés API et supprimer définitivement - est impossible avec une clé. Une clé cesse aussi de fonctionner lorsque la personne qui l'a créée n'est plus Admin du workspace.

Chaque modification effectuée avec une clé apparaît dans l'historique du lead sous le nom API key <nom>.

Votre premier appel

Envoyez la clé dans l'en-tête Authorization. L'URL de base est https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Créer un lead :

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

La référence complète avec tous les endpoints, champs et un exemple curl se trouve dans l'onglet Documentation de l'API, publiquement sur https://…/api/v1/docs et sous forme de fichier OpenAPI 3.1 sur https://…/api/v1/openapi.json.

Règles pour toute intégration

• Réponses de la forme { "data": ..., "meta": { ... } } ; erreurs { "error": { "code", "message", "details" } } avec la liste des champs pour les erreurs de validation. Les dates sont en ISO 8601, UTC.
• Pagination : les listes renvoient meta.next_cursor ; transmettez-le comme cursor pour obtenir la page suivante (limit jusqu'à 100).
• Idempotence : envoyez un en-tête Idempotency-Key avec les requêtes POST. Une nouvelle tentative avec la même clé renvoie le premier résultat au lieu de créer un doublon (pendant 24 heures).
• Limites de débit : 120 requêtes par minute par clé et 600 par workspace. Au-delà, l'API répond 429 avec un en-tête Retry-After : attendez ce nombre de secondes.
• Maintenance : pendant une mise à jour de NextCRM, l'API répond 503 MAINTENANCE avec Retry-After. Les webhooks sont mis en attente puis livrés ensuite.
• Uniquement côté serveur : appelez l'API depuis votre serveur. Les navigateurs ne peuvent pas l'appeler (pas de CORS) et une clé API ne doit jamais se trouver dans un site web ou une application.

Webhooks

1. Ouvrez l'onglet Webhooks et cliquez sur Ajouter un endpoint.
2. Saisissez l'URL de l'endpoint de votre serveur. Elle doit commencer par https:// et être joignable depuis internet ; les adresses internes, privées et de métadonnées cloud sont refusées.
3. Choisissez les Événements souhaités et cliquez sur Enregistrer l'endpoint.
4. Copiez le secret de signature (affiché une seule fois) et conservez-le sur votre serveur.
5. Cliquez sur Envoyer un événement de test pour vérifier que votre serveur répond.

Événements disponibles : lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined et automation.webhook.

Les événements de devis indiquent les montants en entiers dans la plus petite unité de la devise (par exemple en centimes) : subtotal_minor est la somme des lignes après les remises de ligne, discount_minor la remise sur l'ensemble du devis, tax_minor la taxe et total_minor le montant à payer. Le total_minor de chaque ligne est son montant après la remise de ligne, avant la remise du devis et la taxe.

Les prospects créés par un import de fichier envoient un lead.created par prospect importé une fois l'import terminé, avec "context": { "source": "import", "import_batch_id": "..." } à côté de data.

Chaque livraison est un POST contenant l'événement en JSON (id, type, created_at, actor, data) avec ces en-têtes : X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp et X-NextCRM-Signature.

Vérifier la signature

X-NextCRM-Signature ressemble à t=1760860800,v1=5f2b.... Calculez le HMAC-SHA256 de <t>.<corps brut de la requête> avec votre secret de signature et comparez-le à v1. Refusez les requêtes dont l'horodatage date de plus de 5 minutes.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Nouvelles tentatives, historique et renouvellement

• Répondez avec n'importe quel statut 2xx en moins de 10 secondes. Sinon, NextCRM réessaie avec des pauses croissantes (1, 2, 4, ... minutes), jusqu'à 8 tentatives.
• L'Historique des livraisons affiche chaque livraison avec son statut, ses tentatives et le code de réponse. Renvoyer remet une livraison en file d'attente.
• Après de nombreux échecs consécutifs, un endpoint est désactivé automatiquement et tous les Admins du workspace reçoivent une notification. Corrigez l'endpoint puis cliquez sur Activer.
• Renouveler le secret crée un nouveau secret de signature. L'ancien continue de signer pendant 24 heures pour que vous puissiez basculer sans perdre d'événements.

Lora et l'API

Lora peut expliquer l'API, ouvrir cette page et lister vos endpoints de webhook. Elle ne crée, n'affiche ni ne révoque jamais de clés API et ne voit jamais de secret de signature : c'est vous qui le faites sur cette page.

Dépannage

Réponse	Signification
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	La clé est incorrecte, révoquée ou expirée. Créez-en une nouvelle.
403 INSUFFICIENT_SCOPE	La clé n'a pas l'autorisation pour cet appel. Créez une clé avec l'autorisation nécessaire.
403 API_KEY_OWNER_NOT_ADMIN	La personne qui a créé la clé n'est plus Admin du workspace. Un admin actuel doit créer une nouvelle clé.
402 FEATURE_NOT_IN_PLAN	Le forfait n'inclut pas l'accès à l'API.
409 LEAD_IN_TRASH	Restaurez d'abord le lead (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Le champ et la raison figurent dans error.details.
429 RATE_LIMITED	Attendez les secondes de Retry-After, puis continuez.