Documents dans Codenica API

Dans l'API publique, le nom technique de cet objet est documents. Un document peut représenter une facture, un bon de commande, un contrat, un procès-verbal ou tout autre document conservé dans votre base de données. Les exemples utilisent un enregistrement de type invoice avec des données de facture envoyées par un système externe.

Avant d'envoyer votre première requête, créez la clé décrite dans l'article Codenica API - introduction. Les sections suivantes présentent le cycle complet d'un document : lecture du schéma et des listes, création et mise à jour, gestion des relations et des fichiers, opérations batch et suppression d'un enregistrement.

  • lire des listes de documents avec pagination, tri et filtres ;
  • lire les données de factures et d'autres types de documents ;
  • créer des enregistrements et appliquer des mises à jour partielles ;
  • protéger les modifications avec ETag et If-Match ;
  • répéter les opérations en toute sécurité avec Idempotency-Key ;
  • relier des documents entre eux et à d'autres objets ;
  • téléverser, télécharger, joindre et supprimer des fichiers ;
  • lire les statistiques, les valeurs de champs et exécuter des opérations groupées.

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 document utilisé avant d'écrire des données.

Documents - adresse API et choix du déploiement

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

{BASE_URL}/api/v1/documents

Pour Codenica Cloud, utilisez le domaine public 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 de l'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 correcte est sélectionnée à partir de l'adresse de l'hôte. N'essayez pas de la choisir avec tenantId, un champ supplémentaire dans la query string ou une valeur dans le body. N'utilisez pas localhost lorsque l'application d'intégration fonctionne sur un autre ordinateur que l'API. En production, utilisez HTTPS lorsque l'installation est publiée avec un certificat.

Documents - portées de la clé API

Créez la clé API dans Codenica, dans Settings - API - API Keys. Donnez-lui un nom qui identifie l'application et l'environnement, puis sélectionnez uniquement les portées nécessaires aux opérations sur les documents.

Le parcours complet de cet article nécessite :

  • documents:read - lister et lire les documents ;
  • documents:write - créer et mettre à jour ;
  • documents:delete - supprimer les documents ;
  • documents:schema - lire les champs et les cibles de relation ;
  • documents:stats - statistiques et valeurs de champs ;
  • documents:relationships:read et documents:relationships:write - lire et modifier les relations ;
  • documents:files:read et documents:files:write - gérer les fichiers.

Pour une intégration en lecture seule, documents:read et documents:schema suffisent généralement. Ajoutez les portées des statistiques, des relations et des fichiers uniquement si l'intégration en a besoin.

Les champs techniques peuvent nécessiter documents:technical:read et l'écriture des champs secrets documents:secrets:write. Après la création, enregistrez le Client ID et le Client Secret dans un stockage sécurisé. Le secret n'est affiché qu'au moment de la création ou de la rotation.

Documents - en-têtes d'authentification

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

export CLIENT_ID="cna_your_client_id"
export CLIENT_SECRET="cns_your_client_secret"

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

N'utilisez pas dans l'intégration le JWT Bearer d'un administrateur ni une session du panneau. Le JWT sert à connecter un utilisateur à Codenica ; la clé API relie une application externe à la base sélectionnée. Utilisez HTTPS en dehors d'un environnement de test local.

Ne stockez pas le secret dans un dépôt, une URL, des journaux, l'historique des commandes ou du code envoyé à un navigateur. Les exemples utilisent des valeurs fictives.

Documents - vérifier le contexte de l'installation

Lisez le contexte avant d'effectuer les opérations réelles :

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 portées nécessaires et la présence de documents dans capabilities.resources. Lisez également les limites de pagination, de téléversement et de requêtes.

Conservez meta.requestId. Si le contexte correspond à la mauvaise installation ou si une portée 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.

Documents - schéma des champs et des types

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

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

Pour itemType=invoice, vérifiez d'abord les champs obligatoires :

