# L’API Kolinea : ouvrir des dossiers et publier des demandes depuis vos outils

> Une clé par espace, des droits par domaine, des webhooks et une documentation générée : ce que l’API Kolinea permet.

Un devis part de votre logiciel de gestion, une fiche client de votre CRM, un rendez-vous de votre agenda. Recopier ces informations dans chaque dossier prend du temps et laisse passer des erreurs. L’API Kolinea permet à vos outils de le faire à votre place : ouvrir un dossier, publier une demande de pièces, relire une réponse, rattacher un contact. Voici ce qu’elle couvre, comment on lui donne ses droits et comment son outil est prévenu quand quelque chose change.

## Que peut faire un outil avec l’API Kolinea ?

Tout ce qu’une personne fait dans le produit peut se faire par l’API, avec la même rigueur. Quatre grands domaines sont ouverts :

- **Les dossiers** : en lister, en ouvrir, les lire, en changer les informations.
- **Les publications** : les demandes, les réponses, les documents et les commentaires du fil. Un outil peut publier une demande de pièces, lire la réponse du client ou récupérer le document reçu.
- **L’annuaire des contacts** : lire, créer et mettre à jour les fiches de vos contacts.
- **Les réglages de l’espace** pour les dossiers : l’espace garde le même fonctionnement, qu’il soit piloté à la main ou par un outil.

Le noyau de Kolinea ajoute les comptes, les membres, les invitations, les notifications, les exports, l’abonnement et les webhooks. Les envois qui créent quelque chose (un dossier, une publication) peuvent être rejoués sans risque de doublon : si votre outil répète un appel après une coupure, Kolinea ne crée pas la chose deux fois.

## Comment relier ses dossiers à ceux d’un autre logiciel ?

Votre logiciel de gestion a ses propres numéros de dossier, votre CRM ses propres identifiants de clients. Un dossier ou un contact peut maintenant porter la référence de l’outil qui l’a créé, dans un champ prévu pour cela (`external_ref`). Votre outil retrouve ainsi, d’un appel à l’autre, le dossier ou la fiche qui correspond à son enregistrement, sans tenir de table de correspondance de son côté.

Pour la fiche d’un contact, cela se combine avec l’[annuaire des contacts de Kolinea](/fr/features/annuaire-des-contacts) : une fiche par personne, partagée par tous ses dossiers, que votre CRM peut maintenir à jour.

## Quels droits donne-t-on à une clé ?

L’accès passe par une clé propre à votre espace. Vous la créez dans les paramètres de l’espace, rubrique Développeurs, et elle ne s’affiche qu’une seule fois. Pour chaque domaine, vous choisissez Aucun, Lecture ou Écriture. Les droits se modifient après coup sans changer la clé : l’outil suit dès son appel suivant.

Une clé se comporte comme un compte de service, jamais comme une personne :

1. Elle appartient à un espace et ne voit aucun dossier d’un autre espace.
2. Ce qu’elle publie dans un fil porte le nom que vous lui avez donné, marqué « Intégration ». Vos clients savent que le message vient d’une application.
3. Elle ne lit jamais une publication confidentielle adressée à quelqu’un d’autre.
4. Elle ne supprime pas l’espace, ne change pas l’offre et ne crée pas d’autre clé.

Une clé peut avoir une date d’expiration, et vous la supprimez quand vous voulez : l’outil qui s’en servait perd aussitôt l’accès. Elle cesse aussi de fonctionner quand le membre qui l’a créée quitte l’espace. Pour le détail, la [page de la fonctionnalité API et intégrations](/fr/features/api-et-integrations) décrit chaque règle.

## Comment son outil est-il prévenu quand quelque chose change ?

Plutôt que d’interroger l’API en boucle, votre outil peut recevoir un webhook : vous donnez une adresse dans les paramètres de l’espace et vous choisissez les événements à recevoir, par exemple une réponse à une demande ou l’arrivée d’une pièce. Le message envoyé reste mince : il ne contient que des identifiants. Votre outil relit ensuite le détail avec sa clé, dans la limite de ses droits, de sorte qu’aucune information du dossier ne circule dans un message que vous ne maîtrisez pas.

Chaque envoi est signé, les envois qui échouent sont retentés, et un envoi peut être rejoué depuis les paramètres, utile le jour où votre outil était en panne.

## Où trouver la documentation ?

La documentation est générée à partir du produit lui-même, pas rédigée à côté. Pour chaque point d’accès, elle indique les droits demandés, décrit chaque champ en français et en anglais et montre de vrais exemples de réponse, issus d’un espace de démonstration. Comme elle suit le code, elle ne peut pas décrire une ancienne version de l’API. La spécification OpenAPI se télécharge aussi, pour générer un client ou l’importer dans un outil de test d’appels.

## Par où commencer ?

Commencez petit. Créez une clé en Lecture sur les dossiers et essayez de les lister depuis un outil de test. Quand la lecture se passe comme prévu, passez la clé en Écriture sur le seul domaine dont l’outil a besoin, par exemple les publications, et gardez les autres à Aucun. Si vous ne programmez pas vous-même, donnez la documentation à la personne qui s’occupe de vos outils : elle y trouvera tout ce qu’il faut pour brancher votre logiciel de gestion.

Les clés se créent dans les paramètres de l’espace, rubrique Développeurs.