Codenica API

Codenica API permet de relier des applications externes aux données de votre système Codenica, en Cloud comme en On-Premise. Cet article présente les règles communes à toute l'API : création d'une clé, choix des scopes, adresse du service, authentification et envoi sécurisé des requêtes. Les champs et opérations propres à chaque objet sont décrits dans des articles API séparés.

Créer une clé API

Commencez la préparation de l'intégration par la création de la clé API adaptée. La clé est rattachée à votre entreprise et permet à l'application externe d'exécuter uniquement les opérations couvertes par les scopes sélectionnés.

  1. Ouvrez Paramètres, puis sélectionnez API et API Keys.
  2. Saisissez le nom de l'intégration dans le champ Nom, par exemple Intégration de l'entrepôt ou Rapports BI.
  3. Ajoutez éventuellement une description pour reconnaître plus tard l'usage de la clé.
  4. Définissez la date Actif jusqu'au. Une durée plus courte limite les conséquences d'une divulgation accidentelle des identifiants.
  5. Sélectionnez uniquement les scopes nécessaires à l'intégration.
  6. Sélectionnez Créer une clé API.
  7. Copiez immédiatement le Client ID et le Client Secret, puis conservez-les dans le coffre de secrets utilisé par l'intégration.

Le Client Secret n'est affiché qu'après la création de la clé ou lors de sa rotation. La liste conserve les informations de la clé, mais ne renvoie pas le secret. Si vous le perdez, effectuez une rotation ou supprimez la clé et créez-en une nouvelle.

Panneau API Keys dans les paramètres de Codenica, avec le formulaire de création d'une clé et la liste des scopes d'autorisation.

Limites de clés selon la licence

Traitez chaque clé comme un canal d'accès distinct pour une intégration. Le nombre de clés disponibles dépend de la licence de l'entreprise :

Licence
Accès à l'API
Nombre maximal de clés actives
Starter
Aucun
0
Plus
Oui
50
Enterprise
Oui
100

La suppression d'une clé supprime son enregistrement et libère une place dans la limite. Cette opération est définitive : vérifiez donc que l'intégration n'utilise plus cette clé avant de la supprimer.

Lorsque la date d'expiration est atteinte, l'authentification s'arrête, mais l'enregistrement reste visible dans la liste.

Si vous ne définissez pas de date de fin lors de la création, la durée de validité par défaut est de 90 jours. La durée maximale d'activité d'une clé est de 5 ans. En pratique, adaptez cette date au cycle de révision de l'intégration.

Adresse de l'API et authentification

L'adresse de base dépend du mode de déploiement. Ajoutez /api/v1, puis le chemin de la ressource concernée, à l'adresse de base.

  • Cloud : utilisez l'adresse publique de l'entreprise, par exemple https://votre-entreprise.codenica.com/api/v1.
  • On-Premise : l'adresse par défaut enregistrée par Codenica Discovery est http://codenica.local:5150/api/v1. Si l'administrateur a publié l'installation avec un nom DNS personnalisé, un reverse proxy ou HTTPS, utilisez l'adresse accessible au serveur d'intégration. Les détails du déploiement sont présentés dans le guide d'installation de Codenica On-Premise.

N'utilisez pas localhost, l'adresse d'un conteneur ou celle de la base de données, sauf si l'application d'intégration fonctionne exactement sur le même ordinateur et qu'il s'agit d'une configuration de test volontaire. Le serveur d'intégration doit pouvoir accéder à l'adresse publiée de Codenica.

Authentifiez chaque requête API avec deux en-têtes :

  • X-Codenica-Client-Id - identifiant de la clé ;
  • X-Codenica-Client-Secret - secret de la clé.

Ne transmettez pas la session du panneau ni le JWT de l'utilisateur à l'API publique. Ne placez jamais le secret dans l'URL, les paramètres de requête, le contenu des réponses ou les journaux.

export BASE_URL="https://votre-entreprise.codenica.com"
export CLIENT_ID="cna_votre_client_id"
export CLIENT_SECRET="cns_votre_client_secret"

curl --request GET \
  --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Pour l'installation On-Premise par défaut, remplacez BASE_URL dans l'exemple par http://codenica.local:5150. En production, utilisez HTTPS lorsque l'installation est publiée avec un certificat.

Format standard des requêtes

Les exemples des articles suivants suivent une structure REST simple : méthode, URL, en-têtes et, pour les opérations avec contenu, JSON transmis avec --data-raw. Cette présentation peut être reprise facilement dans le code de l'application ou dans un outil d'intégration.

Les opérations qui modifient les données exigent aussi l'en-tête Idempotency-Key. Donnez-lui une valeur unique pour chaque intention d'opération. Répéter exactement la même requête avec la même clé ne doit pas créer un second enregistrement.

curl --request POST \
  --url "$BASE_URL/api/v1/<resource>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: integration-create-20260907-001" \
  --data-raw '{"field":"value"}'

Pour les mises à jour, suppressions, relations et opérations sur les fichiers, envoyez également l'en-tête If-Match avec la valeur actuelle de l'ETag. Les pages consacrées aux objets indiquent les chemins, les noms de champs et les corps JSON exacts.