Champ
Type
Signification
date
dateTime
date du document
docNumber
string
numéro de facture ou de document

Le schéma décrit également readable, writable, required, technical, secretWriteOnly, les options, la longueur maximale, l'unicité et les règles de génération automatique. L'ensemble des champs n'est pas nécessairement identique dans chaque base.

Les champs key et keyType sont secrets. Ils ne sont pas renvoyés dans les réponses ordinaires et ne peuvent pas être utilisés pour filtrer, trier, calculer des statistiques ou rechercher des valeurs. Comparez le body au schéma avant de l'envoyer.

Documents - endpoints disponibles

La carte ci-dessous reprend les principales opérations. Remplacez les valeurs entre accolades par les identifiants renvoyés par l'API.

  • GET /api/v1/documents - liste ;
  • GET /api/v1/documents/schema - schéma des champs et des relations ;
  • GET /api/v1/documents/stats - statistiques ;
  • GET /api/v1/documents/values - valeurs de champs ;
  • GET /api/v1/documents/{id} - document individuel ;
  • POST /api/v1/documents - création ;
  • PATCH /api/v1/documents/{id} - mise à jour partielle ;
  • DELETE /api/v1/documents/{id} - suppression ;
  • POST /api/v1/documents:batch - opérations create, update et delete ;
  • GET /api/v1/documents/{id}/relationships - liste des relations ;
  • POST /api/v1/documents/{id}/relationships - ajouter une relation ;
  • POST /api/v1/documents/{id}/relationships:batch - modifier plusieurs relations ;
  • DELETE /api/v1/documents/{id}/relationships/{targetDataSet}/{targetId} - supprimer une relation ;
  • GET /api/v1/documents/{id}/files - liste des fichiers ;
  • POST /api/v1/documents/{id}/files - téléversement ;
  • POST /api/v1/documents/{id}/files/{fileId} - joindre un fichier existant ;
  • PUT /api/v1/documents/{id}/files/{fileId}/main - définir le fichier principal ;
  • DELETE /api/v1/documents/{id}/files/{fileId} - supprimer ou détacher un fichier ;
  • GET /api/v1/documents/{id}/files/{fileId}/content - télécharger le contenu.

Une réponse 403 signifie généralement que la clé ne possède pas la portée nécessaire ou que l'utilisateur associé ne dispose pas de l'autorisation requise.

Documents - liste et pagination

Lisez la liste page par page. Cet exemple renvoie les dix premiers documents invoice :

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&page=1&pageSize=10&sort=date&direction=desc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La réponse d'une 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 un tri explicite.

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

Documents - recherche et filtrage

L'exemple du test recherche un document par son identifiant personnalisé, son type et son statut :

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&customId=PUBLIC-API-DOC-20260905101715-SOURCE&status=Draft&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 schéma, vous pouvez utiliser notamment itemType, ids, search, customId, docNumber, name, status, category, currency, createdAfter, createdBefore, updatedAfter et updatedBefore.

Pour des conditions précises, utilisez filter :

filter=status:eq:Draft
filter=docNumber:contains:2026
filter=category:in:Procurement,Sales
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.

Documents - sélectionner les 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/documents?itemType=invoice&fields=id,itemType,customId,docNumber,name,status,total" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Utilisez include pour lire les fichiers et les relations avec l'enregistrement :

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID?include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

L'accès aux données incluses doit être accordé séparément. L'absence de documents:files:read ou de documents:relationships:read ne peut pas être contournée avec fields=*. Les champs techniques et secrets sont renvoyés uniquement lorsque les portées et le schéma l'autorisent.

Documents - créer un enregistrement

Utilisez POST /api/v1/documents pour créer un document. Placez le type dans itemType et les champs inscriptibles dans attributes. Cet exemple représente une facture envoyée par un système comptable :

export IDEMPOTENCY_KEY="documents-create-20260905-0001"

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --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 '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

