Documentation de l'API

Le premier appel à faire quand on branche une intégration : il confirme que la clé fonctionne, sur quel espace elle porte, et combien d'appels il reste ce mois-ci.

CLÉ : LECTURE SEULE SUFFIT

• Aucun paramètre : si cet appel répond 200, votre clé et votre identifiant d'espace sont bons.
• Les en-têtes X-Kapacity-Quota-* accompagnent CHAQUE réponse de l'API, pas seulement celle-ci.

GET https://kapacity.app/api/v1/w/{workspace_id}/me
Authorization: Bearer kap_live_…

{
  "espace": {
    "id": "b7f1c0de-0000-4000-8000-000000000000",
    "nom": "Top Closer Academy",
    "plan": "free"
  },
  "cle": {
    "nom": "n8n",
    "portee": "lecture_ecriture",
    "proprietaire": true
  },
  "quota": {
    "mois": 12,
    "limite_mois": 10000,
    "restant_mois": 9988,
    "reset_mois": "2026-10-01T00:00:00.000Z"
  }
}

Le deuxième appel d'une intégration, après /me : il donne les identifiants de table dont tout le reste a besoin.

CLÉ : LECTURE SEULE SUFFIT

• DEUX SORTES DE TABLES. Les tables « native » sont vos pipelines : « leads » = Mon Pipe, « leads_setting » = Setting. Leur identifiant est ce mot, pas un UUID.
• Les tables « personnalisee » sont celles que votre équipe a créées (Ventes, Setting, Ressources…), identifiées par un UUID.
• Les deux s'utilisent EXACTEMENT de la même façon par la suite : mêmes adresses, mêmes réponses.
• On ne crée ni table ni colonne par API : cette partie du CRM se lit, elle ne se façonne pas.

GET https://kapacity.app/api/v1/w/{workspace_id}/tables
Authorization: Bearer kap_live_…

