Clients et employés dans Codenica API

Le nom technique de cette ressource dans l'API publique est clients, tandis que le type renvoyé par l'API est client. Cette collection permet de gérer les données des clients et des employés, selon le rôle, le type et les informations enregistrées dans votre base de données. Les requêtes utilisent une seule ressource et la distinction vient des valeurs des champs de l'enregistrement.

Avant d'envoyer votre première requête, préparez la clé décrite dans Codenica API - introduction. La suite de l'article présente le cycle complet : vérifier le schéma et les listes, créer et modifier les enregistrements, puis gérer les relations, les fichiers, les opérations batch et la suppression.

  • lire les listes de clients et d'employés avec pagination, tri et filtres ;
  • ne lire que les champs nécessaires à l'intégration ;
  • créer des enregistrements et appliquer des mises à jour partielles aux données de contact ou d'organisation ;
  • protéger les modifications avec ETag et If-Match ;
  • répéter les opérations en toute sécurité avec Idempotency-Key ;
  • relier les enregistrements aux actifs, aux documents, aux tickets et aux autres objets pris en charge ;
  • téléverser, télécharger, joindre et supprimer des fichiers ;
  • lire les statistiques, les valeurs de champs et exécuter des opérations batch.

Les champs obligatoires et les valeurs disponibles peuvent dépendre de la configuration de votre base de données. Lisez le schéma actuel du type de données utilisé avant toute écriture.

Clients et employés - adresse de l'API et choix de l'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 elle-même, d'un conteneur ou d'un port accessible uniquement à l'intérieur du serveur. Les chemins des clients et des employés commencent par :

{BASE_URL}/api/v1/clients

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

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

Dans l'installation On-Premise par défaut, l'adresse enregistrée localement par Codenica Discovery est :

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 fournie pour cette installation :

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

La base de données correcte est choisie à partir de l'adresse de l'hôte. N'essayez pas de la sélectionner avec tenantId, un champ supplémentaire dans la 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 que l'API. En production, utilisez HTTPS lorsque l'installation est publiée avec un certificat.

BASE_URL ne doit pas contenir le dernier /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 un domaine personnalisé ou un reverse proxy :
# export BASE_URL="https://api.votre-entreprise.example"

Clients et employés - clé API et scopes d'accès

Créez la clé de l'intégration externe dans Codenica, sous Paramètres - API - API Keys. Donnez-lui un nom qui décrit l'application, l'environnement et l'usage, par exemple CRM production - Clients. Sélectionnez ensuite uniquement les scopes nécessaires à cette intégration et enregistrez une seule fois le Client ID et le Client Secret affichés, dans un gestionnaire sécurisé de secrets.

Le parcours complet présenté dans cet article nécessite les scopes suivants :

  • clients:read, clients:write et clients:delete - lire, créer, modifier et supprimer des enregistrements ;
  • clients:schema - schéma des champs et cibles des relations ;
  • clients:stats - statistiques et valeurs de champs ;
  • clients:relationships:read et clients:relationships:write - lire et modifier les relations ;
  • clients:files:read et clients:files:write - gérer les fichiers.

Si l'intégration relie un enregistrement à un autre objet, elle a également besoin du scope de lecture de cette cible, par exemple assets:read pour les actifs existants. Le scope des relations clients ne remplace pas l'autorisation de lire l'objet cible.

Pour une intégration en lecture seule, ces scopes suffisent généralement :

clients:read
clients:schema

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

Licence
API publique
Clés actives
Starter
non disponible
0
Plus
disponible
50
Enterprise
disponible
100

Le panneau API affiche les clés créées et permet de les faire tourner ou de les supprimer. Une clé supprimée ne peut plus authentifier de requêtes et n'est plus comptée parmi les clés actives. Le Client Secret n'est affiché qu'au moment de la création ou de la rotation. Ne l'enregistrez pas dans un dépôt, une URL, des journaux, l'historique des commandes ou du code exécuté dans le navigateur.

Clients et employés - en-têtes d'authentification

L'application externe envoie des requêtes de serveur à serveur avec deux en-têtes :

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

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

N'utilisez pas le JWT Bearer de l'administrateur ni une session du panneau dans l'intégration. Le JWT sert à connecter un utilisateur à Codenica, tandis que la clé API relie une application externe à la base de données choisie. Utilisez HTTPS en dehors d'un environnement de test.