Dans le schéma invoice testé, date et docNumber étaient obligatoires. Votre base peut demander d'autres champs ou valeurs. N'envoyez pas de champs en lecture seule ni d'id sauf si le schéma l'autorise explicitement.

Une réponse réussie 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 du document dans le système externe.

Documents - répéter une création en toute sécurité

Si un délai d'attente survient après l'envoi d'une facture, vous ne savez pas encore si l'enregistrement a été sauvegardé. Envoyez exactement la même requête avec la même Idempotency-Key et un body identique. Ne créez pas une nouvelle clé simplement parce que la première réponse n'est pas arrivée :

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --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 '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

La répétition idempotente renvoie le même document au lieu de créer un doublon. La même clé ne doit pas ensuite décrire un autre body, endpoint ou objectif. Une telle réutilisation renvoie 422 idempotency_key_reused. Utilisez une nouvelle valeur pour chaque nouvelle intention.

Documents - lire un enregistrement

Après avoir créé ou trouvé un document, lisez-le avec son UUID :

export DOCUMENT_ID="11111111-1111-1111-1111-111111111111"

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID?include=files,relationships" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La réponse contient id, itemType, les champs dans attributes et les métadonnées dans meta. L'ETag actuel se trouve dans l'en-tête HTTP et généralement aussi dans data.meta.etag et dans l'enveloppe meta.etag.

Lisez un ETag récent avant chaque modification du document, d'une relation ou d'un fichier. N'utilisez pas une valeur enregistrée auparavant si une autre personne ou intégration a pu modifier l'enregistrement.

Documents - mise à jour partielle avec ETag

PATCH modifie uniquement les champs envoyés dans le body. Il nécessite la valeur actuelle de If-Match et une nouvelle Idempotency-Key :

export CURRENT_ETAG='"etag-v1"'
export UPDATE_IDEMPOTENCY_KEY="documents-update-20260905-0001"

curl --request PATCH --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "Accept: application/json" \
  --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: $UPDATE_IDEMPOTENCY_KEY" \
  --data-raw '{
    "attributes": {
      "status": "Approved",
      "total": 1350.75,
      "description": "Invoice approved after verification in the accounting system."
    }
  }'

Il n'est pas nécessaire d'envoyer le document complet. Les champs absents du body restent inchangés. Après une opération réussie, enregistrez le nouvel ETag renvoyé par l'API.

Documents - se protéger contre une modification obsolète

L'API rejette une modification sans l'ETag actuel. L'absence de If-Match renvoie 428 if_match_required :

curl --request PATCH --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: documents-update-without-etag-0001" \
  --data-raw '{"attributes":{"status":"Approved"}}'

Si vous envoyez un ancien ETag, l'API renvoie 412 if_match_failed et laisse l'enregistrement inchangé. Relisez le document, examinez sa nouvelle version, puis décidez seulement ensuite s'il faut renvoyer votre modification.

{
  "status": 412,
  "code": "if_match_failed",
  "detail": "The supplied ETag is not the current document version.",
  "requestId": "request-id-from-response"
}

La même règle s'applique à la suppression du document, aux modifications de relations et aux opérations sur les fichiers lorsque le chemin modifie l'enregistrement.

Documents - relations et cibles compatibles

Un document peut être relié à un autre objet lorsque la cible est visible pour la clé et autorisée par le schéma. Vérifiez relationshipTargets dans la réponse du schéma avant d'envoyer une relation.

Envoyez targetId, targetDataSet, éventuellement targetItemType et relationshipType lorsque la cible sélectionnée le prend en charge. Cet exemple relie directement deux factures :

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-add-0001" \
  --data-raw '{
    "targetId": "22222222-2222-2222-2222-222222222222",
    "targetDataSet": "documents",
    "targetItemType": "invoice",
    "relationshipType": "related"
  }'

N'envoyez pas de targetItemType différent du type réel de la cible. Ne créez pas de relation vers le même enregistrement ni vers un enregistrement invisible pour la clé.

