API Dynamic Assets

Cette documentation constitue un guide complet pour l'intégration avec l'API Dynamic Assets de Hyperfox. L'API vous permet de gérer des structures de données dynamiques via une interface RESTful avec authentification OAuth 2.0.

Concepts

Modèle de données : Master Data et Reference Data

Hyperfox repose sur une architecture flexible qui s'appuie sur des assets dynamiques pouvant varier d'une configuration à l'autre.

Chaque configuration comprend un ensemble standard d'assets et de champs qui sont déployés automatiquement et ne peuvent pas être modifiés par les utilisateurs. Ces données sont appelées Master Data (données de base). Les Master Data représentent la structure de données centrale et immuable qui constitue le socle de chaque configuration Hyperfox.

Chaque configuration peut définir des assets personnalisés afin de répondre à des besoins métier spécifiques. Ces données sont appelées Reference Data (données de référence). La structure des Reference Data peut être modifiée pour répondre à des besoins particuliers.

Aspect	Master Data	Reference Data
Personnalisable	Non	Oui
Indicateur	`supporting_data: false`	`supporting_data: true`
Exemples	`dyn_stock_order`, `dyn_order_line`	`dyn_item`, `dyn_party`
Déploiement	Automatique, standard	Automatique et configurable

Modèles de configuration

Chaque modèle dispose de sa propre structure de Master Data, adaptée à son cas d'usage spécifique. La structure des assets diffère selon le modèle de configuration suivi par votre implémentation.

Modèle Stock

Optimisé pour les scénarios de gestion des stocks et d'entrepôt. Vous trouverez plus de détails sur la structure de données ici.

Asset	Utilité	Supporting Data
`dyn_stock_order`	Stocke toutes les informations de commande.	Non
`dyn_order_line`	Stocke toutes les informations de ligne de commande.	Non
`dyn_item`	Doit être rempli avec les informations produit.	Oui
`dyn_party`	Doit être rempli avec les informations client.	Oui
`dyn_unit_code`	Doit être rempli avec les codes d'unité dans lesquels un produit peut être commandé (par ex. pièce, carton).	Oui
`dyn_item_units_of_measure`	Peut être rempli avec les informations de palettisation.	Oui
`dyn_party_items`	Peut être utilisé pour déterminer quel produit un client est autorisé à commander.	Oui
`dyn_order_history`	Peut être utilisé pour stocker l'historique des commandes par client, afin que Hyperfox consulte cet historique et gagne en précision sur les nouvelles commandes.	Oui

Modèle Transport

Optimisé pour les flux logistiques et de transport.

Asset	Utilité	Supporting Data
`dyn_transport_order`	Stocke toutes les informations de transport, par ex. les remarques générales, la référence de transport.	Non
`dyn_consignment`	Stocke les informations relatives au(x) envoi(s) lié(s) à un transport, par ex. les informations de chargement et de déchargement.	Non
`dyn_goods`	Stocke les informations sur les marchandises transportées, par ex. le produit concerné, les dimensions, le poids, la quantité.	Non
`dyn_allowance_charge`	Stocke les informations sur les frais liés à un transport.	Non
`dyn_party`	Doit être rempli avec les informations client.	Oui
`dyn_location`	Doit être rempli avec les données d'adresse.	Oui
`dyn_packing_type`	Doit être rempli avec les différents types d'emballage pouvant être transportés, par ex. palettes, big bag.	Oui
`dyn_allowance_charge_reason`	Doit être rempli avec les différents frais applicables, par ex. les surcharges carburant, le Maut.	Oui

Mise à jour du statut de la commande

Lorsqu'une commande est validée et approuvée dans Hyperfox, les données sont envoyées via l'intégration connectée à votre configuration. La commande apparaît avec le statut submitted dans l'archive. Tout client API disposant du scope write:order_data peut mettre à jour le processing_status et lui attribuer l'une des valeurs suivantes :

États valides

