L'API des Objets personnalisés de Webmecanik Automation vous permet de synchroniser automatiquement les données de votre écosystème (site e-commerce, ERP, CRM métier) avec votre outil de marketing automation.
Retrouvez toute notre documentation API pour Webmecanik Automation.
⚠️ Rappel important : La fonctionnalité des Objets personnalisés est exclusivement réservée aux utilisateurs de l'offre Webmecanik Premium. Pensez à contacter votre Customer Success Manager (CSM) pour l'activer sur votre compte avant d'initier vos développements.
💡 Comprendre l'API sans être développeur
L'API fonctionne comme une passerelle sécurisée entre vos logiciels et Webmecanik :
- L'Objet personnalisé (Custom Object) est le modèle général (ex. Produits ou Commandes). On l'identifie par son identifiant numérique (
id) ou par son nom technique (alias, ex.products). - L'Élément personnalisé (Custom Item) est une entrée concrète (ex. le produit Table basse). Il possède toujours un champ Nom (
name) par défaut. - Les Champs personnalisés (Custom Fields) sont les caractéristiques de l'élément (ex. SKU, Couleur, Prix).
Pour enregistrer une nouvelle donnée, il ne faut pas renseigner d'identifiant (
id). À l'inverse, dès que vous transmettez un id, Webmecanik comprend que vous souhaitez modifier un élément existant.🔄 Synchroniser des Éléments personnalisés avec un Contact
Cette méthode est la plus courante : lorsqu'un client passe commande ou consulte un produit, vous envoyez les informations du contact et ses éléments associés en une seule et même requête.
Les routes disponibles
POST api/contacts/new: Crée un contact (ou le met à jour s'il existe déjà) et lui rattache les éléments personnalisés.POST api/contacts/batch/new: Permet d'envoyer plusieurs contacts et leurs éléments en lot (tableau JSON).PATCHouPUT api/contacts/[contact_id]/edit: Met à jour un contact spécifique et ses éléments rattachés.
Webmecanik effectue une vérification complète avant d'enregistrer : il valide la conformité des objets, des champs et du contact. Si toutes les validations réussissent, le contact et les éléments personnalisés sont créés ou mis à jour, puis liés entre eux automatiquement.
Exemple de requête (Création d'un contact avec un élément mis à jour)
Dans cet exemple, nous envoyons un contact avec un produit à mettre à jour (puisqu'un
id est renseigné) :JSON
{
"email": "jean.dupont@exemple.com",
"firstname": "Jean",
"customObjects": {
"data": [
{
"alias": "products",
"data": [
{
"id": 23,
"name": "Vélo de course Pro",
"attributes": {
"website": "https://mon-site.com",
"in-stock": 12,
"multi": ["bleu", "noir"],
"sku": "VELO-9821",
"color": "noir"
}
}
]
}
]
}
}
Récupérer les Objets personnalisés dans la réponse API
Par défaut, la réponse API ne renvoie pas le détail des objets pour ne pas ralentir les échanges techniques. Pour récupérer les objets personnalisés dans la réponse, ajoutez simplement le paramètre
?includeCustomObjects=true à votre URL d'appel :POST api/contacts/new?includeCustomObjects=true
📦 Gérer les Éléments personnalisés de manière autonome
Vous pouvez créer, mettre à jour ou supprimer des éléments sans les associer immédiatement à un contact (par exemple pour importer votre catalogue produit).
Créer un ou plusieurs éléments
- Création unitaire :
POST api/custom/item/new/[custom_object_id]
JSON
{
"name": "Machine à café",
"data": {
"sku": "MC-450",
"couleur": "argent"
}
}
- Création par lot (Batch) :
POST api/custom/item/batch/new/{customObjectId}
JSON
[
{
"name": "Avion miniature",
"data": {
"couleur": "jaune"
}
},
{
"name": "Bus électrique",
"data": {
"couleur": "violet"
}
}
]
Supprimer des données
- Supprimer un élément spécifique :
GET api/custom/item/delete/[custom_item_id]Chaque identifiant d'élément personnalisé est unique dans toute la base ; il n'est donc pas nécessaire de préciser l'objet parent. -
Vider intégralement un objet personnalisé :
GET api/custom/object/empty/[custom_object_id]Cette action supprime tous les éléments enregistrés dans l'objet tout en conservant sa structure et ses champs. Cette opération peut prendre du temps selon le volume : relancer la requête n'accélère pas le traitement.
🔗 Lier deux Éléments personnalisés entre eux
Vous pouvez interconnecter des fiches d'objets distincts (par exemple, relier une Boutique physique à une Commande) à l'aide de la route suivante :
POST api/custom/item/{itemId}/link/customItem/{itemId}
🔍 Consulter et filtrer les informations
Pour auditer vos paramétrages ou récupérer des listes d'éléments, plusieurs requêtes d'interrogation (
GET) sont à votre disposition :| Objectif | Route API | Filtrage possible |
| Lister les Objets personnalisés | GET api/custom/objects |
Renvoie la liste globale et les métadonnées de structure. |
| Lister les Champs personnalisés | GET api/custom/fields |
Ajoutez ?where[0][col]=customObject&where[0][expr]=in&where[0][val]={customObjectId} pour cibler un objet précis.
|
| Lister les Éléments enregistrés | GET api/custom/items |
Même syntaxe de filtre pour cibler uniquement les éléments d'un objet donné. |
🛡️ Gestion des erreurs et bonnes pratiques
Si un objet personnalisé, un champ ou un identifiant d'élément fourni dans votre requête n'existe pas, l'API bloque l'opération et renvoie un code d'erreur HTTP 400 (Bad Request). Pour préserver l'intégrité de votre base, aucune donnée n'est enregistrée (ni le contact, ni l'élément personnalisé).
Exemple de retour en cas d'erreur de saisie sur un alias :
JSON
{
"errors": [
{
"code": 400,
"message": "Custom Object with alias = invoice was not found",
"details": []
}
]
}
Veillez à bien vérifier l'orthographe exacte de vos alias et le respect des types de champs (par exemple, ne pas injecter de texte libre dans un champ de type Nombre ou Date) pour garantir des intégrations fluides.
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.