API - tâches

Les Tâches dans Codenica API

Avant d'envoyer la première requête concernant une Tâche, créez une clé API dans les paramètres de Codenica. Si aucune clé n'est encore disponible, ouvrez Codenica API - introduction dans un nouvel onglet. Cet article présente les règles communes de création des clés, d'authentification, d'utilisation de l'adresse API et de conservation sécurisée du secret.

Une Tâche permet d'enregistrer une activité précise, une responsabilité ou un travail à réaliser. Un enregistrement peut contenir une échéance, un statut, une priorité, une catégorie, une description, un lieu, un service, un lien et des tags. Une Tâche peut également être liée à d'autres objets utilisés dans le Service Desk et la gestion des actifs.

Dans le contrat de l'API, un enregistrement porte la valeur worktask dans itemType et la collection d'endpoint s'appelle worktasks. Les exemples contiennent des valeurs de démonstration sûres. Remplacez les identifiants, les adresses et les dates par ceux de votre intégration.

Tâches - adresse de l'API et choix de l'installation

Toutes les routes des Tâches commencent par :

{BASE_URL}/api/v1/worktasks

BASE_URL désigne l'adresse de l'application Codenica sans le suffixe /api/v1. N'ajoutez pas le nom de la base de données ni l'identifiant de l'entreprise à cette adresse.

Codenica Cloud : utilisez le domaine ou le sous-domaine attribué à l'entreprise :

export BASE_URL="https://{domaine-de-votre-entreprise}"

Codenica On-Premise : l'adresse locale enregistrée par défaut par Codenica Discovery est :

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

Si l'administrateur a publié l'installation sur un domaine d'entreprise, en HTTPS, derrière un reverse proxy ou sur un autre port, utilisez l'adresse exacte communiquée pour cette installation. Consultez les instructions d'installation de Codenica On-Premise pour les détails du déploiement. Utilisez localhost uniquement dans un environnement de test local volontaire, lorsque le client HTTP et l'API fonctionnent sur le même ordinateur.

N'envoyez pas tenantId dans le body ni dans les paramètres de requête. La bonne base de données est sélectionnée à partir de l'adresse et de l'hôte de la requête.

Tâches - clé API et limites de licence

Créez la clé dans Paramètres -> API -> API Keys. Une clé distincte pour chaque application et chaque environnement facilite le contrôle des accès. Donnez-lui un nom explicite et sélectionnez uniquement les scopes nécessaires aux Tâches.

La suppression d'une clé supprime son enregistrement et libère une place dans la limite. L'expiration bloque l'authentification, mais ne remplace pas le nettoyage de la liste. Si aucune date de fin n'est choisie, la période d'activité par défaut est de 90 jours ; la durée maximale d'une clé est de 5 ans.

Tâches - authentification des requêtes

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

X-Codenica-Client-Id: {CLIENT_ID}
X-Codenica-Client-Secret: {CLIENT_SECRET}
Accept: application/json

Exemple de première lecture :

export PUBLIC_API_CLIENT_ID="cna_votre_client_id"
export PUBLIC_API_CLIENT_SECRET="cns_votre_client_secret"

curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/context"

Une intégration externe n'a pas besoin de la session du panneau ni du Bearer JWT de l'utilisateur. Conservez le secret côté serveur ou dans un gestionnaire de secrets. Ne le placez pas dans le code du navigateur, un dépôt, une URL, l'historique du shell ou les journaux.

Tâches - vérification du contexte de connexion

Lisez le contexte avant de récupérer une liste ou de créer la première Tâche. Vous vérifierez ainsi que l'adresse mène à la bonne base de données et que la clé possède les scopes et les limites nécessaires.

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/context" | jq

Dans la réponse, vérifiez data.tenant.id, data.tenant.name, data.tenant.subdomain, data.tenant.resolvedDomain, data.caller.clientId et data.caller.scopes. Vérifiez aussi que les capacités comprennent supportsRelationships, supportsFiles, supportsETag et supportsIdempotency.