Les requêtes qui modifient les données nécessitent également un en-tête unique :

Idempotency-Key: public-api-clients-create-20260905104704

Après avoir lu un enregistrement, ajoutez son ETag actuel à toute requête qui modifie les données :

If-Match: "etag-client-actuel"

Ne générez pas de nouvelle clé d'idempotence pour répéter la même requête. La même clé et un body identique permettent de retrouver sans risque le résultat d'une opération qui a pu se terminer par un timeout.

Clients et employés - vérifier le contexte de l'installation

Avant de commencer la synchronisation, lisez le contexte :

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 clients dans capabilities.resources. Lisez également les limites de pagination, de téléversement et de requêtes.

Dans le parcours de test terminé, le contexte a confirmé notamment clients:read, clients:write, clients:delete, clients:schema, clients:stats, les scopes des relations et des fichiers, ainsi que la prise en charge des opérations batch, des relations, des fichiers, des ETags et de l'idempotence.

Conservez meta.requestId. Si le contexte indique une mauvaise installation ou si un scope manque, arrêtez la synchronisation et corrigez l'adresse ou la clé. N'essayez pas de changer de base dans le body de la requête.

Clients et employés - schéma des champs et types de données

Le schéma indique les champs qui peuvent être lus ou écrits et les valeurs acceptées dans votre base de données :

curl --request GET --url "$BASE_URL/api/v1/clients/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 client. Dans le schéma actuel, les champs suivants sont obligatoires et l'adresse e-mail est unique :

Champ
Type
Obligatoire
Unique
Signification possible
firstName
string
oui
non
prénom ou première partie d'un nom
lastName
string
oui
non
nom ou deuxième partie d'un nom
email
string
oui
oui
adresse de contact

Parmi les champs facultatifs fréquemment utilisés :

customId, displayName, gender, position, category, contractType,
type, role, status, phone, phoneWork, phoneMobile, address, country,
city, state, zipCode, location, department, section, roomNumber, tag,
link, number, value, isLicensed, isVerified, comments, description,
notification, preferredLanguage

Avant d'utiliser un champ supplémentaire, vérifiez dans le schema ses propriétés readable, writable, son type et sa longueur maximale. Ne supposez pas que les valeurs de status, type, category ou role sont identiques dans toutes les installations. La création d'un Client ne nécessite pas le itemType technique dans le body - l'API renvoie client.

Le schema confirme également les cibles de relations suivantes : assets, documents, tickets, notes, worktasks, confirmations et requesteditems. Dans le schema actuel, clients n'est pas une cible de relation Client vers Client.

Clients et employés - carte des endpoints

La carte suivante couvre les principales opérations. Remplacez les valeurs entre accolades par les identifiants reçus dans les réponses de l'API.

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

Une réponse 403 signifie généralement qu'il manque un scope à la clé ou que l'utilisateur associé à la clé ne possède pas l'autorisation nécessaire.

Clients et employés - liste et pagination

Lisez la liste page par page. Cet exemple renvoie les vingt premiers enregistrements :

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

La réponse de collection contient items, page, pageSize, totalItems, totalPages et hasNextPage. Continuez tant que hasNextPage vaut true. Si l'ordre est important pour la synchronisation, définissez toujours le tri explicitement.

Lisez la limite de pageSize dans le contexte. Ne supposez pas que la première page contient tous les enregistrements ni que l'ordre par défaut restera identique.

Clients et employés - recherche et filtrage

L'exemple du test recherche un enregistrement à partir de son identifiant, de son statut et de son type de données :

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

Selon le schema, vous pouvez utiliser notamment les paramètres ids, search, firstName, lastName, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter et updatedBefore.

Pour des conditions précises, utilisez filter :

filter=status:eq:Active
filter=displayName:contains:Public
filter=category:in:Customer,Employee
filter=description:notEmpty:

Les opérateurs comprennent eq, ne, in, contains, startsWith, endsWith, empty, notEmpty, gt, gte, lt et lte. Encodez selon les règles des URL les valeurs qui contiennent des espaces ou des caractères spéciaux.

Clients et employés - sélectionner des champs et inclure des données

Le paramètre fields limite la réponse aux champs nécessaires :

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