Documents - lire et supprimer des relations

Lisez la liste actuelle des relations séparément ou avec le document :

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

Pour supprimer une relation, lisez l'ETag récent du document et envoyez :

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/relationships/documents/$TARGET_DOCUMENT_ID?relationshipType=related&targetItemType=invoice" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-relationship-delete-0001"

Une suppression réussie renvoie 200 avec data=true. Relisez la liste après l'opération et enregistrez le nouvel ETag du document.

Documents - modifier plusieurs relations à la fois

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

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-batch-0001" \
  --data-raw '{
    "add": [
      {
        "targetId": "33333333-3333-3333-3333-333333333333",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ],
    "remove": [
      {
        "targetId": "22222222-2222-2222-2222-222222222222",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ]
  }'

La réponse indique les compteurs added, removed et skipped. Utilisez un ETag actuel même lorsque le batch ne contient qu'une modification. En cas de résultat partiel, examinez chaque élément avant une nouvelle tentative.

Documents - lister et téléverser un fichier

Les fichiers sont gérés séparément des champs du document. Commencez par lire la liste actuelle :

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/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. Cet exemple crée un fichier texte et le définit comme fichier principal :

printf 'Invoice attachment created by the ERP integration.\n' > invoice-primary.txt
export FILE_UPLOAD_ETAG='"etag-v1"'

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

La réponse contient id, fileName, contentType, size, relationshipType, isMain et downloadUrl. Cette URL est relative à BASE_URL.

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

Téléchargez le contenu du fichier avec l'endpoint content. Enregistrez-le comme contenu binaire :

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output downloaded-invoice-file

Vous pouvez téléverser un second fichier avec makeMain=false. Pour changer le fichier principal, lisez l'ETag actuel du document et appelez :

curl --request PUT --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$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: documents-file-main-0001"

Relisez la liste des fichiers après la modification. Un seul fichier doit avoir isMain=true. Enregistrez le nouvel ETag après l'opération.

Documents - joindre un fichier existant

Si un fichier est déjà conservé avec un autre document, joignez-le à un autre enregistrement sans téléverser à nouveau son contenu :

export TARGET_DOCUMENT_ID="11111111-1111-1111-1111-111111111111"
export EXISTING_FILE_ID="44444444-4444-4444-4444-444444444444"

curl --request POST --url "$BASE_URL/api/v1/documents/$TARGET_DOCUMENT_ID/files/$EXISTING_FILE_ID?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: documents-file-attach-0001"

La jointure crée une relation entre le document et le fichier. Le détachement avec DELETE /documents/{id}/files/{fileId} supprime la relation pour ce document, mais ne supprime pas un fichier appartenant à un autre document. La suppression du fichier depuis son document propriétaire est une opération distincte.

Documents - supprimer un fichier

Lisez une liste récente des fichiers et l'ETag du document avant de supprimer un fichier. Si vous supprimez le fichier principal actuel, le système peut sélectionner automatiquement un autre fichier principal :

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/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: documents-file-delete-0001"

Après une réponse 200, mettez à jour l'ETag et relisez la liste. La suppression du dernier fichier ne supprime pas le document ; elle laisse une collection de fichiers vide. Si le fichier était seulement joint au document, supprimez d'abord la relation et n'envisagez sa suppression que dans l'emplacement où il est stocké.

Documents - statistiques et valeurs de champs

Les statistiques montrent la répartition des données, tandis que l'endpoint values renvoie des valeurs utiles pour construire des filtres :

curl --request GET --url "$BASE_URL/api/v1/documents/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/documents/values?field=status&search=Draf&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Exemple de réponse de valeurs :

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

Les statistiques et les valeurs ne modifient pas les données. Ne les utilisez pas pour des champs secrets ou techniques sans la portée appropriée.

Documents - opérations batch

L'endpoint documents:batch permet de créer, mettre à jour et supprimer plusieurs documents dans une seule requête. Les opérations update et delete nécessitent leur propre ETag pour chaque élément :

curl --request POST --url "$BASE_URL/api/v1/documents:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: documents-batch-0001" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "invoice",
          "attributes": {
            "customId": "PUBLIC-API-DOC-20260905101715-TARGET-A",
            "date": "2026-09-05T10:18:00Z",
            "docNumber": "FV/2026/0002",
            "name": "Related invoice",
            "category": "Procurement",
            "type": "invoice",
            "status": "Draft",
            "currency": "PLN",
            "paymentMethod": "bank_transfer",
            "total": 510.00
          }
        }
      },
      {
        "operation": "update",
        "id": "11111111-1111-1111-1111-111111111111",
        "ifMatch": "\"etag-v1\"",
        "update": {
          "attributes": {
            "status": "Approved"
          }
        }
      },
      {
        "operation": "delete",
        "id": "22222222-2222-2222-2222-222222222222",
        "ifMatch": "\"etag-v3\""
      }
    ]
  }'

