Les fournisseurs dans Codenica API

Le nom technique de cette ressource dans la Public API est vendors et le type renvoyé par l'API est vendor. Une fiche fournisseur peut contenir le nom de l'entreprise, les coordonnées, les informations d'immatriculation, le statut et une description de la relation commerciale.

Avant d'envoyer votre première requête, préparez la clé décrite dans Codenica API - introduction. Le parcours ci-dessous couvre toutes les étapes : consulter le schéma et les listes, créer et modifier un fournisseur, gérer les cibles de relation autorisées, utiliser les fichiers, traiter des opérations batch et supprimer une fiche.

  • lire les listes de fournisseurs avec pagination, tri et filtres ;
  • ne demander que les champs nécessaires à l'intégration ;
  • créer des fiches fournisseurs et appliquer des mises à jour partielles ;
  • protéger les modifications avec ETag et If-Match ;
  • répéter les opérations d'écriture en toute sécurité grâce à Idempotency-Key ;
  • utiliser les cibles de relation exposées par le schéma des fournisseurs ;
  • téléverser, télécharger, rattacher et supprimer des fichiers ;
  • lire les statistiques, les valeurs de champs et traiter des opérations batch.

Les champs obligatoires et les valeurs acceptées peuvent dépendre de la configuration de votre base de données. Consultez le schéma actuel avant toute écriture.

Fournisseurs - adresse de l'API et type d'installation

Envoyez les requêtes à l'adresse publique à laquelle votre installation Codenica est accessible. N'utilisez pas l'adresse de la base de données, d'un conteneur ou d'un port accessible uniquement à l'intérieur du serveur. Les chemins des fournisseurs commencent par :

{BASE_URL}/api/v1/vendors

Dans Codenica Cloud, utilisez le domaine attribué à votre installation :

export BASE_URL="https://votre-entreprise.codenica.com"

Dans l'installation On-Premise par défaut, Codenica Discovery enregistre le service localement à l'adresse suivante :

export BASE_URL="http://codenica.local:5150"

Si l'administrateur a publié l'installation On-Premise avec un domaine d'entreprise, un reverse proxy, HTTPS ou un autre port externe, utilisez l'adresse exacte qui vous a été communiquée :

export BASE_URL="https://api.votre-entreprise.example"

La base de données est sélectionnée à partir de l'adresse de l'hôte. Ne la sélectionnez pas avec tenantId, un paramètre supplémentaire de query string ou une valeur dans le body. N'utilisez pas localhost si le programme d'intégration s'exécute sur un autre ordinateur.

BASE_URL ne doit pas contenir le suffixe final /api/v1 :

# Codenica Cloud :
export BASE_URL="https://votre-entreprise.codenica.com"

# On-Premise par défaut avec Codenica Discovery :
# export BASE_URL="http://codenica.local:5150"

# On-Premise avec une adresse publiée par l'administrateur :
# export BASE_URL="https://api.votre-entreprise.example"

Fournisseurs - clé API et scopes d'accès

Créez la clé destinée à une intégration externe dans Codenica, sous Paramètres - API - Clés API. Donnez-lui un nom qui indique l'application, l'environnement et l'usage, par exemple Achats - Fournisseurs - production. Sélectionnez uniquement les scopes nécessaires, puis enregistrez une seule fois le Client ID et le Client Secret affichés dans un coffre-fort de secrets.

Le parcours complet de cet article nécessite :

  • vendors:read, vendors:write et vendors:delete - lecture, création, modification et suppression des fiches ;
  • vendors:schema - champs et cibles de relation ;
  • vendors:stats - statistiques et valeurs de champs ;
  • vendors:relationships:read et vendors:relationships:write - lecture et modification des relations ;
  • vendors:files:read et vendors:files:write - opérations sur les fichiers.

Si l'intégration lit des Documents ou une autre cible de relation, ajoutez également son scope de lecture, par exemple documents:read. Le scope des relations fournisseurs ne remplace pas l'accès à l'objet cible.

Une intégration en lecture seule nécessite généralement :

vendors:read
vendors:schema

Les limites de clés dépendent de la licence :

Licence
Public API
Nombre maximal de clés
Starter
indisponible
0
Plus
disponible
50
Enterprise
disponible
100