Pour lire les fichiers et les relations avec l'enregistrement, utilisez include :

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_RECORD_ID?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Dans le test, la réponse contenait les champs demandés ainsi que les collections files et relationships. L'accès en lecture aux données incluses doit être accordé séparément. L'absence de clients:files:read ou de clients:relationships:read ne peut pas être contournée avec fields=*.

Clients et employés - créer un enregistrement

Utilisez POST /api/v1/clients pour créer un enregistrement. Placez les champs inscriptibles dans attributes. L'exemple suivant montre un profil complet de client ou d'employé provenant d'un système CRM :

export IDEMPOTENCY_KEY="public-api-clients-create-source-20260905104704"

curl --request POST --url "$BASE_URL/api/v1/clients" \
  --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: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "attributes": {
      "customId": "PUBLIC-API-CLI-20260905104704-SOURCE",
      "firstName": "Public API",
      "lastName": "Client source 20260905104704",
      "displayName": "Public API client source 20260905104704",
      "email": "[email protected]",
      "category": "Customer",
      "type": "External",
      "role": "Customer",
      "status": "Active",
      "preferredLanguage": "fr",
      "phone": "+33 6 00 00 00 01",
      "department": "Customer Service",
      "description": "Source client used by the complete Public API Clients flow."
    }
  }'

Cette ressource n'exige pas l'itemType technique dans le body. L'API renvoie elle-même itemType: client. Dans le schema testé, firstName, lastName et un email unique étaient obligatoires. Votre base peut exiger d'autres champs ou d'autres valeurs.

Une réponse correcte a le statut 201 Created. Enregistrez data.id, l'ETag de l'en-tête HTTP et data.meta.etag. customId facilite la recherche ultérieure de l'enregistrement dans le système externe.

Clients et employés - répéter la création en toute sécurité

Si un timeout se produit après l'envoi des données et que vous ne savez pas si l'enregistrement a été sauvegardé, envoyez exactement la même requête avec le même Idempotency-Key et un body identique :

curl --request POST --url "$BASE_URL/api/v1/clients" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-clients-create-source-20260905104704" \
  --data-raw '{
    "attributes": {
      "customId": "PUBLIC-API-CLI-20260905104704-SOURCE",
      "firstName": "Public API",
      "lastName": "Client source 20260905104704",
      "displayName": "Public API client source 20260905104704",
      "email": "[email protected]",
      "category": "Customer",
      "type": "External",
      "role": "Customer",
      "status": "Active",
      "preferredLanguage": "fr",
      "phone": "+33 6 00 00 00 01",
      "department": "Customer Service",
      "description": "Source client used by the complete Public API Clients flow."
    }
  }'

Dans le test terminé, la seconde requête identique a renvoyé le même identifiant et le même ETag. Aucun second Client n'a été créé. Modifier le body ou réutiliser la même clé pour une autre opération n'est pas une répétition - créez une nouvelle clé pour une nouvelle opération.

Clients et employés - lire et modifier partiellement un enregistrement

Conservez l'UUID de l'enregistrement après sa création. Lisez un profil individuel ainsi :

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

PATCH ne modifie que les champs envoyés. Cet exemple met à jour le nom affiché et la description :

curl --request PATCH --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE" \
  --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-clients-update-source-20260905104704" \
  --data-raw '{
    "attributes": {
      "displayName": "Public API client source updated",
      "description": "Updated through the Codenica Public API Clients flow."
    }
  }'

Une mise à jour réussie renvoie 200 OK et un nouvel ETag. Remplacez l'ancien ETag par le nouveau après chaque modification. Les opérations sur les relations et les fichiers peuvent également changer la version de l'enregistrement : relisez donc l'ETag actuel avant toute nouvelle mutation.

Clients et employés - éviter d'écraser les modifications

Si une autre opération modifie l'enregistrement après que l'intégration a lu son ETag, l'ancienne valeur de If-Match est rejetée :

HTTP/1.1 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 client version.",
  "instance": "/api/v1/clients/{clientId}",
  "code": "if_match_failed",
  "requestId": "request-id-from-response"
}

Après cette erreur, ne remplacez pas l'enregistrement sans contrôle. Relisez le Client, comparez les changements, puis préparez un nouveau PATCH avec l'ETag actuel. Omettre If-Match pour une opération qui exige le contrôle de version renvoie :

HTTP/1.1 428 Precondition Required

{
  "code": "if_match_required",
  "status": 428,
  "detail": "Send the ETag returned by GET in the If-Match header."
}