pending_validation — Une nouvelle commande créée par la plateforme.
saved — Une commande dont certaines données ont été modifiées et qui a été enregistrée.
validated — Tous les champs obligatoires ont été renseignés et la commande peut être exportée.
rejected — La commande n'a pas besoin d'être exportée.
submitted — La commande a été envoyée à l'intégration externe.
submit_failed — L'intégration externe est passée en erreur ou a refusé la commande. L'intégration peut renvoyer une erreur, qui est affichée dans l'interface de Hyperfox.
completed — La commande a bien été reçue par l'intégration externe.

En pratique, un système externe qui met à jour le processing_status n'a généralement à choisir qu'entre submit_failed et completed. Lorsque le statut est défini sur submit_failed, un champ facultatif error_reason peut être fourni sous la forme d'un tableau de messages d'erreur, qui sont affichés dans l'interface de Hyperfox.

Point de terminaison

PUT api/v1/dynamic-assets/dyn/{default_order_model}/assets/{hyperfox_order_id}

Le {default_order_model} correspond au modèle de commande par défaut configuré pour le tenant — souvent dyn_stock_order ou dyn_transport_order. Le {hyperfox_order_id} est l'ID de la commande à mettre à jour.

Exemple : commande terminée

{
  "processing_status": "completed"
}

Exemple : commande en échec

{
  "processing_status": "submit_failed",
  "error_reason": [
    "Invalid customer reference",
    "Delivery date is in the past"
  ]
}

Type de contenu

Toutes les requêtes doivent utiliser Content-Type: application/json.

Format des réponses

Toutes les réponses réussies renvoient les données au format suivant :