Le panneau API conserve les clés créées pour votre base de données. Une clé distincte pour chaque application et chaque environnement facilite le contrôle des accès, la rotation d'un secret ou la suppression d'une intégration sans interrompre les autres. Une clé supprimée ne peut plus authentifier de requêtes et n'est pas comptée comme active.

Le Client Secret n'est affiché qu'à la création ou à la rotation d'une clé. Ne le stockez pas dans un dépôt, une URL, des journaux, l'historique des commandes ou du code exécuté dans le navigateur.

Fournisseurs - en-têtes d'authentification

L'application externe envoie des requêtes de serveur à serveur avec deux en-têtes qui identifient la clé :

export CLIENT_ID="cna_votre_client_id"
export CLIENT_SECRET="cns_votre_client_secret"

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

Dans ce scénario, n'envoyez ni JWT d'administrateur ni cookies de session du panneau. L'intégration utilise la clé API attribuée à cette base de données et une installation de production doit être accessible en HTTPS.

Toute opération qui modifie les données nécessite un en-tête unique :

Idempotency-Key: public-api-vendors-create-20260905111218

Les mises à jour, les suppressions, les changements de relation et les opérations sur les fichiers nécessitent l'ETag actuel de la fiche :

If-Match: "etag-actuel-du-fournisseur"

Après chaque modification réussie, enregistrez le nouvel ETag renvoyé dans l'en-tête et dans data.meta.etag. Pour répéter la même opération logique, conservez le même Idempotency-Key et un body identique.

Fournisseurs - vérifier le contexte de l'installation

Lisez le contexte avant de commencer la synchronisation :

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"

Vérifiez apiVersion, contractVersion, l'identifiant de la base, tenant.resolvedDomain, caller.authentication égal à api_key, les scopes requis et la présence de vendors dans capabilities.resources. Lisez également les limites de pagination, de fichiers, de batch et de requêtes.

Une intégration complète doit normalement exposer supportsBatch, supportsRelationships, supportsFiles, supportsETag et supportsIdempotency. Conservez meta.requestId de chaque réponse. Il est nécessaire pour analyser une erreur ou contacter l'administrateur.

Si le contexte indique une autre base ou si un scope nécessaire manque, arrêtez la synchronisation et corrigez l'adresse ou la clé. N'essayez pas de modifier la base dans le body de la requête.

Fournisseurs - schéma des champs et cibles de relation

Lisez le schéma avant la première écriture :

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

Dans la réponse, data.itemType vaut vendor. Le schéma indique le type du champ, s'il peut être lu ou écrit, son caractère obligatoire, sa longueur maximale, son unicité et sa génération automatique. Dans le schéma actuel, name est obligatoire et peut contenir 300 caractères au maximum :

Champ
Type
Obligatoire
Limite
Signification
name
string
oui
300
nom du fournisseur

Les champs les plus courants appartiennent à plusieurs groupes :

  • identification : customId, name, displayName, type, category, role, status ;
  • localisation : location, department, address, city, country, state, zipCode ;
  • contact : email, phone, phoneWork, phoneMobile, contactName, contactPhone, contactMobile, contactEmail ;
  • registres et repères : website, tag, taxId, idNumber, registryNumber, link, number ;
  • description et état : comments, description, notification, value, isLicensed, isVerified.

Le schéma renvoie également le catalogue des cibles de relation. Dans le modèle actuel des fournisseurs, il s'agit de documents, notes, worktasks et requesteditems. Ne supposez pas que toutes les ressources visibles dans le contexte peuvent être une cible de relation.

Fournisseurs - carte des endpoints

Cette carte regroupe les principales opérations sur les fiches fournisseurs. Remplacez les valeurs entre accolades par les UUID renvoyés dans les réponses précédentes.

  • GET /api/v1/vendors - liste ;
  • GET /api/v1/vendors/schema - schéma des champs et des relations ;
  • GET /api/v1/vendors/stats - statistiques ;
  • GET /api/v1/vendors/values - valeurs de champs ;
  • GET /api/v1/vendors/{id} - fiche unique ;
  • POST /api/v1/vendors - création ;
  • PATCH /api/v1/vendors/{id} - mise à jour partielle ;
  • DELETE /api/v1/vendors/{id} - suppression ;
  • POST /api/v1/vendors:batch - opérations de création, mise à jour et suppression ;
  • GET /api/v1/vendors/{id}/relationships - liste des relations ;
  • POST /api/v1/vendors/{id}/relationships - ajout d'une relation ;
  • POST /api/v1/vendors/{id}/relationships:batch - modification groupée des relations ;
  • DELETE /api/v1/vendors/{id}/relationships/{targetDataSet}/{targetId} - suppression d'une relation ;
  • GET /api/v1/vendors/{id}/files - liste des fichiers ;
  • POST /api/v1/vendors/{id}/files - téléversement ;
  • POST /api/v1/vendors/{id}/files/{fileId} - rattachement d'un fichier existant ;
  • PUT /api/v1/vendors/{id}/files/{fileId}/main - définition du fichier principal ;
  • DELETE /api/v1/vendors/{id}/files/{fileId} - suppression d'un fichier ;
  • GET /api/v1/vendors/{id}/files/{fileId}/content - téléchargement du contenu.