{
  "tables": [
    {
      "id": "leads",
      "nom": "Leads",
      "type": "native",
      "base": "pipe",
      "base_libelle": "Mon Pipe",
      "icone": null,
      "lignes": 42
    },
    {
      "id": "leads_setting",
      "nom": "Leads Setting",
      "type": "native",
      "base": "setting",
      "base_libelle": "Setting",
      "icone": null,
      "lignes": 8
    },
    {
      "id": "6b0c…",
      "nom": "Ventes",
      "type": "personnalisee",
      "base": "ventes",
      "base_libelle": "Mes Ventes",
      "icone": "card",
      "creee_le": "2026-09-01T09:12:00.000Z"
    }
  ],
  "bases": [
    {
      "id": "pipe",
      "libelle": "Mon Pipe"
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT

• L'erreur numéro un d'une intégration : dans Kapacity, une colonne est identifiée par un UUID, pas par son nom.
• On PEUT écrire par le nom (l'API le résout, sans tenir compte des accents, de la casse ni de la ponctuation), mais un outil sûr de lui relève d'abord ces identifiants.
• Une colonne « lecture_seule » (formule, cumul, lookup) est refusée en écriture, et l'API dit pourquoi.

GET https://kapacity.app/api/v1/w/{workspace_id}/tables/leads
Authorization: Bearer kap_live_…

{
  "table": {
    "id": "6b0c…",
    "nom": "Mes Ventes",
    "base": "ventes",
    "icone": "card",
    "lignes": 128
  },
  "colonnes": [
    {
      "id": "f1a2…",
      "nom": "Client",
      "type": "texte",
      "lecture_seule": false
    },
    {
      "id": "f3b4…",
      "nom": "Montant",
      "type": "monetaire",
      "lecture_seule": false
    },
    {
      "id": "f5c6…",
      "nom": "Statut",
      "type": "selection",
      "lecture_seule": false,
      "options": [
        {
          "id": "o1",
          "libelle": "Signé"
        }
      ]
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT

• Les lignes sortent de la plus ANCIENNE à la plus récente : c'est ce qui rend une synchronisation reprenable.
• Pagination par CURSEUR, jamais par numéro de page : une ligne créée entre deux appels ne fait sauter personne.
• Tant que « curseur_suivant » n'est pas null, il reste des lignes.
• Les valeurs sont BRUTES : un montant est en CENTIMES, une sélection est l'identifiant de son option. Avec « format=lisible » : euros, libellés et noms des membres.
• CHERCHER UNE LIGNE : filtre=Email:eq:jean@acme.fr. Plusieurs « filtre » se cumulent en ET. Un montant se compare en CENTIMES (filtre=Montant:gt:100000).
• Pour une SÉLECTION, filtrez par l'identifiant de l'option (rendu par GET /tables/{id}). Avec « format=lisible », par son libellé, et un montant en euros (filtre=Montant:gt:1000).
• Pour chercher sans savoir dans quelle colonne : recherche=Dupont.
• Le nom d'une colonne se donne comme on veut : « E-mail », « Email » et « email » désignent la même. Accents, casse et ponctuation sont ignorés.

GET https://kapacity.app/api/v1/w/{workspace_id}/tables/leads/records?filtre=Email:eq:jean@acme.fr
Authorization: Bearer kap_live_…

{
  "lignes": [
    {
      "id": "a1b2…",
      "cree_le": "2026-09-02T10:00:00.000Z",
      "modifie_le": "2026-09-20T14:31:00.000Z",
      "champs": {
        "f1a2…": "Acme",
        "f3b4…": 350000
      }
    }
  ],
  "curseur_suivant": "MjAyNi0wOS0wMlQxMDowMDowMC4wMDBafGExYjI"
}

CLÉ : LECTURE ET ÉCRITURE

• Une valeur invalide est IGNORÉE et expliquée dans « ignores », jamais convertie en effacement.
• Si AUCUNE valeur n'a pu être écrite, l'appel est refusé en 422 plutôt que de créer une ligne vide.
• Une création déclenche les automatisations « Quand un enregistrement est créé », comme une saisie à la main.
• Dans « leads » ou « leads_setting », un contact a besoin d'un « Prénom » ou d'un « Nom » : sans l'un ni l'autre, l'appel est refusé plutôt que de créer un contact « Sans nom ».

POST https://kapacity.app/api/v1/w/{workspace_id}/tables/leads/records
Authorization: Bearer kap_live_…
Content-Type: application/json

{
  "champs": {
    "Prénom": "Jean",
    "Nom": "Dupont",
    "Email": "jean@acme.fr"
  }
}

{
  "ligne": {
    "id": "a1b2…",
    "cree_le": "2026-09-22T10:00:00.000Z",
    "modifie_le": null,
    "champs": {
      "f1a2…": "Acme"
    }
  }
}

Sans lui, importer 500 contacts coûte 500 appels, soit 5 % du quota mensuel d'un espace gratuit pour un seul import. Avec lui, cinq appels.

CLÉ : LECTURE ET ÉCRITURE

• Une ligne refusée n'arrête PAS les autres : chaque entrée rend son sort dans « resultats », avec son rang. Un import de 500 lignes qui s'arrête à la 37e est un import à refaire à la main.
• Les automatisations sont COUPÉES par défaut, contrairement à l'écriture à l'unité : 100 lignes importées, ce serait 100 séquences d'e-mails envoyées à des gens qui viennent d'être importés. « ?automatisations=1 » les rallume.
• 201 dès qu'une ligne est passée, 422 si tout a été refusé : on peut aiguiller sur le code sans lire le détail.
• Posez un « Idempotency-Key » : si le réseau coupe avant la réponse, le rejeu rend le résultat du premier appel. La réponse rejouée porte l'en-tête X-Kapacity-Idempotent-Replay.

POST https://kapacity.app/api/v1/w/{workspace_id}/tables/leads/records/bulk
Authorization: Bearer kap_live_…
Content-Type: application/json
Idempotency-Key: import-salon-2026-lot-1

{
  "lignes": [
    {
      "champs": {
        "Prénom": "Jean",
        "Nom": "Dupont",
        "Email": "jean@acme.fr"
      }
    },
    {
      "champs": {
        "Prénom": "Léa",
        "Nom": "Martin",
        "Email": "lea@acme.fr"
      }
    }
  ]
}

{
  "creees": 2,
  "refusees": 1,
  "automatisations": false,
  "resultats": [
    {
      "i": 0,
      "ok": true,
      "id": "l1…"
    },
    {
      "i": 1,
      "ok": true,
      "id": "l2…"
    },
    {
      "i": 2,
      "ok": false,
      "erreur": "Aucune valeur n'a pu être écrite."
    }
  ],
  "lignes": []
}

CLÉ : LECTURE SEULE SUFFIT

• La ligne porte sa table : l'adresse n'a pas besoin de la répéter.

GET https://kapacity.app/api/v1/w/{workspace_id}/records/7fc74cfb-c67a-43d2-868f-f4a8ab028475
Authorization: Bearer kap_live_…

{
  "ligne": {
    "id": "a1b2…",
    "cree_le": "2026-09-02T10:00:00.000Z",
    "modifie_le": null,
    "champs": {
      "f1a2…": "Acme"
    }
  },
  "table": {
    "id": "6b0c…",
    "nom": "Mes Ventes"
  },
  "colonnes": [
    {
      "id": "f1a2…",
      "nom": "Client",
      "type": "texte",
      "lecture_seule": false
    }
  ]
}

CLÉ : LECTURE ET ÉCRITURE

• Pour VIDER une colonne, envoyez null (ou une chaîne vide, ou une liste vide).
• Une modification déclenche les automatisations « Quand un enregistrement est modifié ».

PATCH https://kapacity.app/api/v1/w/{workspace_id}/records/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
Authorization: Bearer kap_live_…
Content-Type: application/json

{
  "champs": {
    "Client": "Acme SAS",
    "Montant": 350000
  }
}

{
  "ligne": {
    "id": "a1b2…",
    "cree_le": "2026-09-02T10:00:00.000Z",
    "modifie_le": "2026-09-22T11:00:00.000Z",
    "champs": {
      "f1a2…": "Acme SAS"
    }
  }
}

CLÉ : LECTURE ET ÉCRITURE

• Aucune corbeille : la ligne est perdue. Le journal d'activité garde la trace de la suppression et de la clé qui l'a faite.

DELETE https://kapacity.app/api/v1/w/{workspace_id}/records/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
Authorization: Bearer kap_live_…

{
  "supprime": true,
  "id": "a1b2…"
}

CLÉ : LECTURE SEULE SUFFIT

• Envoyez le « lien_public » à votre prospect : il choisit son créneau, et le rendez-vous, le contact et l'invitation d'agenda se créent tout seuls.
• Poser un rendez-vous directement par API n'existe pas : le round-robin, les disponibilités et l'anti-double-réservation se décident côté Kapacity.
• « parts » donne la répartition voulue entre les assignés de même priorité, en pourcentage (somme 100 pour chaque niveau de priorité) : c'est le réglage du type, pas ce qui a été reçu.
• « priorites » donne le niveau de chaque assigné, de 1 à 5 (5 la plus haute, 3 quand rien n'est réglé) : sur un créneau, les assignés libres du niveau le plus haut reçoivent tous les rendez-vous, et un niveau plus bas ne prend le relais que lorsque tous ceux du dessus sont pris. Vide quand le type tourne par équipe.
• « repartition » dit comment l'équipe tourne : « tour » (chacun son tour), « charge » (le moins chargé, en suivant les parts) ou « hasard » (tirage au sort pondéré par les parts, « Par % de chance » à l'écran).
• « attribution_par » vaut « equipes » quand le type tourne par équipe : « equipes » donne alors chaque équipe cochée, sa « part » en pourcentage (somme 100) et ses « membres » actuels, « assignes » tous ces membres, et « parts » (par membre) reste vide. Un rendez-vous part d'abord à une équipe selon sa part, puis à l'un de ses membres libres, à parts égales.

GET https://kapacity.app/api/v1/w/{workspace_id}/event-types
Authorization: Bearer kap_live_…

{
  "types_de_rendez_vous": [
    {
      "id": "e1f2…",
      "nom": "Appel de qualification",
      "duree_min": 30,
      "lieu": "Google Meet",
      "attribution": "round_robin",
      "attribution_par": "membres",
      "repartition": "charge",
      "repartition_libelle": "Le moins chargé",
      "assignes": [
        "u1…",
        "u2…",
        "u3…"
      ],
      "parts": {
        "u1…": 67,
        "u2…": 33,
        "u3…": 100
      },
      "priorites": {
        "u1…": 5,
        "u2…": 5,
        "u3…": 3
      },
      "equipes": [],
      "actif": true,
      "questions": 3,
      "lien_public": "https://kapacity.app/b/mon-espace/appel-de-qualification"
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT

• Chaque identifiant vient avec son nom : un scénario n'a jamais à faire un second appel pour savoir qui est « u1… ».

GET https://kapacity.app/api/v1/w/{workspace_id}/bookings?depuis=2026-09-22T00:00:00Z&statut=confirme
Authorization: Bearer kap_live_…

{
  "rendez_vous": [
    {
      "id": "b1c2…",
      "debut": "2026-09-23T09:00:00.000Z",
      "fin": "2026-09-23T09:30:00.000Z",
      "statut": "confirme",
      "type": {
        "id": "e1f2…",
        "nom": "Appel de qualification"
      },
      "assigne": {
        "id": "u1…",
        "nom": "Camille Royer"
      },
      "contact": {
        "id": "l1…",
        "nom": "Jean Dupont"
      },
      "invite": {
        "nom": "Jean Dupont",
        "email": "jean@acme.fr",
        "telephone": "+33612345678"
      },
      "lien_visio": "https://meet.google.com/abc-defg-hij"
    }
  ],
  "curseur_suivant": null
}

CLÉ : LECTURE SEULE SUFFIT

GET https://kapacity.app/api/v1/w/{workspace_id}/forms
Authorization: Bearer kap_live_…

{
  "formulaires": [
    {
      "id": "f1…",
      "titre": "Candidature",
      "statut": "publie",
      "questions": 12,
      "lien_public": "https://kapacity.app/f/candidature"
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT

• Les réponses sortent avec le LIBELLÉ de chaque question, pas son identifiant : elles se lisent sans relire le formulaire.

GET https://kapacity.app/api/v1/w/{workspace_id}/forms/f1e2d3c4-b5a6-4978-8695-a4b3c2d1e0f9/responses?qualifie=true
Authorization: Bearer kap_live_…

{
  "formulaire": {
    "id": "f1…",
    "titre": "Candidature"
  },
  "reponses": [
    {
      "id": "r1…",
      "soumise_le": "2026-09-21T18:02:00.000Z",
      "score": 86,
      "qualifie": true,
      "complete": true,
      "repondant": {
        "nom": "Jean Dupont",
        "email": "jean@acme.fr"
      },
      "contact": {
        "id": "l1…",
        "nom": "Jean Dupont"
      },
      "reponses": {
        "Votre budget": "Plus de 5 000 €",
        "Votre objectif": "Doubler mon chiffre"
      }
    }
  ],
  "curseur_suivant": null
}

CLÉ : LECTURE SEULE SUFFIT

• Le corps du contrat n'est pas rendu ici, il est long : GET /contracts/{id} le donne.
• Les montants sont en CENTIMES.

GET https://kapacity.app/api/v1/w/{workspace_id}/contracts?statut=signe
Authorization: Bearer kap_live_…

{
  "contrats": [
    {
      "id": "c1…",
      "titre": "Accompagnement 6 mois",
      "statut": "signe",
      "montant_cents": 500000,
      "contact": {
        "id": "l1…",
        "nom": "Jean Dupont"
      },
      "signataire": {
        "nom": "Jean Dupont",
        "email": "jean@acme.fr"
      },
      "envoye_le": "2026-09-19T10:00:00.000Z",
      "signe_le": "2026-09-20T08:14:00.000Z"
    }
  ],
  "curseur_suivant": null
}

CLÉ : LECTURE SEULE SUFFIT

• La piste d'audit est ce qui donne sa valeur probante à la signature : horodatage et adresse IP de chaque étape.
• Elle est en ajout seul en base : l'API la lit, personne ne la réécrit.

GET https://kapacity.app/api/v1/w/{workspace_id}/contracts/b423fdff-34f8-4a04-a66f-68034f0d77fe
Authorization: Bearer kap_live_…

{
  "contrat": {
    "id": "c1…",
    "titre": "Accompagnement 6 mois",
    "statut": "signe",
    "montant_cents": 500000,
    "empreinte": "9f2c…"
  },
  "piste_audit": [
    {
      "etape": "cree",
      "libelle": "Contrat créé",
      "le": "2026-09-19T09:58:00.000Z",
      "ip": null
    },
    {
      "etape": "signe",
      "libelle": "Signé",
      "le": "2026-09-20T08:14:00.000Z",
      "ip": "81.…"
    }
  ]
}

C'est d'ici que vient le « modele_id » qu'attend POST /contracts. Chaque modèle dit s'il est utilisable maintenant et quel message e-mail partira avec lui.

CLÉ : LECTURE SEULE SUFFIT

• Le « id » de chaque modèle est le « modele_id » à passer à POST /contracts.
• « utilisable » vaut false pour un modèle désactivé ou suspendu par le plan gratuit, et « raison » dit lequel des deux : POST /contracts le refuserait.
• « message_email » est l'e-mail qui partira au contact avec le lien de signature. S'il vaut null, aucun e-mail ne partira : le contrat sera quand même envoyé, et son lien rendu.
• « montant_defaut_cents » est le montant réglé sur le modèle, à titre indicatif : POST /contracts vous demande toujours le montant du contrat. En CENTIMES.

GET https://kapacity.app/api/v1/w/{workspace_id}/contract-templates
Authorization: Bearer kap_live_…

{
  "modeles": [
    {
      "id": "3e5a7c9b-2d4f-4e6a-8b1c-9d0e2f4a6b8c",
      "titre": "Accompagnement 6 mois",
      "montant_defaut_cents": 500000,
      "utilisable": true,
      "raison": null,
      "message_email": {
        "id": "8a6c4e2f-0b9d-4f7b-a5c3-1e9f7d5b3a1c",
        "nom": "Votre contrat à signer"
      },
      "cree_le": "2026-09-10T09:00:00.000Z"
    }
  ]
}

Vous dites QUEL modèle de contrat, à QUEL contact, et pour QUEL montant : les trois vont dans le body JSON. Kapacity fait alors exactement ce que fait le bouton « Envoyer le contrat » de l'application : le contrat est rempli avec les informations du contact (nom, e-mail, société) et le montant, il part à la signature, le contact passe à « Contrat envoyé », et l'e-mail rattaché au modèle lui est envoyé avec le lien pour signer. La réponse vous rend ce lien (« lien_signature »), pour l'envoyer aussi par un autre canal si vous le voulez.

CLÉ : LECTURE ET ÉCRITURE

• Le LIEN DE SIGNATURE est dans « contrat.lien_signature ». Il est TOUJOURS rendu, que l'e-mail parte ou non : c'est la page où le contact lit et signe son contrat.
• Le montant est OBLIGATOIRE et s'écrit en CENTIMES : 450000 = 4 500 €, 99900 = 999 €. Sans lui, l'appel est refusé (422) : un contrat ne part jamais à un prix que vous n'avez pas écrit.
• « email » dit si l'e-mail est parti : { envoye: true, a: <adresse> }. Sinon { envoye: false, raison } explique pourquoi (pas de message rattaché au modèle, pas d'adresse chez le contact, pas de boîte d'envoi reliée, ou « envoyer_email »: false). Le contrat, lui, est envoyé dans tous les cas.
• Posez un « Idempotency-Key » (un texte unique par envoi, par exemple l'identifiant du deal) : si le réseau coupe et que votre scénario rejoue l'appel, le contact recevrait sinon DEUX contrats. Avec lui, le second appel rend le premier envoi.
• Le message part de la boîte du Sales du contact s'il en a relié une, sinon de la boîte de l'espace.
• Le contrat est FIGÉ à l'envoi : modifier le contact ensuite ne change pas le contrat.
• La piste d'audit du contrat dit « créé » puis « envoyé » par votre clé, sous son nom.
• Au plan gratuit, 5 envois de contrat par mois : au-delà, 429 « limite_plan » avec un Retry-After jusqu'au mois suivant.
• Un modèle désactivé ou suspendu par le plan est refusé en 422 : GET /contract-templates le dit à l'avance.

POST https://kapacity.app/api/v1/w/{workspace_id}/contracts
Authorization: Bearer kap_live_…
Content-Type: application/json
Idempotency-Key: contrat-jean-dupont-2026-09-23

{
  "modele_id": "3e5a7c9b-2d4f-4e6a-8b1c-9d0e2f4a6b8c",
  "contact_id": "7fc74cfb-c67a-43d2-868f-f4a8ab028475",
  "montant_cents": 450000
}

{
  "contrat": {
    "id": "b423fdff-34f8-4a04-a66f-68034f0d77fe",
    "titre": "Accompagnement 6 mois · Jean Dupont",
    "statut": "envoye",
    "montant_cents": 450000,
    "contact": {
      "id": "7fc74cfb-c67a-43d2-868f-f4a8ab028475",
      "nom": "Jean Dupont",
      "email": "jean@acme.fr"
    },
    "signataire": {
      "nom": "Jean Dupont",
      "email": "jean@acme.fr"
    },
    "lien_signature": "https://kapacity.app/c/ab29cbefa0874ba5b2cc1c0758aa9fcd6f276503a714411391a2e8017d780ca6",
    "cree_le": "2026-09-23T11:50:37.723277+00:00",
    "envoye_le": "2026-09-23T11:50:37.498Z"
  },
  "email": {
    "envoye": true,
    "a": "jean@acme.fr"
  },
  "automatisations": true
}

CLÉ : LECTURE SEULE SUFFIT

• Prix, acompte et coût sont en CENTIMES.

GET https://kapacity.app/api/v1/w/{workspace_id}/products
Authorization: Bearer kap_live_…

{
  "produits": [
    {
      "id": "p1…",
      "nom": "Accompagnement 6 mois",
      "prix_cents": 500000,
      "mensualites": 3,
      "actif": true
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT

• Lecture seule, et volontairement : un paiement est un fait constaté chez le fournisseur, pas une donnée qu'on saisit.
• Les montants sont en CENTIMES et HORS TAXES.

GET https://kapacity.app/api/v1/w/{workspace_id}/payments?depuis=2026-09-01T00:00:00Z
Authorization: Bearer kap_live_…

{
  "paiements": [
    {
      "id": "pay1…",
      "recu_le": "2026-09-20T08:20:00.000Z",
      "montant_cents": 180000,
      "devise": "eur",
      "statut": "succeeded",
      "fournisseur": "whop",
      "payeur": {
        "nom": "Jean Dupont",
        "email": "jean@acme.fr"
      },
      "contact": {
        "id": "l1…",
        "nom": "Jean Dupont"
      },
      "rattache_a_une_vente": true
    }
  ],
  "curseur_suivant": null
}

CLÉ : LECTURE SEULE SUFFIT

• Une colonne « membre » (Sales, Setter) s'écrit avec l'identifiant rendu ici, ou avec l'e-mail ou le nom exact.
• « equipes » donne les identifiants des équipes du membre, ceux que « GET /event-types » rend dans « equipes ».

GET https://kapacity.app/api/v1/w/{workspace_id}/members
Authorization: Bearer kap_live_…

{
  "membres": [
    {
      "id": "u1…",
      "nom": "Camille Royer",
      "email": "camille@…",
      "roles": [
        "closer"
      ],
      "equipes": [
        "t1…"
      ],
      "proprietaire": false
    }
  ]
}

CLÉ : LECTURE SEULE SUFFIT · RÉSERVÉ AU PROPRIÉTAIRE

• RÉSERVÉ aux clés créées par le PROPRIÉTAIRE de l'espace : « Logs Workspace » lui est réservé dans l'application, l'API ne fait pas exception.
• Le plus récent d'abord, contrairement aux autres listes : un journal se lit à l'envers.
• Le genre « api » retrouve tout ce que vos intégrations ont écrit, avec le nom de la clé.

GET https://kapacity.app/api/v1/w/{workspace_id}/activity?qui=api
Authorization: Bearer kap_live_…

{
  "activite": [
    {
      "id": "a1…",
      "le": "2026-09-22T11:02:00.000Z",
      "action": "lead.create",
      "phrase": "a ajouté le contact « Jean Dupont »",
      "acteur": {
        "genre": "api",
        "id": null,
        "nom": "API · n8n"
      },
      "objet": {
        "nature": "lead",
        "id": "l1…",
        "libelle": "Jean Dupont"
      }
    }
  ],
  "curseur_suivant": null
}

Un abonnement dit « appelle cette adresse quand ceci se passe ». C'est ce qui remplace un scénario qui interroge l'API toutes les cinq minutes : il consommerait du quota pour rien et réagirait en retard.

CLÉ : LECTURE SEULE SUFFIT

• Le secret de signature n'est JAMAIS rendu ici : il n'est lisible qu'une fois, à la création.

GET https://kapacity.app/api/v1/w/{workspace_id}/webhooks
Authorization: Bearer kap_live_…

{
  "webhooks": [
    {
      "id": "w1…",
      "url": "https://n8n.exemple.fr/webhook/abc",
      "evenements": [
        "contrat.signe"
      ],
      "actif": true,
      "ignorer_api": true,
      "description": "Scénario de closing",
      "cree_le": "2026-09-22T09:00:00.000Z",
      "dernier_envoi_le": "2026-09-22T11:30:00.000Z",
      "echecs_consecutifs": 0
    }
  ],
  "evenements_possibles": [
    {
      "id": "contrat.signe",
      "libelle": "Quand un contrat est signé",
      "description": "Un contrat revient signé."
    }
  ]
}

CLÉ : LECTURE ET ÉCRITURE

• Le « secret » n'est rendu QU'ICI, une seule fois : notez-le. Il sert à vérifier notre signature, sans lui n'importe qui pourrait se faire passer pour Kapacity auprès de votre serveur.
• L'adresse doit être publique et en https. Une adresse privée est refusée, à la création comme à chaque envoi.
• Si votre scénario ÉCRIT dans Kapacity et écoute les mêmes événements, mettez « ignorer_api » à true : sinon il se réveille lui-même, indéfiniment.

POST https://kapacity.app/api/v1/w/{workspace_id}/webhooks
Authorization: Bearer kap_live_…
Content-Type: application/json

{
  "nom": "Relance après signature",
  "url": "https://n8n.exemple.fr/webhook/abc",
  "evenements": [
    "contrat.signe"
  ],
  "entete": {
    "nom": "X-Api-Key",
    "valeur": "une-valeur-que-vous-choisissez"
  },
  "ignorer_api": true
}

{
  "webhook": {
    "id": "w1…",
    "nom": "Relance après signature",
    "url": "https://n8n.exemple.fr/webhook/abc",
    "evenements": [
      "contrat.signe"
    ],
    "actif": true,
    "entete_nom": "X-Api-Key"
  },
  "secret": "whsec_…"
}

CLÉ : LECTURE ET ÉCRITURE

• Seuls les champs envoyés changent : les autres restent tels quels.
• Le secret ne se change pas : pour en changer, supprimez l'abonnement et recréez-le. C'est ce qui garantit qu'il n'existe qu'à un seul endroit.
• Réactiver remet le compteur d'échecs à zéro : un abonnement réparé repart avec toutes ses chances.

PATCH https://kapacity.app/api/v1/w/{workspace_id}/webhooks/5c7e9a1b-3d5f-4b7d-9f1a-2c4e6a8b0d2f
Authorization: Bearer kap_live_…
Content-Type: application/json

{
  "nom": "Relance après signature",
  "evenements": [
    "contrat.envoye",
    "contrat.signe"
  ],
  "entete": {
    "nom": "X-Api-Key",
    "valeur": "une-nouvelle-valeur"
  }
}

{
  "webhook": {
    "id": "w1…",
    "nom": "Relance après signature",
    "evenements": [
      "contrat.envoye",
      "contrat.signe"
    ],
    "actif": true,
    "echecs_consecutifs": 0,
    "entete_nom": "X-Api-Key"
  }
}

CLÉ : LECTURE ET ÉCRITURE

• Définitif. Pour arrêter les envois sans perdre l'historique, passez « actif » à false.

DELETE https://kapacity.app/api/v1/w/{workspace_id}/webhooks/5c7e9a1b-3d5f-4b7d-9f1a-2c4e6a8b0d2f
Authorization: Bearer kap_live_…

{
  "supprime": true,
  "id": "w1…"
}

L'essai passe par la MÊME file que les vrais envois : même signature, mêmes en-têtes, mêmes reprises. Un essai qui aboutit prouve donc que le vrai aboutira.

CLÉ : LECTURE ET ÉCRITURE

• Le corps porte « essai: true » : votre scénario peut s'arrêter là plutôt que de créer une vraie facture.
• La réponse est un 202 : l'envoi part dans les secondes qui suivent. Son résultat se lit dans le journal des envois.

POST https://kapacity.app/api/v1/w/{workspace_id}/webhooks/5c7e9a1b-3d5f-4b7d-9f1a-2c4e6a8b0d2f/test?evenement=contrat.signe
Authorization: Bearer kap_live_…

{
  "envoi": {
    "id": "d1…",
    "event_id": "e1…",
    "evenement": "contrat.signe",
    "statut": "en_attente"
  }
}

CLÉ : LECTURE SEULE SUFFIT

• C'est ici que « je ne reçois rien » trouve sa réponse : le code HTTP et le début de la réponse de VOTRE serveur y sont écrits.
• Le plus récent d'abord : on vient y chercher le dernier envoi, pas rejouer l'historique.

GET https://kapacity.app/api/v1/w/{workspace_id}/webhooks/5c7e9a1b-3d5f-4b7d-9f1a-2c4e6a8b0d2f/deliveries?statut=echec
Authorization: Bearer kap_live_…

{
  "envois": [
    {
      "id": "d1…",
      "event_id": "e1…",
      "evenement": "contrat.signe",
      "statut": "echec",
      "tentatives": 4,
      "code_http": 401,
      "reponse": "Unauthorized",
      "erreur": null,
      "duree_ms": 180,
      "prochaine_tentative_le": null,
      "envoye_le": null,
      "cree_le": "2026-09-22T11:30:00.000Z"
    }
  ],
  "curseur": null
}

CLÉ : LECTURE ET ÉCRITURE

• Le corps rejoué est celui de l'ÉPOQUE, pas l'état d'aujourd'hui : c'est bien l'événement qui est rejoué.
• Le « webhook-id » reste le même : un destinataire qui déduplique reconnaît un doublon au lieu de traiter deux fois.
• Un envoi encore en cours de tentatives ne se rejoue pas : attendez son résultat.

POST https://kapacity.app/api/v1/w/{workspace_id}/webhooks/5c7e9a1b-3d5f-4b7d-9f1a-2c4e6a8b0d2f/deliveries/9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a/replay
Authorization: Bearer kap_live_…

{
  "envoi": {
    "id": "d2…",
    "event_id": "e1…",
    "evenement": "contrat.signe",
    "statut": "en_attente"
  },
  "rejoue_depuis": "d1…"
}