En cas de réussite complète, la réponse est 200 ; en cas de réussite partielle, 207. Le batch n'est pas une transaction tout ou rien. Enregistrez les identifiants, les ETags et les statuts de chaque opération.

Documents - supprimer un enregistrement

La suppression d'un document ne peut pas être annulée par l'API. Lisez l'ETag actuel et vérifiez l'UUID ainsi que l'adresse de la base :

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-delete-0001"

Une réponse correcte renvoie 200 et data=true. Une lecture ultérieure du document renvoie 404 document_not_found. Si l'enregistrement possède des relations ou des fichiers, sauvegardez hors du système les données nécessaires avant de le supprimer.

Documents - erreurs, limites et sécurité

Les erreurs utilisent le format Problem Details. Les champs les plus importants sont status, code, detail et requestId. Basez la logique de l'application sur le champ stable code.

  • 400 - champs, type de document ou relation non valides ;
  • 401 - identifiants absents ou invalides ;
  • 403 - portée ou autorisation manquante ;
  • 404 - document ou cible inexistant ou invisible ;
  • 409 - conflit de données ;
  • 412 - ETag obsolète ;
  • 413 - fichier trop volumineux ;
  • 428 - If-Match ou Idempotency-Key absent ;
  • 429 - limite de requêtes dépassée ;
  • 503 - service temporairement indisponible.

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. Masquez dans les journaux le Client Secret, les secrets des documents et le contenu des fichiers.

Documents - parcours complet d'intégration

  1. Créez une clé dans Settings - API - API Keys et accordez uniquement les portées nécessaires à l'intégration.
  2. Définissez BASE_URL sur l'adresse publique de Codenica Cloud ou sur l'adresse On-Premise communiquée par l'administrateur.
  3. Envoyez GET /api/v1/context et confirmez la bonne base, l'appelant, les portées et les limites.
  4. Lisez GET /api/v1/documents/schema et choisissez le type de document, les champs obligatoires et les valeurs acceptées.
  5. Lisez la liste paginée et filtrée ou récupérez un document par UUID.
  6. Créez une facture avec une Idempotency-Key unique, enregistrez son UUID et son ETag, puis répétez la requête identique après un délai d'attente.
  7. Mettez à jour l'enregistrement uniquement avec le If-Match actuel et enregistrez le nouvel ETag après chaque modification.
  8. Ajoutez, lisez et supprimez les relations autorisées par le schéma.
  9. Utilisez les endpoints de fichiers dédiés, en conservant l'ETag actuel et en distinguant la jointure de la suppression du fichier.
  10. Pour des volumes importants, utilisez stats, values et documents:batch, puis examinez le résultat de chaque opération.
  11. Avant la suppression, relisez le document, confirmez l'ETag correct et utilisez une nouvelle clé d'idempotence.

Ce parcours permet d'intégrer la gestion des factures et des autres documents dans un logiciel comptable, un outil de workflow documentaire, un ERP ou une application personnalisée.