Si un endpoint renvoie 403, vérifiez d'abord le scope attribué à la clé, puis les autorisations de son propriétaire.

Fournisseurs - liste, tri et pagination

Lisez la liste page par page. Cet exemple renvoie les vingt premières fiches et les trie par nom :

curl --request GET --url "$BASE_URL/api/v1/vendors?page=1&pageSize=20&sort=name&direction=asc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

L'enveloppe de collection contient items, page, pageSize, totalItems, totalPages et hasNextPage. Lorsque hasNextPage vaut true, lisez la page suivante. Pour une synchronisation reproductible, définissez explicitement le tri.

Lisez la limite pageSize dans le contexte. Ne supposez pas que la première page contient toutes les fiches ni que l'ordre par défaut restera inchangé.

Fournisseurs - recherche et filtrage

Après la création d'une fiche, retrouvez-la avec son identifiant interne et son statut :

curl --request GET --url "$BASE_URL/api/v1/vendors?customId=PUBLIC-API-VEN-20260905111218-SOURCE&status=Active&sort=customId&direction=asc&page=1&pageSize=10" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Utilisez search pour rechercher un texte :

curl --request GET --url "$BASE_URL/api/v1/vendors?search=technology&page=1&pageSize=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Selon le schéma, vous pouvez notamment utiliser ids, search, name, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter et updatedBefore.

Pour des conditions plus précises, utilisez filter :

filter=status:eq:Active
filter=name:contains:Technology
filter=category:in:Technology,Hardware
filter=description:notEmpty:

Les opérateurs permettent de comparer des valeurs, de rechercher un fragment de texte, de choisir une valeur parmi plusieurs et de tester les champs vides. Encodez les espaces et les caractères spéciaux selon les règles des URL avant d'envoyer le filtre.

Fournisseurs - sélectionner les champs et inclure des données

Le paramètre fields limite la réponse aux propriétés nécessaires à l'intégration :

curl --request GET --url "$BASE_URL/api/v1/vendors?fields=id,itemType,customId,displayName,email,status" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Utilisez include pour lire les fichiers et les relations avec la fiche :

curl --request GET --url "$BASE_URL/api/v1/vendors/a8156781-3b1c-4fa5-9cf2-05077e5d1399?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La réponse peut contenir les attributs demandés ainsi que les collections files et relationships. L'accès aux données incluses doit être accordé séparément. L'absence de vendors:files:read ou de vendors:relationships:read ne peut pas être contournée par fields=*.

Fournisseurs - créer une fiche

Utilisez POST /api/v1/vendors pour créer une fiche. Placez les champs inscriptibles dans attributes. La requête minimale exige name, mais il est utile d'envoyer immédiatement l'identifiant du système source et les coordonnées principales :

{
  "attributes": {
    "customId": "ERP-VENDOR-2026-001",
    "name": "Northwind Technology Services",
    "displayName": "Northwind Technology Services",
    "email": "[email protected]",
    "category": "Technology",
    "type": "Supplier",
    "role": "Supplier",
    "status": "Active",
    "description": "Fournisseur de services d'infrastructure informatique."
  }
}
curl --request POST --url "$BASE_URL/api/v1/vendors" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001" \
  --data @vendor-create.json

Une réponse correcte renvoie le statut 201 Created. Enregistrez data.id, data.meta.etag et l'en-tête HTTP ETag. Dans la fiche de démonstration, l'API a renvoyé itemType: vendor et l'identifiant a8156781-3b1c-4fa5-9cf2-05077e5d1399.

Fournisseurs - répéter la création en toute sécurité