{
  "data": {
    "id": "uuid",
    "field1": "value1",
    "field2": "value2",
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Pour les collections (points de terminaison de listage), la réponse inclut la pagination :

{
  "data": [
    {
      "id": "uuid",
      "field1": "value1"
    }
  ],
  "links": {
    "first": "url",
    "last": "url",
    "prev": null,
    "next": "url"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 100
  }
}

Authentification

L'API utilise le flux OAuth 2.0 Client Credentials. Obtenez d'abord un jeton d'accès à l'aide de la requête OAuth Token, puis utilisez-le dans l'en-tête Authorization pour toutes les requêtes suivantes.

Création des identifiants

Les identifiants peuvent être générés dans le tenant Hyperfox par un utilisateur disposant du rôle admin. Les utilisateurs peuvent créer, supprimer et régénérer des identifiants en accédant à Paramètres → API Clients.

Obtention d'un jeton d'accès

Pour interagir avec l'API, vous avez besoin d'un jeton d'accès valide au format JWT (JSON Web Token). Ce jeton authentifie vos requêtes et autorise l'accès aux points de terminaison protégés. Le processus consiste à utiliser l'authentification Basic pour demander le jeton d'accès (JWT) via le point de terminaison /oauth/token.

Ce jeton devra être renouvelé après son expiration ; nous fournissons le champ expires_in dans la réponse du jeton afin de vérifier sa validité.

Scopes

L'API Dynamic Assets utilise le flux OAuth 2.0 Client Credentials avec un contrôle d'accès basé sur les scopes. Les scopes définissent le niveau d'accès de votre application aux différents types de données et d'opérations.

Lors de la demande d'un jeton d'accès, vous indiquez les scopes dont votre application a besoin dans le paramètre scope. Le jeton d'accès n'accordera d'autorisations que pour les scopes demandés, et tout appel d'API nécessitant des scopes supplémentaires sera rejeté.

Scopes disponibles

read:reference_data — Accès en lecture aux Reference Data (supporting_data = true)
write:reference_data — Accès en écriture aux Reference Data (supporting_data = true)
read:order_data — Accès en lecture aux Master Data de type commandes (supporting_data = false)
write:order_data — Accès en écriture aux Master Data de type commandes (supporting_data = false)

Vous pouvez demander plusieurs scopes dans un même jeton en les séparant par des espaces :

{
  "scope": "read:reference_data write:reference_data read:order_data"
}

Génération d'un jeton OAuth

Exemple de requête

POST /oauth/token
Content-Type: application/json

{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "read:reference_data write:reference_data"
}

Réponse

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Utilisation du jeton

Incluez le jeton d'accès dans l'en-tête Authorization pour toutes les requêtes API :

Authorization: Bearer your_access_token

Environnements

L'API Dynamic Assets utilise un format d'URL structuré qui inclut le nom de votre tenant, l'environnement et la version de l'API. Comprendre cette structure est essentiel pour configurer correctement votre intégration API. Tous les points de terminaison de l'API suivent ce modèle d'URL de base.

Composants

tenant — L'identifiant de tenant unique de votre organisation.
environment — L'environnement auquel vous vous connectez (staging ou production).
table — Le nom de la table dynamique avec laquelle vous travaillez (par ex. dyn_party, dyn_item, dyn_order).
endpoint — Le chemin du point de terminaison spécifique (par ex. assets, info).

URL de base

Production : https://{tenant}.api.hyperfox.cloud
Staging : https://{tenant}.staging.testerfox.eu

Exemple de point de terminaison

https://{tenant}.api.hyperfox.cloud/api/v1/dynamic-assets/dyn/{table}/assets

Collection Postman (avec exemples)

Nous mettons à disposition une collection Postman accompagnée d'exemples interactifs. Téléchargez-la dans un dossier local et importez-la dans Postman pour l'utiliser.

Instructions

Assurez-vous de disposer d'un client Postman — soit une version installée localement, soit la version web.
Téléchargez et importez la collection.
Définissez les variables de la collection.
Exécutez la requête Request Access Token du dossier Authentication. Vous disposez désormais d'une clé d'accès valide pendant 1 heure. Si vous recevez un message d'erreur indiquant que la clé n'est plus valide, actualisez la clé d'accès en appelant à nouveau ce point de terminaison.
Vous pouvez maintenant explorer les différents points de terminaison liés aux commandes.

Types de champs et contraintes

Types de champs

Les assets dynamiques prennent en charge différents types de champs :

String — Valeurs textuelles
LongText — Contenu textuel long
Integer — Nombres entiers
Decimal — Nombres décimaux
Date — Valeurs de date (YYYY-MM-DD)
DateTime — Valeurs de date et d'heure (ISO 8601)
Boolean — Valeurs true / false

Contraintes de champs

Les champs peuvent être :

Required — Doivent être fournis dans les requêtes de création/mise à jour
Nullable — Peuvent être nuls ou omis

Points de terminaison de l'API

`GET` Lister tous les assets

remarque

TODO : créer un point de terminaison permettant de récupérer tous les assets et/ou un moyen de visualiser tous les assets dans l'interface.

`GET` Obtenir les informations d'un asset

Liste l'ensemble du schéma de champs de l'asset {table}.

GET /api/v1/dynamic-assets/dyn/{table}/info

Paramètres

table — Le nom de table du type d'asset.

Réponse : objet de données contenant tous les champs et relations.

Scopes requis

read:reference_data pour les Reference Data
read:order_data pour les données de commande

`GET` Lister les détails des assets

Liste tous les enregistrements d'un asset {table}.

GET /api/v1/dynamic-assets/dyn/{table}/assets

Paramètres

table — Le nom de table du type d'asset.

Réponse : liste paginée d'assets (25 par page). Voir Pagination pour savoir comment gérer la pagination.

Scopes requis

read:reference_data pour les Reference Data
read:order_data pour les données de commande

`GET` Obtenir le détail d'un asset

Renvoie un enregistrement unique {asset_id} situé dans {table}.

GET /api/v1/dynamic-assets/dyn/{table}/assets/{asset_id}

Paramètres

table — Le nom de table du type d'asset.
asset_id — L'UUID de l'asset.

Scopes requis

read:reference_data pour les Reference Data
read:order_data pour les données de commande

`POST` Créer un asset

Ajoute un nouvel élément à l'asset {table}.

POST /api/v1/dynamic-assets/dyn/{table}/assets

Paramètres

table — Le nom de table du type d'asset.

Corps de la requête : objet JSON contenant les champs de l'asset.

Réponse : 201 Created avec l'asset créé.

Scopes requis

write:reference_data pour les Reference Data
write:order_data pour les données de commande

`PUT` Mettre à jour un asset

Met à jour l'élément portant l'id {asset_id} dans l'asset {table}.

PUT /api/v1/dynamic-assets/dyn/{table}/assets/{asset_id}

Paramètres

table — Le nom de table du type d'asset.
asset_id — L'UUID de l'asset.

Corps de la requête : objet JSON contenant les champs de l'asset à mettre à jour.

Réponse : 200 OK avec l'asset mis à jour.

Scopes requis

write:reference_data pour les Reference Data
write:order_data pour les données de commande

`POST` Upsert par lot d'assets

Met à jour les enregistrements existants et insère de nouveaux enregistrements dans l'asset {table}.

POST /api/v1/dynamic-assets/dyn/{table}/assets/batch

Paramètres

table — Le nom de table du type d'asset.

Corps de la requête : objet JSON contenant un tableau d'assets à insérer ou mettre à jour.

{
    "items": [
        {
            "field1": "value1",
            "field2": "value2"
        },
        {
            "field1": "value3",
            "field2": "value4"
        }
    ]
}

Règles applicables aux lots

Minimum 1 élément, maximum 1000 éléments par lot.
Chaque élément est validé par rapport aux exigences de champs du type d'asset.
Utilise le champ d'index unique du type d'asset pour les opérations d'upsert (création si l'enregistrement n'existe pas, mise à jour s'il existe).
Toutes les opérations sont exécutées au sein d'une transaction de base de données.

Réponse : 200 OK avec un message de réussite.

{
    "data": {
        "message": "Batch upsert completed successfully"
    }
}

Scopes requis

write:reference_data pour les Reference Data
Les données de commande ne peuvent pas être écrites via des opérations par lot.

Exemple pratique

Cet exemple illustre une opération par lot mixte, qui crée de nouveaux enregistrements et met à jour des enregistrements existants dans une seule requête. Supposons que nous ayons une table dyn_party avec un index unique sur external_id :

POST /api/v1/dynamic-assets/dyn/dyn_party/assets/batch
Authorization: Bearer your_access_token
Content-Type: application/json

{
    "items": [
        {
            "name": "New Party",
            "street": "New Street",
            "city": "New City",
            "external_id": "party-1"
        },
        {
            "name": "Newer Party",
            "street": "Newer Street",
            "city": "Newer City",
            "external_id": "party-2"
        }
    ]
}

Dans cet exemple :

Si party-1 existe déjà, il sera mis à jour avec les nouvelles valeurs.
Si party-2 n'existe pas, il sera créé en tant que nouvel enregistrement.
Le champ external_id sert d'identifiant unique pour l'opération d'upsert.
Les deux opérations réussissent ou échouent ensemble (transaction atomique).
L'id peut être omis, car nous utiliserons l'index unique de l'asset.

Gestion des erreurs

Si la validation échoue pour l'un des éléments du lot, l'opération entière est rejetée :

{
    "message": "Validation failed",
    "errors": {
        "items": ["The items field is required."],
        "items.0.name": ["This field is required"],
        "items.1.email": ["The email field must be a valid email address"]
    }
}

Suivi des lots avec `_batch_id`

Les types d'assets de Reference Data (supporting_data: true) incluent automatiquement, sur leur table de base de données, un champ _batch_id géré par le système. Ce champ indique quelle synchronisation par lot a écrit chaque enregistrement en dernier, ce qui permet de nettoyer les données obsolètes après une synchronisation complète.

Lorsque vous effectuez des upserts par lot sur des Reference Data, incluez une valeur _batch_id dans chaque élément afin de marquer tous les enregistrements appartenant à la même exécution de synchronisation :

{
    "items": [
        {
            "name": "Party A",
            "external_id": "party-1",
            "_batch_id": "sync-2026-03-03-001"
        },
        {
            "name": "Party B",
            "external_id": "party-2",
            "_batch_id": "sync-2026-03-03-001"
        }
    ]
}

Principales caractéristiques de _batch_id :

Ajouté automatiquement à toutes les tables de Reference Data — aucune configuration manuelle n'est nécessaire.
Nullable — non obligatoire, mais doit être fourni si vous comptez utiliser le point de terminaison Clean Up.
Masqué dans les réponses standard de l'API (champ système préfixé par _).

Une fois une synchronisation complète des données effectuée via un upsert par lot, utilisez le point de terminaison Clean Up pour supprimer les enregistrements qui n'étaient pas inclus dans le dernier lot.

`POST` Nettoyer les assets

Supprime d'un asset de Reference Data {table} les enregistrements obsolètes qui ne faisaient pas partie de la dernière synchronisation par lot. Ce point de terminaison n'est disponible que pour les Reference Data (supporting_data: true).

POST /api/v1/dynamic-assets/dyn/{table}/assets/clean-up

Paramètres

table — Le nom de table du type d'asset.

Corps de la requête

{
    "batch_id": "sync-2026-03-03-001"
}

Champ	Type	Obligatoire	Description
`batch_id`	string	Oui	L'identifiant de lot utilisé lors de l'upsert par lot précédent.

Fonctionnement

Le point de terminaison supprime tous les enregistrements de la table dont le _batch_id ne correspond pas au batch_id fourni. Cela supprime de fait toutes les données qui n'étaient pas incluses dans la dernière synchronisation.

Réponse : 200 OK

{
    "data": {
        "message": "Clean up completed successfully",
        "deleted": 42
    }
}

Scopes requis

write:reference_data

Restrictions

Disponible uniquement pour les types d'assets de Reference Data (supporting_data: true). Toute tentative de nettoyage de Master Data renverra une erreur :

{
    "message": "This asset type cannot be cleaned up",
    "error": "This operation can only be executed safely on reference data"
}

Flux de synchronisation des données typique

Le mécanisme combinant _batch_id et le nettoyage permet de maintenir les Reference Data synchronisées avec un système externe :

Upsert par lot — Envoyez tous les enregistrements actuels avec un _batch_id unique (par ex. un horodatage ou un identifiant d'exécution de synchronisation).
Clean Up — Appelez le point de terminaison de nettoyage avec le même batch_id afin de supprimer les enregistrements qui ne faisaient pas partie de la synchronisation.
Résultat — La table contient désormais exactement les enregistrements de la dernière synchronisation.

Exemple

Étape 1 : upsert par lot avec _batch_id = "sync-001"
        → Les enregistrements A, B, C sont insérés/mis à jour avec _batch_id = "sync-001"
        → L'enregistrement D (de la synchronisation précédente) a toujours _batch_id = "sync-000"

Étape 2 : nettoyage avec batch_id = "sync-001"
        → L'enregistrement D est supprimé (son _batch_id ≠ "sync-001")
        → Les enregistrements A, B, C sont conservés

Résultat : la table ne contient plus que le jeu de données actuel

Gestion des erreurs

Codes de statut HTTP

200 — Succès
201 — Created (pour les requêtes POST)
401 — Unauthorized (jeton invalide ou manquant)
403 — Forbidden (scopes insuffisants)
404 — Not Found (l'asset ou la table n'existe pas)
422 — Validation Error (données invalides)
500 — Server Error

Format des réponses d'erreur

Erreurs de validation (422) :

{
    "message": "Validation failed",
    "errors": {
        "field_name": [
            "This field is required"
        ],
        "another_field": [
            "This field must be a valid email"
        ]
    }
}

Autres erreurs :

{
    "message": "Error description",
    "error": "Detailed error information"
}

Pagination

Les points de terminaison de listage de l'API Dynamic Assets renvoient des résultats paginés afin de garantir des performances optimales lors du traitement de grands volumes de données. L'API utilise une pagination par page avec une taille de page par défaut de 25 éléments.

Pour récupérer des données paginées, ajoutez le paramètre de requête page à votre requête. S'il est omis, l'API renvoie la première page par défaut.

Exemple de requête

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?page=1

Structure de la réponse

Les réponses paginées contiennent trois sections principales.

Tableau `data`

Contient les éléments effectifs de la page en cours.

Objet `links`

Fournit des URL prêtes à l'emploi pour faciliter la navigation :

first — URL vers la première page.
last — URL vers la dernière page.
prev — URL vers la page précédente ; null si vous êtes sur la première page.
next — URL vers la page suivante ; null si vous êtes sur la dernière page.

Objet `meta`

Contient les métadonnées de pagination :

current_page — Le numéro de la page en cours.
from — Index du premier élément de cette page.
to — Index du dernier élément de cette page.
per_page — Nombre d'éléments par page (toujours 25).
last_page — Nombre total de pages.
total — Nombre total d'éléments sur l'ensemble des pages.

Remarques importantes

Le paramètre page accepte des entiers positifs à partir de 1.
Demander un numéro de page supérieur à last_page renvoie un tableau de données vide.
La taille de page par défaut est de 25 éléments. Utilisez le paramètre perPage pour la modifier (voir ci-dessous).
Tous les points de terminaison de listage suivent cette structure de pagination de manière cohérente.

Taille de page

Le nombre d'éléments par page peut être contrôlé avec le paramètre de requête perPage. Seules les valeurs 25, 100 et 1000 sont acceptées ; toute autre valeur revient à la valeur par défaut de 25.

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?perPage=100

Filtrage et tri

Les points de terminaison de listage (GET /api/v1/dynamic-assets/dyn/{table}/assets) prennent en charge le filtrage et le tri via des paramètres de requête.

Seuls les champs configurés sur le type d'asset peuvent être filtrés et triés. De plus, created_at et updated_at sont toujours disponibles pour le tri. Utilisez le point de terminaison GET .../info pour découvrir les noms de champs disponibles d'un type d'asset. Demander un filtre ou un tri sur un champ non autorisé renvoie une erreur 400 Bad Request.

Filtrage

Appliquez un filtre avec la syntaxe filter[field]=value. Les filtres utilisent par défaut une correspondance partielle (LIKE, insensible à la casse).

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?filter[name]=acme

Transmettez plusieurs valeurs séparées par des virgules pour correspondre à l'une d'entre elles :

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?filter[country]=BE,NL,DE

Combinez plusieurs filtres — ils sont appliqués conjointement (AND) :

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?filter[name]=acme&filter[country]=BE

Tri

Triez les résultats avec le paramètre sort. Préfixez un champ avec - pour un tri décroissant.

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?sort=name
GET /api/v1/dynamic-assets/dyn/dyn_party/assets?sort=-created_at

Triez sur plusieurs champs en les séparant par des virgules ; ils sont appliqués dans l'ordre indiqué :

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?sort=-created_at,name

Combinaison

Les paramètres de filtrage, de tri et de pagination peuvent être combinés dans une seule requête :

GET /api/v1/dynamic-assets/dyn/dyn_party/assets?filter[country]=BE&sort=-created_at&perPage=100&page=1

Webhooks

Les utilisateurs disposant du rôle admin peuvent configurer des webhooks qui s'abonnent aux données d'événements dans Hyperfox (par ex. la création d'une commande). Les webhooks sont créés et gérés via Paramètres → Webhook.

Tous les webhooks contiennent 2 propriétés à la racine :

validated_order{}, qui contient toutes les données relatives à la commande.
custom_data{}, qui contient toutes les propriétés personnalisées pouvant être ajoutées à la configuration.

Transfert de données sécurisé

Les webhooks ne peuvent être envoyés que vers des points de terminaison chiffrés en HTTPS.

Validation des webhooks

Le contenu du webhook peut être vérifié à l'aide de sa Signature intégrée aux données d'en-tête. Pour vérifier le contenu, utilisez HMAC-SHA256 (RFC 4868) en combinaison avec le secret généré lors de la configuration du webhook dans Hyperfox.

Hachez le contenu de la réponse — cela doit produire la même valeur de hachage que l'en-tête de signature.

Exemple d'informations d'en-tête

{
    "Signature": "bb463fed379eeffa4c0828d7ee6b04f08cccc0842a6276f1f2e5073d365cd54b",
    "Content-Type": "application/json"
}

Gestion des erreurs de webhook

Notre mécanisme de webhook tente de livrer les données du webhook jusqu'à 5 fois. Lorsque le webhook ne parvient pas à livrer ses données après la 5e tentative, cela se solde par un échec définitif.

La commande correspondante est renvoyée vers l'écran « À valider » avec le statut failed. Le motif de l'échec est visible dans les détails de la commande concernée.

Un backoff exponentiel est appliqué entre chaque nouvelle tentative.

Remarques importantes

Exigences de champs — Chaque type d'asset dispose de son propre schéma de champs. Les champs obligatoires doivent être inclus dans les requêtes de création/mise à jour.
UUID — Tous les ID d'assets sont des UUID, et non des entiers séquentiels.
Exigences de scopes — Assurez-vous toujours que votre jeton OAuth dispose des scopes appropriés pour les opérations que vous devez effectuer.
Limitation de débit — Tenez compte des limites de débit (les limites précises dépendent de la configuration du serveur).
Opérations par lot — Les opérations d'upsert par lot utilisent les index uniques pour déterminer s'il faut créer ou mettre à jour les enregistrements. Assurez-vous que des index uniques appropriés sont configurés sur votre type d'asset.
Synchronisation des données — Lorsque vous utilisez l'upsert par lot avec _batch_id et le point de terminaison de nettoyage, veillez toujours à utiliser la même valeur batch_id dans les deux requêtes. Appeler le nettoyage avec un batch_id incorrect supprimerait des enregistrements de manière involontaire.

Exemple de données de webhook

{
    "validated_order": {
        "id": "a1e33646-84d6-4c41-9ca3-7296e6c70510",
        "created_at": "2026-05-28T12:46:42.000000Z",
        "updated_at": "2026-05-28T12:50:57.000000Z",
        "sales_order_id": null,
        "processing_status": "validated",
        "issue_date": "2026-05-28",
        "issue_time": null,
        "delivery_date": "2026-05-29",
        "notes": null,
        "customer_reference": "10943",
        "accuracy": 100,
        "order_inquiry_id": "019e6e9d-e05b-7270-bc76-fdb9df6b73a7",
        "buyer_customer_party_id": "BBQ001",
        "accounting_customer_party_id": "BBQ001",
        "error_reason": null,
        "approved_at": "2026-05-28 12:50:57",
        "approved_by": 11,
        "buyer_customer_party": {
            "id": "019a0b7a-372c-73e4-a7da-138baa5f0209",
            "created_at": "2025-10-22T10:32:30.000000Z",
            "updated_at": "2026-05-28T03:00:04.000000Z",
            "account_id": "BBQ001",
            "name": "SMOKY PITS & GRILLS NV",
            "language": null,
            "website_uri": null,
            "street_name": "UNIT 4 GRILLZONE INDUSTRIAL PARK",
            "additional_street_name": "KOOLSKAMPSEWEG",
            "city_name": "ROESELARE",
            "postal_zone": "8800",
            "country": "BE",
            "contact_name": null,
            "contact_telephone": null,
            "contact_email": null,
            "external_id": "BBQ001",
            "address_number": ""
        },
        "accounting_customer_party": {
            "id": "019a0b7a-372c-73e4-a7da-138baa5f0209",
            "created_at": "2025-10-22T10:32:30.000000Z",
            "updated_at": "2026-05-28T03:00:04.000000Z",
            "account_id": "BBQ001",
            "name": "SMOKY PITS & GRILLS NV",
            "language": null,
            "website_uri": null,
            "street_name": "UNIT 4 GRILLZONE INDUSTRIAL PARK",
            "additional_street_name": "KOOLSKAMPSEWEG",
            "city_name": "ROESELARE",
            "postal_zone": "8800",
            "country": "BE",
            "contact_name": null,
            "contact_telephone": null,
            "contact_email": null,
            "external_id": "BBQ001",
            "address_number": ""
        },
        "lines": [
            {
                "id": "a1e33646-8d6b-45d6-bcf0-74550895cd5a",
                "created_at": "2026-05-28T12:46:42.000000Z",
                "updated_at": "2026-05-28T12:46:42.000000Z",
                "quantity": 1,
                "item_id": "01998116-cc49-7113-9c33-56c9cd16d566",
                "order_id": "a1e33646-84d6-4c41-9ca3-7296e6c70510",
                "unit_code_id": "0197f3fb-29e9-70b1-a7c6-ffa8e84b27ea",
                "item": {
                    "id": "01998116-cc49-7113-9c33-56c9cd16d566",
                    "created_at": "2025-09-25T13:36:19.000000Z",
                    "updated_at": "2026-05-28T03:00:06.000000Z",
                    "name": "PRKPAL400",
                    "description": "PORK PAL BBQ RUB 400g JAR",
                    "brand_name": "Braai BBQ",
                    "sku": "PPAL400",
                    "ean": "",
                    "external_id": "BR00123",
                    "base_unit_code_id": "EACH",
                    "category_id": "RUBS01",
                    "product_id": "PRKPAL400",
                    "base_unit_code": null,
                    "category": null
                },
                "unit_code": {
                    "id": "0197f3fb-29e9-70b1-a7c6-ffa8e84b27ea",
                    "created_at": "2025-07-10T10:56:53.000000Z",
                    "updated_at": "2025-07-10T10:56:53.000000Z",
                    "code": "EACH",
                    "value": "EACH"
                }
            }
        ],
        "approver": {
            "id": 11,
            "first_name": "Pit",
            "last_name": "Master",
            "locale": "nl",
            "email": "[email protected]"
        }
    },
    "custom_data": {
       "field": "value"
    }
}

Cette documentation se base sur la version 1 de l'API et est susceptible d'évoluer.

Concepts​

Modèle de données : Master Data et Reference Data​

Modèles de configuration​

Modèle Stock​

Modèle Transport​

Mise à jour du statut de la commande​

Type de contenu​

Format des réponses​

Authentification​

Création des identifiants​

Obtention d'un jeton d'accès​

Scopes​

Scopes disponibles​

Génération d'un jeton OAuth​

Exemple de requête​

Réponse​

Utilisation du jeton​

Environnements​

URL de base​

Exemple de point de terminaison​

Collection Postman (avec exemples)​

Types de champs et contraintes​

Types de champs​

Contraintes de champs​

Points de terminaison de l'API​

GET Lister tous les assets​

GET Obtenir les informations d'un asset​

GET Lister les détails des assets​

GET Obtenir le détail d'un asset​

POST Créer un asset​

PUT Mettre à jour un asset​

POST Upsert par lot d'assets​

Suivi des lots avec _batch_id​

POST Nettoyer les assets​

Gestion des erreurs​

Codes de statut HTTP​

Format des réponses d'erreur​

Pagination​

Exemple de requête​

Structure de la réponse​

Tableau data​

Objet links​

Objet meta​

Remarques importantes​

Taille de page​

Filtrage et tri​

Filtrage​

Tri​

Combinaison​

Webhooks​

Transfert de données sécurisé​

Validation des webhooks​

Gestion des erreurs de webhook​

Remarques importantes​

Exemple de données de webhook​

Concepts

Modèle de données : Master Data et Reference Data

Modèles de configuration

Modèle Stock

Modèle Transport

Mise à jour du statut de la commande

Type de contenu

Format des réponses

Authentification

Création des identifiants

Obtention d'un jeton d'accès

Scopes

Scopes disponibles

Génération d'un jeton OAuth

Exemple de requête

Réponse

Utilisation du jeton

Environnements

URL de base

Exemple de point de terminaison

Collection Postman (avec exemples)

Types de champs et contraintes

Types de champs

Contraintes de champs

Points de terminaison de l'API

`GET` Lister tous les assets

`GET` Obtenir les informations d'un asset

`GET` Lister les détails des assets

`GET` Obtenir le détail d'un asset

`POST` Créer un asset

`PUT` Mettre à jour un asset

`POST` Upsert par lot d'assets

Suivi des lots avec `_batch_id`

`POST` Nettoyer les assets

Gestion des erreurs

Codes de statut HTTP

Format des réponses d'erreur

Pagination

Exemple de requête

Structure de la réponse

Tableau `data`

Objet `links`

Objet `meta`

Remarques importantes

Taille de page

Filtrage et tri

Filtrage

Tri

Combinaison

Webhooks

Transfert de données sécurisé

Validation des webhooks

Gestion des erreurs de webhook

Remarques importantes

Exemple de données de webhook