Parcours | Durée | Niveau | Avant de commencer | |
🔴 Intégration | 90 min | Avancé | [[09 · Eventos - que el proceso avance solo | Événements - que le processus avance tout seul]] · Notions d'API REST et JSON · Un endpoint de test (par exemple, un flux n8n ou un service de capture de requêtes) |
Mairu vit rarement seul : il y a un ERP avec les commandes, un MES avec les ordres de fabrication, une GMAO avec les équipements. Cette leçon vous enseigne les trois voies pour que l'information entre et sorte de Mairu, et les précautions qu'exige chacune.
🎯 À la fin, vous saurez
Choisir la voie d'intégration adaptée : import, API ou Webhook.
Charger des données de façon massive avec le modèle d'import.
Trouver et tester les endpoints dans le Centre pour développeurs.
Enregistrer une API dans Sources de données et l'appeler depuis un événement Webhook.
Prévoir l'effet d'une intégration sur les événements du formulaire.
🧠 L'idée : qui initie la conversation
Voie | Direction | Qui l'initie | Quand l'utiliser |
Import | Entre | Une personne, ponctuellement | Charges initiales, migrations, données maîtres |
API de Mairu | Entre et sort | L'autre système appelle Mairu | L'ERP crée des réponses ou des tâches, synchronise produits, utilisateurs ou Assets |
Webhook | Sort (et peut récupérer la réponse) | Mairu appelle l'autre système, depuis un événement, un bouton ou une automatisation | Envoyer un contrôle NO OK à l'ERP, prévenir un flux n8n, demander des données à une autre application |
⚠️ Ce qui entre par API ou par import se comporte comme une réponse nouvelle. Les événements du formulaire sont évalués pour chaque réponse créée ou modifiée. Un import de 500 lignes dans un formulaire avec un événement d'e-mail peut générer 500 e-mails. Vérifiez toujours les événements avant d'intégrer.
🛠️ Pratique guidée
Partie 1 · Importer des contrôles historiques
Dans l'historique du Contrôle de conditionnement, menu des trois points → Importer.
Téléchargez le modèle. Utilisez la version LibreOffice si vous voulez choisir les données maîtres avec des listes déroulantes.
Remplissez trois lignes de test :
Laissez l'ID vide : ainsi une réponse nouvelle est créée. Si vous mettez l'ID d'une réponse existante, vous la remplacez.
Pour les données maîtres, utilisez le format Référence – Nom (par exemple,
ENV-L1 – Línea 1) ou la valeur telle qu'elle s'affiche dans le formulaire.Respectez le format de date qu'indique l'en-tête de chaque colonne.
Mettez une des lignes avec résultat NO OK.
Téléchargez le fichier et appuyez sur Importer. La charge se fait en arrière-plan ; s'il y a des erreurs, la fenêtre de progression indique la ligne et le problème.
Vérifiez : les trois réponses apparaissent dans l'historique et calidad.prueba a reçu un e-mail : celui de la ligne NO OK. C'est le comportement attendu des événements.
💡 Les données maîtres s'importent aussi : utilisateurs depuis Configuration > Utilisateurs, produits depuis Produits et valeurs d'entités depuis chaque Entité.
Partie 2 · Explorer l'API
Ouvrez Configuration > Centre pour développeurs.
Dans Overview, localisez l'URL de base, la méthode d'authentification (token Bearer dans l'en-tête
Authorization) et le tableau des champs supportés pour les réponses.Dans Endpoints, ouvrez la catégorie Forms et choisissez l'opération pour créer une réponse. Révisez le corps attendu et l'exemple.
Si vous avez un token de test, collez-le dans le bloc Try it et créez une réponse du Contrôle de conditionnement. Copiez la commande cURL pour la donner à l'équipe qui réalisera l'intégration.
⚠️ Le token permet de lire et d'écrire les données de votre organisation. Demandez-le au support ou à l'administrateur du compte et ne le partagez pas par des canaux non sécurisés.
Partie 3 · Envoyer les NO OK à un autre système avec un Webhook
Enregistrer l'API. Dans Configuration > Sources de données, enregistrez votre endpoint de test : nom, URL de base et méthodes.
Créer l'événement. Dans le Contrôle de conditionnement, onglet Événements :
Quand :
Resultadoest égal àNO OK.Il se passera : Webhook → l'API enregistrée, méthode POST, et la route concrète de l'endpoint.
Construire le corps. Dans l'onglet Body, envoyez les données du contrôle en insérant des champs du formulaire, par exemple :
{
"origen": "Mairu",
"tipo": "control_envasado_no_ok",
"linea": "{linea}",
"producto": "{producto}",
"lote": "{lote}",
"motivo": "{motivo_rechazo}"
}
Récupérer la réponse (facultatif). Si l'autre système renvoie, par exemple, un numéro d'incident, vous pouvez l'enregistrer dans un champ du formulaire depuis l'onglet Réponse du Webhook, en indiquant la « direction » de la donnée (par exemple
incidencia.numero).
Vérifiez : enregistrez un contrôle NO OK et vérifiez que la requête arrive à votre endpoint avec les données du contrôle.
⚠️ Erreurs fréquentes
Importer sans réviser les événements. C'est la cause la plus habituelle d'avalanches d'e-mails ou de tâches planifiées par erreur.
Mettre un ID dans le modèle par inadvertance. Cette ligne remplace la réponse existante avec cet ID.
« L'API n'apparaît pas dans le Webhook. » Il faut d'abord l'enregistrer dans Sources de données.
**Utiliser Exécuter le test sur des appels qui créent ou suppriment des données. Le test du mappage de la réponse est un appel réel** vers l'autre système et ne peut pas être annulé.
Concevoir une intégration massive comme si elle était manuelle. Si l'API crée beaucoup de réponses, toutes déclenchent leurs événements. Réfléchissez aux actions qui doivent s'exécuter quand la réponse vient d'un autre système.
🏋️ Défi
L'ERP veut créer automatiquement une tâche de contrôle dans Mairu chaque fois qu'un ordre de fabrication démarre, avec la ligne, le produit et le lot déjà remplis. Avec ce que vous avez vu dans le Centre pour développeurs, écrivez (sans le programmer) la conception de l'intégration : quel endpoint vous utiliseriez, quelles données l'ERP enverrait, à qui la tâche serait assignée et quels événements du Contrôle de conditionnement se déclencheraient quand l'opérateur la complètera.
📚 Pour en savoir plus
Comment mapper la réponse d'un Webhook vers les champs du formulaire
➡️ Leçon suivante : Projet final - concevez un processus complet