Clients et employés - cibles de relations disponibles

Le schema actuel indique les ensembles de données cibles suivants :

  • assets - actifs, par exemple computer ;
  • documents - type de document renvoyé par le schema ;
  • tickets - type de ticket renvoyé par le schema ;
  • notes - type de note renvoyé par le schema ;
  • worktasks - type de tâche renvoyé par le schema ;
  • confirmations - type de confirmation renvoyé par le schema ;
  • requesteditems - type de demande renvoyé par le schema.

targetItemType doit correspondre au type réel de la cible. Dans le test terminé, deux actifs existants de type computer ont été sélectionnés dynamiquement. Si la relation pointe vers des actifs, la clé doit aussi disposer de assets:read. Pour les autres cibles, utilisez le scope de lecture correspondant.

Dans le schema actuel, clients n'est pas une cible de relation Client vers Client. Créez des relations uniquement avec les objets présents dans la réponse actuelle du schema.

Clients et employés - ajouter et lire des relations

Cet exemple relie l'enregistrement à un actif existant. Le body de la relation contient l'identifiant de la cible, son ensemble de données, son type et le type de relation :

{
  "targetId": "635d6518-1ac0-496a-abb7-95636b1b19b9",
  "targetDataSet": "assets",
  "targetItemType": "computer",
  "relationshipType": "related"
}
curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/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-clients-relationship-add-20260905104704" \
  --data @client-relationship.json

Un ajout réussi renvoie 201 Created et les informations de la cible, notamment targetId, targetDataSet, targetItemType, relationshipType, customId et name. Lisez la collection des relations ainsi :

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships?targetDataSet=assets&targetItemType=computer&relationshipType=related&page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La réponse utilise le même modèle de pagination que la liste des clients. Après l'ajout d'une relation dans le test, totalItems valait 1.

Clients et employés - relations batch et suppression d'un lien

Utilisez relationships:batch pour effectuer plusieurs modifications en une seule opération :

