Declaration

Déclarer une intégration

La déclaration d'une intégration se fait par le biais de la méthode d'API StockTicket Admin/Module/Definition/Integrations/Create.
Pour l'exécuter, vous devez avoir un compte StockTicket et être authentifié en tant que développeur du module (voir Authentification).
En outre, une intégration est toujours associée à une définition de module existante.
Vous devez donc au préalable créer un module en créant une définition de module dans l'interface du Back-Office StockTicket.

Requête de création d'une intégration

POST /api/admin/v1/Module/Definition/Integrations/Create?moduleDefinitionId={id}

Cette méthode permet de créer une nouvelle intégration (action externe ou complémentaire) pour une définition de module existante.
Une intégration permet d'étendre les fonctionnalités de StockTicket en ajoutant des liens, des formulaires ou des zones d'interface utilisateur dynamiques.
Elle attend en paramètres:
• l'identifiant de la définition de module cible (moduleDefinitionId (paramètre d'url, string))
• un body JSON : objet de type ModuleIntegrationCreateModel décrivant l'intégration à créer.
Elle retourne l'identifiant (string) de l'intégration créée en cas de succès.

Vous pouvez retrouver la documentation dynamique de cette méthode dans Swagger UI.
Pour plus de clarté concernant les propriétés contenant des énumérations, les valeurs possibles de ces énumérations sont détaillées ci-dessous.

Énumérations

RecordStateEnum - État de l'enregistrement

Valeur	Description
Active	Intégration active et visible
Draft	Brouillon, non visible par les utilisateurs
Deleted	Marquée comme supprimée

ModuleIntegrationScopeEnum - Portée de l'intégration

Valeur	Description
None	Aucune intégration
ModuleOwner	Intégration uniquement pour l'espace de travail propriétaire de la définition de module
InstanceOwner	Intégration uniquement pour l'espace de travail propriétaire de l'instance de module
InstanceOwnerSubscription	Intégration uniquement pour l'espace de travail ayant souscrit à l'instance de module dont il est propriétaire
Subscription	Intégration pour tous les espaces de travail ayant souscrit à l'instance de module

IntegrationColorEnum - Couleur de l'intégration ou de l'icône

Valeur	Description
Default	Couleur par défaut
Primary	Couleur primaire
Secondary	Couleur secondaire
Tertiary	Couleur tertiaire
Info	Bleu information
Success	Vert succès
Warning	Orange avertissement
Error	Rouge erreur
Dark	Sombre
Transparent	Transparent
Inherit	Héritée du parent

IntegrationTypeEnum - Type d'intégration

Valeur	Description
Undefined	Type non défini
Link	Lien hypertexte simple
UIForm	Formulaire modal intégré
UIZone	Zone d'interface intégrée (iframe)
CodeExecution	Exécution de code côté client

DialogTypeEnum - Type de dialogue

Valeur	Description
Small	Petite fenêtre modale
Medium	Fenêtre modale moyenne
Large	Grande fenêtre modale
FullScreen	Plein écran

Passage de paramêtres vers l'intégration

Lors de la création d'une intégration, vous pouvez définir des paramètres personnalisés qui seront transmis à l'intégration lors de son exécution.
Les valeurs de paramètres peuvent être transmises de différentes manières en renseignant les propriétés ci-dessous de l'objet "Action" :
- formData : transmission des paramètres via le corps de la requête (body) dans le cas où httpMethod a été défini sur POST ou PUT
- headers : transmission des paramètres via les en-têtes HTTP
- queryParameters : transmission des paramètres via la chaîne de requête (query string) dans l'URL

Les différentes méthodes sont cumulables : certains paramètres peuvent être transmis via le corps de la requête, d'autres via les en-têtes HTTP ou la chaîne de requête.

Vous pouvez définir des valeurs et des noms de paramêtres fixes qui sont propres à votre module ou utiliser des variables dynamiques fournies par StockTicket au moment de l'appel de l'intégration.
Pour plus de détails sur la cible d'intégration et les données associées disponibles, vous pouvez visiter la page "Cibles d'intégration" dans la section "Espace développeur" de votre espace de travail.
Elle comporte dans le détail de la cible une liste des valeurs dynamiques disponibles pour cette cible.
Exemple :

Pour obtenir la valeur d'une variable dans les paramètres transmis, vous devez utiliser la syntaxe suivante : {{ NomVariable }}
Note : les valeurs de type objet complexe sont sérialisés au format JSON avant envoi.
Par exemple :

{
  "url": "https://mon-url.fr",
  "httpMethod": "POST",
  "formData": {
    "layout": "{{ VenueRoomLayout }}",
  },
  "headers": {
    "X-Custom-Header": "MaValeurFixe"
  },
  "queryParameters": {
    "IdLieu": "{{ VenueId }}"
  }
}

Autres méthodes d'API associées aux intégrations

• /api/admin/v1/Module/Definition/Integrations/Patch : Met à jour une intégration existante en utilisant la syntaxe JSON Patch.
La méthode attend un paramêtre de type JsonPatchDocument (JsonPatchDocument?): Document JSON Patch contenant les modifications à appliquer aux propriétés utilisateur.
Ce document permet de décrire, sous forme d’opérations (add, replace, remove…), les changements à effectuer sur les propriétés transmises dans la requête.

• /api/admin/v1/Module/Definition/Integrations/GetDetail : Récupère les détails d'une intégration spécifique.
• /api/admin/v1/Module/Definition/Integrations/GetList : Liste toutes les intégrations pour une définition de module donnée.