Cycle de travail commun d'une intégration

  1. Envoyez GET /api/v1/context pour vérifier l'identité de l'entreprise et le caller, les scopes, les capacités et les limites de l'API.
  2. Ouvrez le schéma de l'objet nécessaire, par exemple GET /api/v1/assets/schema, pour connaître ses champs, ses opérations, ses scopes et ses relations prises en charge.
  3. Récupérez les listes avec pagination et filtres. Les paramètres de filtrage sont décrits dans l'article de l'objet concerné.
  4. Lisez un enregistrement par son identifiant lorsque vous avez besoin des données actuelles et de son ETag.
  5. Créez, mettez à jour et supprimez les enregistrements en utilisant Idempotency-Key et, lorsque c'est requis, If-Match.
  6. Utilisez les relations, les fichiers, les opérations par lot et les actions spéciales uniquement via les chemins documentés pour l'objet concerné.

Format commun des réponses

Les réponses réussies renvoient les données dans la propriété data. Les informations techniques, comme requestId et parfois ETag, se trouvent dans meta. Conservez requestId dans le journal de l'intégration afin de retrouver rapidement une requête lors du diagnostic.

ETag, nouvelles tentatives et erreurs

L'ETag protège un enregistrement contre l'écrasement de modifications effectuées par une autre personne ou intégration. Après la lecture, enregistrez la valeur de l'en-tête ETag. Avant une mise à jour ou une suppression, envoyez-la dans If-Match. Après une modification réussie, utilisez la nouvelle valeur renvoyée par l'API.

  • 428 Precondition Required avec le code if_match_required indique l'absence de l'en-tête obligatoire If-Match ou Idempotency-Key.
  • 412 Precondition Failed avec le code if_match_failed indique que la valeur ETag utilisée n'est plus actuelle. Relisez l'enregistrement et décidez si la modification doit être répétée.
  • 429 Too Many Requests indique que la limite a été dépassée. Lisez l'en-tête Retry-After lorsqu'il est renvoyé et réessayez après ce délai, avec des délais progressivement plus longs.

Les erreurs suivent le format Problem Details. Les champs essentiels sont status, code, detail et requestId. Ne considérez pas le texte de detail comme un identifiant d'erreur stable : utilisez le champ code dans la logique de l'application.

Les réponses contiennent aussi des en-têtes de limite, notamment X-RateLimit-Limit et X-RateLimit-Remaining. L'intégration doit contrôler son rythme, gérer 429 et éviter une boucle de nouvelles tentatives trop agressive.

Articles API consacrés aux objets

Après avoir créé une clé et vérifié la connexion, choisissez l'article correspondant aux données à intégrer :

  • API - Actifs - ordinateurs, appareils, logiciels et autres éléments d'inventaire, avec leurs champs, relations et fichiers.
  • API - Documents - documents de l'entreprise, comme les factures, leurs données descriptives, fichiers et relations.
  • API - Clients / Employés - fiches clients ou employés, contacts, informations organisationnelles et relations prises en charge.
  • API - Fournisseurs - fiches fournisseurs et relations disponibles pour cet objet, notamment les documents et les notes.
  • API - Tickets - tickets du Service Desk, cycle de vie, champs opérationnels, fichiers et relations.
  • API - Changements - changements planifiés dans l'environnement IT, étapes de réalisation et données de contrôle du processus.
  • API - Problèmes - problèmes nécessitant une analyse de cause, un suivi de processus et des liens avec d'autres éléments.
  • API - Releases - planification et suivi des releases, statuts et informations sur les changements déployés.
  • API - Solutions - articles de la base de solutions et relations avec les problèmes.
  • API - Notes - notes, confidentialité, épinglage, fichiers et relations avec les enregistrements.
  • API - Approbations - processus d'approbation, données de décision, affectations et gestion du résultat.
  • API - Confirmations - confirmations nécessitant une décision du client, avec leurs fichiers et relations.
  • API - Tâches - tâches de travail, affectations, statuts, relations et pièces jointes.
  • API - Demandes - demandes de produits ou de services, données de réalisation, fichiers et relations.
  • API - Temps de travail - entrées de temps liées à un ticket, un changement, un problème, une release ou une tâche.

Liste de contrôle avant la mise en production

  • Créez une clé distincte pour chaque intégration et accordez uniquement les scopes nécessaires.
  • Conservez le Client ID et le Client Secret dans un coffre de secrets, jamais dans un dépôt ou dans du code envoyé au navigateur.
  • Définissez une durée d'activité adaptée à la gestion de l'intégration.
  • En production, utilisez HTTPS et une adresse de l'entreprise accessible au serveur d'intégration.
  • Journalisez requestId, le statut HTTP et le code d'erreur, mais masquez le Client Secret.
  • Gérez la pagination, les limites, 429, ETag et les nouvelles tentatives sécurisées.

Une fois ces points vérifiés, ouvrez l'article de l'objet choisi. Vous y trouverez les chemins, les champs et les exemples d'opérations propres à ce type de données.