{
  "add": [
    {
      "targetId": "5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a",
      "targetDataSet": "assets",
      "targetItemType": "computer",
      "relationshipType": "related"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/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-clients-relationship-batch-20260905104704" \
  --data @client-relationship-batch.json

La réponse fournit les compteurs added, removed et skipped. Après le batch, relisez le nouvel ETag du Client.

Supprimez une relation individuelle avec :

curl --request DELETE --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships/assets/635d6518-1ac0-496a-abb7-95636b1b19b9?relationshipType=related" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-relationship-remove-20260905104704"

Le succès renvoie 200 OK avec data: true. Après la suppression de la dernière relation, la collection doit renvoyer totalItems: 0.

Clients et employés - liste des fichiers et téléversement

Les fichiers sont gérés séparément des champs de l'enregistrement. Un nouveau Client possède d'abord une collection vide :

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

Envoyez le fichier en multipart/form-data. L'exemple suivant crée un fichier documentaire principal :

curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/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-clients-file-upload-primary-20260905104704" \
  --form "[email protected];type=text/plain"

La réponse contient notamment id, fileName, contentType, size, relationshipType, isMain et un downloadUrl relatif. Le fichier de test clients-primary.txt faisait 62 octets. Après le téléversement, vérifiez la liste des fichiers, car elle indique l'état final de isMain.

Clients et employés - télécharger un fichier et changer le fichier principal

Téléchargez le contenu du fichier via l'endpoint content. Utilisez une sortie binaire :

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

Vous pouvez envoyer un second fichier avec makeMain=false :

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

Pour le définir comme fichier principal :

curl --request PUT --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files/$SECONDARY_FILE_ID/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-clients-file-set-main-20260905104704"

L'opération renvoie data: true. Ensuite, le premier fichier a isMain: false et le second isMain: true. L'ETag de l'enregistrement change : relisez-le avant la prochaine mutation.

Clients et employés - rattacher un fichier existant

Si un fichier est déjà enregistré auprès d'un Client, vous pouvez le rattacher à un autre enregistrement sans le téléverser de nouveau :

owner client: 8844622a-f948-4f2a-a718-81f61fa5ab21
target client: 3569dead-82b1-439e-8ecd-e4ee6b5f886b
file: cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4
curl --request POST --url "$BASE_URL/api/v1/clients/3569dead-82b1-439e-8ecd-e4ee6b5f886b/files/cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-attach-existing-20260905104704"

Vérifiez isMain dans la liste de fichiers du Client cible, et pas seulement dans la réponse directe de l'opération de rattachement. Détachez le fichier avec :

curl --request DELETE --url "$BASE_URL/api/v1/clients/3569dead-82b1-439e-8ecd-e4ee6b5f886b/files/cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-detach-20260905104704"

Le détachement retire le fichier du Client cible, mais ne supprime pas le fichier du Client propriétaire.

Clients et employés - supprimer un fichier

Avant de supprimer un fichier, lisez une liste récente et l'ETag de l'enregistrement. Si vous supprimez le fichier principal actuel, le système peut choisir automatiquement un autre fichier comme fichier principal :

curl --request DELETE --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files/$FILE_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-clients-file-delete-20260905104704"

Après une réponse 200, mettez à jour l'ETag et vérifiez la liste. La suppression du dernier fichier ne supprime pas l'enregistrement du client ou de l'employé : elle laisse une collection de fichiers vide. Si le fichier était seulement rattaché à l'enregistrement, retirez le rattachement, puis envisagez sa suppression à l'endroit où il est stocké.

Clients et employés - statistiques et valeurs de champs

Les statistiques montrent la répartition des données, tandis que l'endpoint values renvoie les valeurs utiles à la construction de filtres :

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

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

Dans le test, les statistiques comprenaient notamment les statuts aktywny, Active, w magazynie et Urlop płatny. Un résultat mélangé est possible lorsque les données viennent de sources différentes : ne supposez pas que les statuts seront uniquement en français ou dans une seule langue.

Exemple de réponse values :

{
  "data": {
    "field": "status",
    "values": ["Active"]
  },
  "meta": {
    "requestId": "request-id-from-response"
  }
}

Les statistiques et les valeurs ne modifient pas les données. Utilisez values pour construire les filtres et les suggestions au lieu d'intégrer des dictionnaires en dur.

Clients et employés - création par batch

Le batch permet de créer plusieurs enregistrements dans une seule requête. Un élément de création contient operation: create et un objet create avec attributes :

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "PUBLIC-API-CLI-20260905104704-BATCH-A",
          "firstName": "Public API",
          "lastName": "Clients batch A 20260905104704",
          "displayName": "Public API clients batch A 20260905104704",
          "email": "[email protected]",
          "category": "Customer",
          "role": "Customer",
          "status": "Active",
          "description": "Client created by the Public API batch flow."
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "PUBLIC-API-CLI-20260905104704-BATCH-B",
          "firstName": "Public API",
          "lastName": "Clients batch B 20260905104704",
          "displayName": "Public API clients batch B 20260905104704",
          "email": "[email protected]",
          "category": "Employee",
          "role": "Employee",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/clients: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-clients-batch-create-20260905104704" \
  --data @clients-batch-create.json

Dans le test terminé, la réponse avait 200 OK, succeeded: 2, failed: 0 et deux éléments avec le statut d'opération 201. Conservez séparément chaque nouvel UUID et chaque ETag.

Clients et employés - mise à jour par batch et réussite partielle

Une mise à jour exige id, l'ifMatch actuel et un objet update. L'exemple suivant contient aussi un élément invalide pour illustrer une réponse partielle :

{
  "items": [
    {
      "operation": "update",
      "id": "942f8323-bb7b-4915-80a9-81eaae657cb8",
      "ifMatch": "\"3drgMRaLiRYP6p6nCd6JDh_UHVRhYIAwWFDO4YLOUvc\"",
      "update": {
        "attributes": {
          "displayName": "Public API client batch A updated",
          "description": "Updated inside a partial Clients batch."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/clients: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-clients-batch-partial-20260905104704" \
  --data @clients-batch-partial.json

Dans le test, la réponse était 207 Multi-Status :

{
  "data": {
    "succeeded": 1,
    "failed": 1,
    "items": [
      {"operation": "update", "status": 200},
      {
        "operation": "invalid",
        "status": 400,
        "error": {"code": "invalid_batch_item"}
      }
    ]
  }
}

207 ne signifie pas un échec total. Vérifiez le résultat de chaque opération séparément et prévoyez un ifMatch distinct pour une opération delete :

{
  "operation": "delete",
  "id": "4db45845-ddec-4740-bb4b-f3c57836d3b5",
  "ifMatch": "\"NAHxuB2XecVkevWAbNdCeT6aQkwyyYHc_TDtgLvfI_U\""
}

Clients et employés - supprimer un enregistrement

La suppression d'un profil est irréversible depuis l'API. Commencez par lire l'ETag actuel :

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

Envoyez ensuite DELETE :

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

Le succès renvoie 200 OK et data: true. Une lecture ultérieure renvoie 404 Not Found avec le code client_not_found. Un filtrage sur le préfixe PUBLIC-API-CLI-20260905104704 doit renvoyer totalItems: 0.

Clients et employés - erreurs, limites et sécurité

Les erreurs sont renvoyées au format Problem Details. Les champs les plus importants sont status, code, detail et requestId. Fondez la logique de l'application sur le champ stable code.

  • 400 - champs, type de cible ou élément batch non valides ;
  • 401 - identifiants manquants ou invalides ;
  • 403 - scope ou autorisation manquant ;
  • 404 - enregistrement, fichier ou cible inexistant ou non visible ;
  • 409 - conflit de données, par exemple une adresse e-mail déjà utilisée ;
  • 412 - ETag obsolète ;
  • 413 - fichier dépassant la limite ;
  • 422 - erreur de validation métier ;
  • 428 - If-Match ou Idempotency-Key manquant ;
  • 429 - limite de requêtes dépassée ;
  • 503 - service temporairement indisponible ;
  • 207 - batch exécuté partiellement.

Lisez X-RateLimit-Limit et X-RateLimit-Remaining. En cas de 429, utilisez Retry-After s'il est renvoyé et augmentez le délai entre les tentatives successives. Ne journalisez pas X-Codenica-Client-Secret, les secrets ni le contenu sensible des fichiers.

Clients et employés - cycle complet d'intégration

  1. Définissez BASE_URL avec l'adresse réelle de Codenica Cloud ou On-Premise.
  2. Créez une clé sous Paramètres - API - API Keys, sélectionnez les scopes minimum et enregistrez le secret dans un gestionnaire d'identifiants.
  3. Lisez /api/v1/context et confirmez la bonne base, le caller, les scopes et les limites.
  4. Lisez /api/v1/clients/schema et vérifiez les champs obligatoires, les valeurs et les cibles de relations.
  5. Envoyez un GET filtré avec un customId unique afin d'écarter un doublon.
  6. Créez l'enregistrement du client ou de l'employé avec un Idempotency-Key unique.
  7. Conservez l'UUID et l'ETag de la réponse. Si la réponse est perdue, répétez la création à l'identique avec la même clé.
  8. Lisez le profil avec fields et, si nécessaire, include=files,relationships.
  9. Modifiez les champs avec PATCH, l'If-Match actuel et une nouvelle clé d'idempotence.
  10. Ajoutez, lisez et supprimez uniquement les relations autorisées par le schema. Vérifiez le targetItemType de la cible.
  11. Gérez les fichiers avec les endpoints dédiés en conservant l'ETag actuel et en distinguant le rattachement de la suppression.
  12. Après chaque téléversement, rattachement, changement de fichier principal et DELETE, vérifiez la liste des fichiers.
  13. Utilisez stats et values pour synchroniser les filtres et les dictionnaires.
  14. Pour les volumes importants, utilisez clients:batch et gérez les réponses 200 et 207.
  15. Avant la suppression, lisez l'ETag, envoyez DELETE et confirmez le code client_not_found.

Les exemples de cet article proviennent d'un parcours utilisant le préfixe PUBLIC-API-CLI-20260905104704. Votre intégration doit utiliser les identifiants reçus de votre base et non les valeurs de démonstration.

context = GET /api/v1/context
schema = GET /api/v1/clients/schema

client = POST /api/v1/clients
  Idempotency-Key: unique-create-key

client = GET /api/v1/clients/{id}
etag = client.data.meta.etag

updated = PATCH /api/v1/clients/{id}
  If-Match: etag
  Idempotency-Key: unique-update-key

relationship = POST /api/v1/clients/{id}/relationships
  If-Match: updated-etag
  Idempotency-Key: unique-relationship-key

files = GET /api/v1/clients/{id}/files

deleted = DELETE /api/v1/clients/{id}
  If-Match: latest-etag
  Idempotency-Key: unique-delete-key