Si un délai d'attente survient ou si la réponse est perdue après l'envoi, ne créez pas immédiatement une seconde fiche. Répétez exactement la même requête avec la même clé :

Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001

Le body doit être identique et la clé doit être réservée à cette seule opération logique. La répétition avec la même clé ne créera pas un second fournisseur. Ne réutilisez pas cette clé pour une autre fiche, une mise à jour ou une suppression.

L'idempotence s'applique aux opérations d'écriture. Chaque nouvelle écriture doit recevoir une clé unique.

Fournisseurs - lire une fiche

Après sa création ou sa recherche, lisez la fiche avec l'UUID renvoyé par l'API :

VENDOR_ID="a8156781-3b1c-4fa5-9cf2-05077e5d1399"

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

La réponse 200 OK contient data.itemType: vendor ; l'ETag actuel se trouve dans l'en-tête HTTP et dans data.meta.etag. N'utilisez pas l'identifiant du système source à la place de l'UUID, sauf si vous avez d'abord recherché la fiche.

Fournisseurs - mise à jour partielle avec ETag

Commencez par lire la fiche et utilisez l'ETag renvoyé. PATCH ne modifie que les propriétés transmises dans attributes :

CURRENT_ETAG='"ao_LJiJqs-uhBu9oDENCFJH6JY8qwbl_vt77Gl5cjGQ"'

curl --request PATCH --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-update-20260905111218" \
  --data '{"attributes":{"displayName":"Northwind Technology Services - service achats","description":"Données fournisseur mises à jour par l'intégration."}}'

Une réponse réussie renvoie 200 OK. N'envoyez pas les propriétés que vous ne voulez pas modifier. Après l'opération, remplacez l'ETag enregistré par la nouvelle valeur, par exemple "ek44P2KnmKSAB1xX4Ycs_NgIn0I3NLoDdqsezEUgBTY".

Fournisseurs - éviter d'écraser une modification

Si deux processus ont lu la même fiche, le second peut déjà posséder une version obsolète. La Public API rejette cette mise à jour avec le code if_match_failed et le statut 412 Precondition Failed :

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current vendor version.",
  "code": "if_match_failed"
}

L'absence de If-Match lors d'une mise à jour ou d'une suppression renvoie 428 Precondition Required avec le code if_match_required. Après un 412 ou un 428, relisez la fiche, examinez son état actuel et décidez seulement ensuite s'il faut recommencer. N'envoyez pas un ETag choisi au hasard.

Fournisseurs - catalogue limité des relations

Tout objet disponible dans le système ne peut pas être une cible de relation d'un fournisseur. La source de vérité est relationshipTargets, renvoyé par /api/v1/vendors/schema. Le modèle actuel expose :

documents
notes
worktasks
requesteditems

Ne reliez pas les fournisseurs à clients ni à assets. Ne déduisez pas la prise en charge d'une autre collection simplement parce qu'elle apparaît dans capabilities.resources. La liste des ressources de l'installation est plus large que celle des cibles de relation d'un objet donné.

Les relations entre objets fournisseurs n'utilisent pas relationshipType. Ne l'envoyez pas dans le body et n'ajoutez pas relationshipType=related à la query string. Si un endpoint de fichiers utilise relationshipType=documentation ou relationshipType=manual, cette valeur est une métadonnée du fichier et ne représente pas une relation avec un autre objet.

Fournisseurs - ajouter et lire une relation

Lisez un ETag récent du fournisseur avant de modifier une relation. Le body contient la cible, la collection et, lorsque l'objet cible l'exige, son targetItemType :