{
  "data": {
    "apiVersion": "v1",
    "caller": {
      "authentication": "api_key",
      "clientId": "{CLIENT_ID}",
      "scopes": [
        "worktasks:read",
        "worktasks:write"
      ]
    },
    "capabilities": {
      "supportsETag": true,
      "supportsIdempotency": true,
      "supportsRelationships": true,
      "supportsFiles": true
    }
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Si le contexte indique une autre entreprise ou ne contient pas le scope nécessaire, arrêtez l'intégration et corrigez l'adresse ou la clé. N'essayez pas de changer de base de données en ajoutant un identifiant externe au body.

Tâches - schema et champs pris en charge

Le schema est la source d'information sur la configuration actuelle des Tâches. Il renvoie les types de champs, les valeurs requises, la possibilité d'écriture, les champs techniques et les cibles de relations disponibles dans l'installation.

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/schema" | jq

{
  "data": {
    "itemType": "worktask",
    "fields": [
      {
        "name": "customId",
        "type": "string",
        "readable": true,
        "writable": true,
        "required": false
      },
      {
        "name": "title",
        "type": "string",
        "readable": true,
        "writable": true,
        "required": false
      }
    ],
    "relationshipTargets": [
      {
        "targetDataSet": "assets",
        "targetItemType": "asset"
      },
      {
        "targetDataSet": "tickets",
        "targetItemType": "ticket"
      }
    ]
  }
}

Ne supposez pas que toutes les bases de données ont la même configuration. Avant de mapper les champs, lisez le schema actuel et respectez readable, writable, required, technical et maxLength.

Tâches - champs modifiables et champs système

Les champs suivants sont destinés à l'objet attributes. Si le schema de l'installation actuelle indique d'autres limites, il est prioritaire.

Le champ pin est en lecture seule et se modifie avec la route dédiée /pin. Les champs techniques comme authorId, agentId, workTimeId, creator, updater, dateCreated, dateUpdated, importId, importSource et dateImported sont complétés par le système. Ne les envoyez pas lors d'une création normale ni dans un PATCH. La valeur de itemType doit toujours être worktask.

Tâches - principaux endpoints

La liste suivante présente les principales opérations disponibles pour l'objet worktask. Ajoutez uniquement le scope nécessaire à l'opération souhaitée.

Tâches - liste et pagination

Lisez la liste des Tâches page par page. Définissez explicitement le tri afin que les lectures successives gardent un ordre prévisible :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks?page=1&pageSize=25&sort=dateCreated&direction=desc" | jq

Dans la réponse, lisez data.items, page, pageSize, totalItems, totalPages et hasNextPage. Lorsque hasNextPage vaut true, demandez la page suivante. Vérifiez la taille maximale de page dans data.capabilities.limits.maxPageSize du contexte.

Le paramètre ids sert à demander certains UUID. Pour une synchronisation, il est préférable de conserver un customId stable dans l'application d'intégration, puis d'enregistrer l'UUID renvoyé par Codenica API.

Tâches - recherche et filtres

La liste accepte la recherche textuelle, la correspondance sur certains champs et un filtre structurel. Les paramètres courants sont customId, search, title, status, priority, category, location, department, tag, createdAfter, createdBefore, updatedAfter et updatedBefore.

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks?search=poste&filter=status%3Aeq%3AOpen&sort=dateDue&direction=asc&page=1&pageSize=25" | jq

Un filtre suit la forme field:operator:value. Exemples d'opérateurs :

status:eq:Open
priority:ne:Low
title:startswith:Préparer
description:contains:poste
dateDue:gte:2026-09-01T00:00:00Z

Les raccourcis =, !=, ge, le, sw et ew correspondent respectivement à l'égalité, l'inégalité, supérieur ou égal, inférieur ou égal, startswith et endswith. Encodez dans l'URL les valeurs qui contiennent des caractères spéciaux.

Tâches - sélection des champs et données incluses

Le paramètre fields limite les champs renvoyés dans l'enregistrement. La réponse est ainsi plus petite et plus simple à traiter :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks?fields=customId,title,status,priority,dateDue&page=1&pageSize=25" | jq

Si des données liées sont nécessaires, utilisez include :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/{WORKTASK_ID}?fields=%2A&include=files%2Crelationships%2Cusers" | jq

Les données incluses n'augmentent pas les permissions de la clé. Pour voir les fichiers, les relations ou les utilisateurs, la clé doit disposer de worktasks:files:read, worktasks:relationships:read et worktasks:users:read. Utilisez fields=* uniquement si les champs techniques sont réellement nécessaires.

Tâches - statistiques et valeurs des champs

Les statistiques permettent de créer des synthèses sans télécharger toute la collection. Exemple : compter les Tâches par statut :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/stats?field=status&limit=20" | jq

{
  "data": {
    "total": 42,
    "field": "status",
    "values": [
      { "value": "Open", "count": 12 },
      { "value": "In progress", "count": 18 },
      { "value": "Closed", "count": 12 }
    ]
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

L'endpoint values renvoie les valeurs d'un champ correspondant à une recherche. Il peut notamment alimenter les suggestions d'un formulaire :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/values?field=category&search=oper&limit=20" | jq

Ces deux routes sont en lecture seule et nécessitent le scope worktasks:stats.

Tâches - création minimale

Une écriture minimale doit contenir itemType et un objet attributes. En pratique, attribuez immédiatement votre propre customId et un titre :

{
  "itemType": "worktask",
  "attributes": {
    "customId": "ERP-WORKTASK-2026-0042",
    "title": "Préparer un poste de travail",
    "status": "Open",
    "priority": "High",
    "category": "IT"
  }
}

Requête de création de l'enregistrement :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json, application/problem+json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Idempotency-Key: erp-worktask-create-2026-0042" \
  --data-raw '{
    "itemType": "worktask",
    "attributes": {
      "customId": "ERP-WORKTASK-2026-0042",
      "title": "Préparer un poste de travail",
      "status": "Open",
      "priority": "High",
      "category": "IT"
    }
  }' \
  "$BASE_URL/api/v1/worktasks" | jq

Une réponse réussie renvoie le statut 201 Created. Enregistrez data.id et l'ETag de l'enregistrement pour la suite.

Tâches - création complète

L'exemple suivant enregistre les données généralement nécessaires pour transmettre une Tâche depuis un outil de planification :

{
  "itemType": "worktask",
  "attributes": {
    "customId": "ERP-WORKTASK-2026-0042",
    "title": "Préparer un poste pour une nouvelle personne",
    "description": "Installez l'ordinateur, configurez l'accès au réseau et confirmez que le poste est prêt.",
    "status": "Open",
    "priority": "High",
    "category": "Onboarding",
    "dateDue": "2026-09-30T12:00:00Z",
    "location": "Cracovie",
    "department": "IT",
    "tag": "onboarding,poste-de-travail",
    "link": "https://portal.example.com/tasks/ERP-WORKTASK-2026-0042"
  }
}

Les valeurs de statut, de priorité et de catégorie doivent correspondre à la configuration de votre base de données. L'API ne crée pas automatiquement un nouveau dictionnaire parce qu'une intégration envoie un nouveau libellé.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json, application/problem+json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Idempotency-Key: erp-worktask-create-2026-0042" \
  --data-binary @worktask.json \
  "$BASE_URL/api/v1/worktasks" | jq

Tâches - Idempotency-Key et nouvelles tentatives sûres

Toute mutation effectuée avec une clé API nécessite l'en-tête Idempotency-Key. Sa valeur identifie une intention métier unique. Pour répéter la même requête, conservez la même clé et ne modifiez pas le body. Pour une nouvelle Tâche ou une autre opération, générez une autre valeur.

--header "Idempotency-Key: erp-worktask-create-2026-0042"

Si la connexion est interrompue après l'envoi de la requête, répétez d'abord la requête à l'identique avec la même clé. Ne créez pas immédiatement une nouvelle clé, car cela peut produire un doublon. Sans cet en-tête, la mutation renvoie 428 avec le code idempotency_key_required.

Tâches - lecture d'un enregistrement

Après la création, lisez l'enregistrement avec l'UUID renvoyé dans data.id :

export WORKTASK_ID="{UUID_DE_LA_REPONSE_CREATE}"

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID?fields=customId,title,status,priority,category,dateDue,description" | jq

Un enregistrement contient id, itemType, attributes et meta. Lisez l'ETag dans meta : il sera nécessaire pour la prochaine mutation.

{
  "data": {
    "id": "{WORKTASK_ID}",
    "itemType": "worktask",
    "attributes": {
      "customId": "ERP-WORKTASK-2026-0042",
      "title": "Préparer un poste pour une nouvelle personne",
      "status": "Open"
    },
    "meta": {
      "customId": "ERP-WORKTASK-2026-0042",
      "etag": "{CURRENT_ETAG}"
    }
  },
  "meta": {
    "requestId": "{REQUEST_ID}",
    "etag": "{CURRENT_ETAG}"
  }
}

Tâches - modification avec ETag et If-Match

Avant toute modification, lisez l'enregistrement actuel et conservez la valeur exacte de l'ETag, guillemets compris lorsqu'ils en font partie :

ETAG=$(curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID?fields=customId,title,status,priority,description" \
  | jq -r '.data.meta.etag // .meta.etag')

PATCH ne modifie que les attributs sélectionnés. Après réussite, enregistrez le nouvel ETag :

curl --fail-with-body --silent --show-error \
  --request PATCH \
  --header "Accept: application/json, application/problem+json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-update-2026-0042" \
  --data-raw '{
    "attributes": {
      "title": "Configurer le poste pour une nouvelle personne",
      "status": "In progress",
      "priority": "Normal",
      "description": "L'ordinateur et l'accès au réseau sont en cours de configuration."
    }
  }' \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID" | jq

N'utilisez pas un ETag enregistré avant une autre modification. Toute mutation réussie peut changer la version de l'enregistrement.

Tâches - ETag obsolète ou manquant

Si une autre personne ou intégration a modifié la Tâche, un ancien ETag entraîne 412 Precondition Failed avec le code if_match_failed. L'API ne doit pas appliquer la modification refusée.

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

PATCH, DELETE, les relations, les fichiers et l'épinglage sans If-Match requis renvoient 428 Precondition Required avec le code if_match_required. Après 412, relisez l'enregistrement, décidez s'il faut conserver la modification locale, puis envoyez seulement une nouvelle requête contrôlée.

Tâches - épingler et désépingler

Le champ pin est en lecture seule dans attributes. Modifiez-le avec l'endpoint dédié :

POST /api/v1/worktasks/{WORKTASK_ID}/pin

Épinglage au niveau 3 :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-pin-2026-0042" \
  --data '{"pin":3}' \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/pin" | jq

La valeur null désépingle la Tâche :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $NEW_ETAG" \
  --header "Idempotency-Key: erp-worktask-unpin-2026-0042" \
  --data '{"pin":null}' \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/pin" | jq

Relisez la Tâche après chacune de ces opérations, car son ETag peut changer.

Tâches - relations utilisateur : auteur et agent

La relation utilisateur possède sa propre route et permet de lire l'auteur de la Tâche ainsi que l'agent affecté :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/user-relationships?page=1&pageSize=20" | jq

La collection contient uniquement des relations de type author ou agent. Exemple d'élément :

{
  "targetId": "{USER_ID}",
  "targetDataSet": "users",
  "relationshipType": "agent",
  "displayName": "Anne Martin",
  "email": "[email protected]",
  "role": "Agent"
}

authorId et agentId sont des champs techniques. N'essayez pas de les modifier avec un PATCH attributes normal. Si la version de l'API propose une action d'affectation séparée, suivez son schema et le scope requis.

Tâches - relations d'objets autorisées

Le schema des Tâches expose onze groupes d'objets pouvant servir de cibles de relations :

Pour assets, le type dépend de l'actif précis. Le tableau utilise computer comme exemple ; avant d'enregistrer la relation, lisez l'itemType réel de l'objet sélectionné.

Tâches - choix de targetItemType et format de relation

targetItemType doit correspondre au type réel de l'objet cible. L'ordre le plus sûr est le suivant : lisez la liste ou le schema de la cible, récupérez son itemType, puis construisez le body de la relation.

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/assets?page=1&pageSize=10&sort=dateCreated&direction=desc" | jq '.data.items[0] | {id, itemType}'

Les relations d'objets des Tâches n'acceptent pas le champ relationshipType. Envoyez uniquement l'identifiant, le nom de la collection et le type d'objet :

{
  "targetId": "{ASSET_ID}",
  "targetDataSet": "assets",
  "targetItemType": "computer"
}

Ne copiez pas asset, document ou task sans vérifier la cible précise. Un type incorrect entraîne une erreur de validation.

Tâches - ajouter, lire et supprimer une relation

L'ajout d'une relation avec un actif nécessite l'ETag actuel de la Tâche et une clé d'idempotence distincte :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-relation-assets-2026-0042" \
  --data '{
    "targetId": "{ASSET_ID}",
    "targetDataSet": "assets",
    "targetItemType": "computer"
  }' \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships" | jq

Lisez la relation avec un filtre de collection :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships?targetDataSet=assets&page=1&pageSize=100" | jq

Suppression d'une seule relation :

curl --fail-with-body --silent --show-error \
  --request DELETE \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-relation-delete-assets-2026-0042" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships/assets/{ASSET_ID}" | jq

Après la suppression, la réponse doit contenir data=true. L'ajout d'une nouvelle relation renvoie 201 Created ; dans certaines situations, le renvoi d'une relation déjà existante peut renvoyer 200 OK.

Tâches - relations batch

Ajoutez ou supprimez plusieurs relations dans une seule requête :

{
  "add": [
    {
      "targetId": "{DOCUMENT_ID}",
      "targetDataSet": "documents",
      "targetItemType": "document"
    }
  ],
  "remove": [
    {
      "targetId": "{ASSET_ID}",
      "targetDataSet": "assets",
      "targetItemType": "computer"
    }
  ]
}

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-relationships-batch-2026-0042" \
  --data-binary @worktask-relationships.json \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships:batch" | jq

{
  "data": {
    "added": 1,
    "removed": 1,
    "skipped": 0
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Les relations batch n'acceptent pas non plus relationshipType. Utilisez l'ETag actuel de la Tâche et lisez la limite d'éléments dans le contexte. Enregistrez le nouvel ETag s'il est renvoyé, puis relisez la collection pour vérifier le résultat.

Tâches - liste des fichiers et upload

Les fichiers associés à une Tâche sont gérés par un groupe d'endpoint distinct. Commencez par lire la liste :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files?page=1&pageSize=100" | jq

Un élément de la liste contient notamment id, fileName, contentType, size, relationshipType, isMain et downloadUrl. Envoyez un nouveau fichier en multipart/form-data :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $ETAG" \
  --header "Idempotency-Key: erp-worktask-file-upload-2026-0042" \
  --form "file=@./instructions-poste.pdf;type=application/pdf" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files?relationshipType=instruction" | jq

L'upload nécessite worktasks:files:write, l'ETag actuel et la limite de fichier lue dans le contexte. Pour les Tâches, l'API définit isMain=false ; ne prévoyez pas d'opération séparée pour un fichier principal.

Tâches - télécharger et joindre un fichier

Téléchargez le contenu du fichier avec la route content et enregistrez-le en mode binaire :

curl --fail-with-body --silent --show-error \
  --output ./instructions-poste-telechargees.pdf \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files/{FILE_ID}/content"

Si un fichier est déjà enregistré dans le système, joignez-le à une deuxième Tâche sans renvoyer son contenu. Lisez d'abord l'ETag de cette deuxième Tâche :

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $SECOND_WORKTASK_ETAG" \
  --header "Idempotency-Key: erp-worktask-file-attach-2026-0042" \
  "$BASE_URL/api/v1/worktasks/$SECOND_WORKTASK_ID/files/{FILE_ID}?relationshipType=reference" | jq

Attach crée une relation de fichier avec la deuxième Tâche. Le même fichier peut être visible dans les deux enregistrements ; reference est le type de relation du fichier, pas celui d'une relation d'objet.

Tâches - détacher et supprimer un fichier

Détachez le fichier de la deuxième Tâche avec son ETag actuel :

curl --fail-with-body --silent --show-error \
  --request DELETE \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $SECOND_WORKTASK_ETAG" \
  --header "Idempotency-Key: erp-worktask-file-detach-2026-0042" \
  "$BASE_URL/api/v1/worktasks/$SECOND_WORKTASK_ID/files/{FILE_ID}" | jq

Le détachement doit renvoyer data=true sans supprimer la relation du fichier avec la Tâche source. Pour supprimer le fichier de la source, lisez son nouvel ETag et exécutez :

curl --fail-with-body --silent --show-error \
  --request DELETE \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $SOURCE_WORKTASK_ETAG" \
  --header "Idempotency-Key: erp-worktask-file-delete-2026-0042" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files/{FILE_ID}" | jq

Vérifiez la liste des fichiers après la suppression. Les Tâches ne possèdent pas de route distincte pour définir un fichier principal.

Tâches - opérations batch sur les enregistrements

L'endpoint /api/v1/worktasks:batch regroupe la création, la modification et la suppression de Tâches. Chaque élément de modification ou de suppression possède son propre ETag :

{
  "items": [
    {
      "operation": "create",
      "create": {
        "itemType": "worktask",
        "attributes": {
          "customId": "ERP-WORKTASK-BATCH-A",
          "title": "Préparer les accès",
          "status": "Open",
          "priority": "Normal",
          "category": "IT"
        }
      }
    },
    {
      "operation": "update",
      "id": "{WORKTASK_ID}",
      "ifMatch": "{CURRENT_ETAG}",
      "update": {
        "attributes": {
          "title": "Préparer les accès - deuxième étape",
          "status": "In progress"
        }
      }
    },
    {
      "operation": "delete",
      "id": "{OTHER_WORKTASK_ID}",
      "ifMatch": "{OTHER_CURRENT_ETAG}"
    }
  ]
}

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Idempotency-Key: erp-worktasks-batch-2026-0042" \
  --data-binary @worktasks-batch.json \
  "$BASE_URL/api/v1/worktasks:batch" | jq

{
  "data": {
    "items": [
      {
        "index": 0,
        "operation": "create",
        "status": 201,
        "id": "{CREATED_WORKTASK_ID}",
        "data": {
          "meta": {
            "etag": "{CREATED_ETAG}"
          }
        }
      }
    ],
    "succeeded": 1,
    "failed": 0
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

En cas de résultat partiel, l'API peut renvoyer 207 Multi-Status. Parcourez data.items, vérifiez chaque élément et ne relancez que les opérations qui nécessitent réellement une nouvelle tentative.

Tâches - supprimer un enregistrement

Avant la suppression, relisez l'enregistrement, vérifiez son UUID et son ETag actuel, puis utilisez une nouvelle clé d'idempotence :

curl --fail-with-body --silent --show-error \
  --request DELETE \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: erp-worktask-delete-2026-0042" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID" | jq

Une réponse réussie contient 200 OK et data=true. Après la suppression, vérifiez que l'enregistrement n'est plus disponible :

curl --fail-with-body --silent --show-error \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/worktasks/$WORKTASK_ID"

Le statut attendu est 404 Not Found. Vous pouvez également filtrer la liste avec customId=ERP-WORKTASK-2026-0042 et confirmer que totalItems=0.

Tâches - erreurs, limites et ordre sûr des opérations

Les réponses d'erreur utilisent le format Problem Details. Utilisez code dans la logique d'intégration et conservez aussi requestId pour signaler un problème. Ne placez ni le secret ni les en-têtes complets dans les journaux.

Lisez les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining. À 429, appliquez des délais croissants avec un décalage aléatoire, limitez le nombre de tentatives et n'effectuez jamais de boucle infinie pour 400, 401, 403, 404 ou 412.

Ordre sûr des opérations

1. Définissez BASE_URL de l'installation correcte et lisez le context.
2. Vérifiez les scopes, les limites, le schema et l'itemType réel des cibles de relations.
3. Créez une Tâche avec son propre Idempotency-Key, puis enregistrez l'UUID et l'ETag.
4. Avant chaque modification, relation, opération de fichier ou épinglage, lisez l'ETag actuel.
5. Après une mutation réussie, enregistrez le nouvel ETag et vérifiez le résultat par une lecture.
6. Après la synchronisation, vérifiez l'enregistrement avec customId et supprimez les données de démonstration avec une requête distincte.
7. Dans n8n, utilisez le nœud HTTP Request ; conservez le Client ID et le Client Secret dans credentials et transmettez l'UUID, l'ETag et la clé d'idempotence entre les nœuds.