{
  "targetId": "31fe2881-6236-4100-9a87-2c018cbaf709",
  "targetDataSet": "documents",
  "targetItemType": "warranty"
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-document-a-20260905111218" \
  --data '{"targetId":"31fe2881-6236-4100-9a87-2c018cbaf709","targetDataSet":"documents","targetItemType":"warranty"}'

Un ajout réussi renvoie 201 Created. Lisez ensuite les relations séparément :

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships?targetDataSet=documents&page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La réponse contient notamment targetId, targetDataSet, targetItemType, customId et status. La liste des relations ne contient pas de paramètre relationshipType.

Fournisseurs - batch de relations et suppression d'un lien

Utilisez relationships:batch pour ajouter ou supprimer plusieurs relations dans une seule requête :

{
  "add": [
    {
      "targetId": "31eed973-79cf-4650-ac0e-1e3ef5513d9f",
      "targetDataSet": "documents",
      "targetItemType": "warranty"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-batch-20260905111218" \
  --data @vendor-relationships-batch.json

Le résultat contient les compteurs added, removed et skipped. Supprimez une relation avec :

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships/documents/31fe2881-6236-4100-9a87-2c018cbaf709" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-delete-20260905111218"

N'ajoutez pas relationshipType. Relisez la collection après l'opération pour confirmer l'état de la relation.

Fournisseurs - lister les fichiers

Les fichiers forment une collection distincte rattachée à la fiche fournisseur :

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Une collection vide contient notamment items: [], totalItems: 0 et hasNextPage: false. Après chaque opération sur un fichier, relisez la collection : elle montre les valeurs réelles de isMain, de relationshipType, de la taille et de l'adresse de téléchargement.

Fournisseurs - téléverser un fichier

Lisez l'ETag actuel du fournisseur avant le téléversement. L'envoi utilise une requête multipart :

curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?makeMain=true&relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-upload-20260905111218" \
  --form "[email protected];type=text/plain"

Ici, relationshipType=documentation décrit le fichier et non une relation entre objets. La réponse 201 Created contient notamment l'identifiant du fichier, son nom, son type de contenu, sa taille et downloadUrl. Confirmez dans la liste que le fichier possède isMain: true.

Lisez la limite d'envoi dans data.capabilities.limits.maxUploadBytes. Dans l'installation d'exemple, elle était de 20971520 octets.

Fournisseurs - télécharger un fichier et changer le fichier principal

Téléchargez le contenu avec downloadUrl ou avec l'endpoint équivalent :

FILE_ID="025222b9-abef-4bad-a2ba-28229a0d73fb"

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output vendors-primary-downloaded.txt

La réponse doit contenir 200 OK, le bon Content-Type et un en-tête Content-Disposition. Pour ajouter un second fichier sans modifier le fichier principal, utilisez makeMain=false et, par exemple, relationshipType=manual. Définissez-le ensuite comme fichier principal :

curl --request PUT --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124/main" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-set-main-20260905111218"

Après une nouvelle lecture, le nouveau fichier doit avoir isMain: true et le précédent isMain: false.

Fournisseurs - rattacher un fichier existant

Vous pouvez rattacher à une autre fiche un fichier conservé avec un fournisseur sans téléverser à nouveau son contenu. Il s'agit d'une opération sur un fichier : relationshipType est donc une métadonnée du fichier :

TARGET_VENDOR_ID="4bfece8f-5bb3-438c-a95b-f14ccf93cce3"
TARGET_ETAG='"l5sRayy308rVRi4PNmUReFFcJGowi0KZUi8-hOGGlr0"'

curl --request POST --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-attach-20260905111218"

Le détachement supprime le rattachement chez le fournisseur cible sans supprimer le fichier de la fiche propriétaire :

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-detach-20260905111218"

Après le détachement, vérifiez la liste des fichiers du fournisseur cible et du propriétaire.

Fournisseurs - supprimer un fichier

La suppression d'un fichier nécessite également l'ETag actuel de la fiche fournisseur :

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-delete-20260905111218"

Si vous supprimez le fichier principal actuel, le système peut choisir automatiquement un autre fichier restant comme fichier principal. Après 200 OK, relisez la liste et vérifiez totalItems et isMain. Détacher un fichier n'est pas la même chose que supprimer le fichier conservé chez son propriétaire.

Fournisseurs - statistiques et valeurs de champs

Les statistiques aident à voir la répartition des données dans les fiches fournisseurs :

curl --request GET --url "$BASE_URL/api/v1/vendors/stats?field=status&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Le résultat peut contenir le nombre total de fiches, le nom du champ et les valeurs accompagnées de compteurs. Les valeurs proviennent de votre base de données. Par exemple, active, Active et fournisseur actif peuvent être des entrées différentes si elles proviennent de sources distinctes.

Utilisez l'endpoint values pour construire des suggestions de filtres :

curl --request GET --url "$BASE_URL/api/v1/vendors/values?field=status&search=Act&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Les statistiques et les valeurs sont des opérations en lecture seule et ne modifient pas les données.

Fournisseurs - création par batch

Un batch permet de créer plusieurs fiches dans une seule requête. Chaque élément contient operation: create et un objet create :

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-A",
          "name": "Northwind Batch A",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-B",
          "name": "Northwind Batch B",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/vendors:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-batch-create-20260905111218" \
  --data @vendors-batch-create.json

Le résultat contient le statut de la requête complète et le statut de chaque opération dans data.items. Un batch réussi peut renvoyer 200 OK, succeeded: 2, failed: 0 et deux éléments au statut 201. Enregistrez chaque UUID et chaque ETag séparément.

Fournisseurs - mise à jour, suppression et réussite partielle par batch

Une mise à jour par batch exige id, l'ifMatch actuel et un objet update :

{
  "items": [
    {
      "operation": "update",
      "id": "76d1698d-dfdb-47a3-9d84-3e476fa7894c",
      "ifMatch": "ETAG_FROM_GET",
      "update": {
        "attributes": {
          "displayName": "Northwind Batch A - mise à jour",
          "description": "Modification effectuée par l'opération batch des fournisseurs."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}

Si une opération réussit et qu'une autre est invalide, l'API renvoie 207 Multi-Status. Ne considérez pas 207 comme un échec total ni comme une réussite totale. Traitez chaque élément de data.items séparément. La suppression suit la même règle : envoyez l'identifiant et l'ifMatch actuel :

{
  "operation": "delete",
  "id": "9462d541-c405-44bf-9c75-000d8b862136",
  "ifMatch": "ETAG_FROM_GET"
}

Après une suppression par batch, effectuez un GET de contrôle. La fiche supprimée doit renvoyer 404 avec le code vendor_not_found.

Fournisseurs - supprimer une fiche

Relisez la fiche avant sa suppression afin de disposer d'un ETag actuel :

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-delete-20260905111218"

Une suppression réussie renvoie 200 OK et data: true. Une lecture ultérieure renvoie 404 Not Found avec le code vendor_not_found. Vous pouvez également filtrer sur votre customId et confirmer totalItems: 0.

Si la réponse DELETE a été perdue, n'envoyez pas immédiatement une nouvelle opération avec une autre clé. Conservez l'Idempotency-Key initial, vérifiez l'état de la fiche et décidez ensuite de la suite.

Fournisseurs - erreurs, limites et parcours d'intégration

Les erreurs de la Public API utilisent le format Problem Details. Fondez la logique de l'application sur le champ stable code et conservez requestId lorsqu'un problème est signalé.

  • 400 - champ, cible de relation ou élément batch invalide ;
  • 401 - identifiants absents ou invalides ;
  • 403 - scope ou autorisation manquant ;
  • 404 - fiche, fichier ou cible inexistante ou invisible ;
  • 409 - conflit de données ou d'unicité ;
  • 412 - ETag obsolète ;
  • 413 - fichier trop volumineux ;
  • 422 - erreur de validation métier ;
  • 428 - If-Match ou Idempotency-Key manquant ;
  • 429 - limite de requêtes dépassée ;
  • 207 - batch partiellement exécuté.

Lisez X-RateLimit-Limit et X-RateLimit-Remaining. Pour 429, utilisez Retry-After lorsqu'il est renvoyé et augmentez le délai entre les tentatives. Ne journalisez jamais X-Codenica-Client-Secret, les secrets ou le contenu sensible des fichiers.

Ordre conseillé :

  1. Définissez BASE_URL sur l'installation correcte.
  2. Créez une clé dans Paramètres - API - Clés API avec les scopes minimaux.
  3. Lisez /api/v1/context et /api/v1/vendors/schema.
  4. Créez un fournisseur avec un Idempotency-Key unique, puis conservez son UUID et son ETag.
  5. Lisez les listes avec pagination, filtres et include facultatif.
  6. Modifiez la fiche uniquement avec l'If-Match actuel.
  7. Ajoutez des relations uniquement vers les cibles du schéma et sans relationshipType.
  8. Utilisez les endpoints de fichiers dédiés et contrôlez la liste après chaque changement.
  9. Pour les volumes importants, examinez le résultat de chaque opération batch.
  10. Relisez l'ETag actuel avant suppression et effectuez un GET de contrôle ensuite.

Les exemples utilisent le préfixe de démonstration PUBLIC-API-VEN-20260905111218. Votre intégration doit utiliser les identifiants renvoyés par votre propre base, et non les valeurs affichées sur cette page.