| Services documentés dans cet article
Structure d'échange (WSCodeDeSelection)
Structure d'échange (WSParamCS)
Référentiel des codes de sélection (getReferentielCodeSelection)
Valeurs possibles pour un code de sélection de type Sur Liste (getLibelles)
Ajouter un code sélection à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (createCodeSelectionEntite)
Modifier la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (updateCodeSelectionByRefInterneCs).
Supprimer la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (deleteCodeSelection)
Liste des codes de sélection et valeurs associés à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (getCodeSelection)
A NE PLUS UTILISER : Ajouter un code sélection pour un client (createCodeSelection)
A NE PLUS UTILISER : Modification de la valeur d'un code sélection associé client (updateCodeSelection)
A NE PLUS UTILISER : Liste des valeurs des codes de sélection d'un client (listCodeSelection)
| Technologie
|| Protocole
La solution technique mise en place côté AboWeb repose sur des Web Services sans états.
Le protocole utilisé est SOAP 1.1. La couche de transport utilisée est HTTP 1.1.
L’intérêt principal de cette technologie est de pouvoir fournir un moyen d’échange indépendant de la plateforme et du langage de programmation utilisé. Les messages basés sur XML peuvent également être validés par une grammaire et des outils appropriés pour s’assurer que leur structure est correcte avant toute tentative de traitement des données.
|| Sécurité
Les Web Services implémentent la norme WS-Security 1.0 afin de réaliser les fonctions d’authentification des messages échangés.
L’authentification est réalisée à l’aide d’un login et d’un mot de passe crypté avec l’algorithme de hachage SHA-1 en base64 dans l’en-tête des messages. La balise utilisée, à savoir <UsernameToken> est conforme au standard.
Exemple d’en-tête (en rouge) :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ges="http://www.gesmag.com/">
${color}[#ff0000](<soapenv:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken>
<wsse:Username>login</wsse:Username>
<wsse:Password>mdp</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
)
<soapenv:Body>
<ges:listCodeSelection>
[…]
</ges:listCodeSelection>
</soapenv:Body>
</soapenv:Envelope>
La confidentialité et l’intégrité des messages ne sont pas implémentées à ce jour.
|| Point d’accès
Les points d’accès sont contenus dans les fichiers WSDL générés sur les différents environnements.
Sur l’environnement de test, nous avons :
**Service :** gestion des codes de sélection
**URL :** http://preprod.aboweb.com/aboweb/CodeSelectionService?wsdl
Le compte utilisateur sur cet environnement sera communiqué par mail.
| Structures d’échange
Ce chapitre présente les structures de données complexes utilisées comme paramètres et valeurs de retour des Web Services. Pour chaque structure, les noms, types et descriptions des paramètres sont fournies. Les valeurs obligatoires en entrée sont indiquées. Les données en lecture seule sont gérées exclusivement dans AboWeb.
|| WSCodeDeSelection
(*) id : le champ « id » n’est obligatoire que pour les méthodes « updateCodeSelection » et « deleteCodeSelection ».
(*) codeClient : le champ « codeClient » n’est obligatoire que pour la méthode « createCodeSelection ».
|| WSParamCS
Cette structure d'échange permet de retourner les colonnes de la table de paramétrage des CS. Qu'il s'agisse de CS de type :
* Code de sélection : c'est un code de sélection qui sera proposé sur la fiche du contact, un abonnement ou une facture
* Aide â la saisie : permet de des valeurs dans un champ de saisie, par exemple les civilités
* Origine abonnement : permet de lister les origines d'abonnement des tarifs d'abonnement. Uniquement pour les éditeurs utilisant cette fonctionnalité.
* Origine réabonnement : permet de lister les origines de réabonnement des tarifs d'abonnement. Uniquement pour les éditeurs utilisant cette fonctionnalité.
* Obsolète
**${color}[#0080ff](<allCodeSelection>)**
${color}[#0080ff](<!-- Utilisation du code de sélection -->)
<!--Integer : indique à quel menu de l'IHM ce code est attaché. Nous avons notamment les valeurs suivantes : -->**
**<!-- 0 pour Code de sélection : c'est un code de sélection qui sera proposé sur la fiche du contact, un abonnement ou une facture -->**
**<!-- 1 pour Aide â la saisie : permet de des valeurs dans un champ de saisie, par exemple les civilités -->**
**<!-- 2 pour Origine abonnement : permet de lister les origines d'abonnement des tarifs d'abonnement. Uniquement pour les éditeurs utilisant cette fonctionnalité. -->**
**<!-- 3 pour Origine réabonnement : permet de lister les origines de réabonnement des tarifs d'abonnement. Uniquement pour les éditeurs utilisant cette fonctionnalité -->**
**<!-- 4 pour Obsolète -->**
<typeMenu>1</typeMenu>
<!--String - Libellé correspondant au type indiqué juste au dessus. -->
**<typeMenuLabel>Code de sélection</typeMenuLabel>**
<!--Integer - indique a quelle entité le code de sélection est lié. Les valeurs possibles sont les suivantes : -->
<!-- 0 pour Client -->
<!-- 1 pour Abonnement -->
<!-- 2 pour Facture -->
<!-- 3 pour Ligne facture -->
<!-- 4 pour Tarif -->
**<typeEntite>0</typeEntite>**
<!--Boolean - Pour le type de menu Code de sélection : indique si code de sélection n'est pas utilisé dans le calcul des OJD. -->
**<pasOJD>true</pasOJD>**
<!--Boolean - Pour le type de menu Code de sélection : indique si code de sélection est affiché sur le CRM : Code de sélection présenté en avant sur la fiche du contact -->
**<estDansCrm>true</estDansCrm>**
<!--List<Integer> - Pour le type de menu Code de sélection : indique la liste des fonctionnalités auquelles ce code de sélection est associé. Il peut y en avoir une ou plusieurs. Les valeurs possibles sont les suivantes : -->
<!-- 0 pour Classique -->
<!-- 1 pour Graces copies -->
<!-- 2 pour Relances -->
<!-- 3 pour Versions -->
**<fonctions>0</fonctions>**
**<fonctions>2</fonctions>**
${color}[#0080ff](<!-- Information particulière -->)
<!--Integer - Uniquement pour le type de menu 2 - Origine abonnement uniquement. Permet de relier un code de sélection à un autre code de sélection. Permet de lier la référence origine à son lot, le lot au segment etc ... -->
**<parent>503</parent> **
${color}[#0080ff](<!-- Informations concernant la création et la modification du code de sélection -->)
<!--Date - Date de création du code de sélection -->
**<creation>2019-06-26T14:53:31+02:00</creation>**
<!--String 20 - Utilisateur qui a créé le code de sélection -->
**<utilCreation>Teddy Martin</utilCreation>**
<!--Date - Date de dernière modification du code de sélection -->
**<modification>2019-06-26T14:53:31+02:00</modification>**
<!--String 20 - Utilisateur qui a modifié le code de sélection -->
**<utilModification>Teddy Martin</utilModification>**
${color}[#0080ff](<!-- Informations sur le code de sélection -->)
<!--Integer - Identifiant unique du code de selection -->
**<id>1063</id>**
<!--String - Nom du code -->
**<libelle>MON_CODE_CS_TEST</libelle>**
<!--Integer - Type de saisie : 1 pour saisie libre, 2 pour sur liste, 3 pour Oui-Non -->
**<typeSaisie>2</typeSaisie>**
<!--Boolean - Si l 'on a choisi un type de saisie sur liste, la valeur true indique que l'on pourra choisir plusieurs valeurs de la liste, la valeur false indique que l'on pourra en saisir qu'une seule -->
**<multiple>true</multiple>**
<!--Boolean - Si l'on choisi un type de saisie sur liste la valeur de choix sera à true. Sinon elle sera à false -->
**<choix>false</choix>**
<!--String - Famille de regroupement du code de sélection -->
**<famille>Client</famille>**
<!--Boolean - Indique si le code de sélection est obligatoire. -->
**<obligatoire>true</obligatoire>**
<!-- Valeur du code de sélection -->
<!--String - Valeur par défaut -->
**<defaut>MA_VALEUR_PAR_DEFAUT</defaut>**
<!--List<String> - Liste des valeurs définies pour ce code de sélection -->
**<valeurs>MA VALEUR 1</valeurs>**
**<valeurs>MA VALEUR 2</valeurs>**
**<valeurs>MA VALEUR 3</valeurs>**
**${color}[#0080ff](</allCodeSelection>)**
| Services
Ce chapitre décrit l’ensemble des services nécessaires à la réalisation des cas d’utilisation. Pour chaque service, plusieurs informations sont fournies : le nom du service, la fonctionnalité réalisée, les paramètres en entrée, la valeur de retour et les cas d’erreurs (SOAPFault). Les structures de données complexes sont présentées dans le chapitre "Structures d'échange".
Les informations concernant l’éditeur sont déduites de l’utilisateur authentifié. On considère qu’il n’y a qu’une société.
Pour des raisons de performance, la taille des listes retournée est limitée à 50 objets. Par ailleurs, il faut éviter de réaliser des opérations d’ajout/suppression d’objets pendant le parcourt des listes à moins de savoir gérer le décalage à l’aide de l’attribut « offset ».
|| Référentiel des codes de sélection (getReferentielCodeSelection)
Retourne le contenu du référentiel des codes de sélection tous menus confondus, ordonnés par l'identifiant du code de sélection.
Voir la structure d'échange WSParamCS pour plus de détails.
__Trame :__
**${color}[#0080ff](<ges:getReferentielCodeSelection>)**
${color}[#0080ff](<!—Paramètre optionnel:-->)
<!--Integer – Index du premier élément de la liste (commence par 0) - Les codes de sélections sont ordonnés par id croissant -->
**<offset>?</offset>**
**${color}[#0080ff](</ges:getReferentielCodeSelection>)**
__ Retour :__
Structure d’échange **List<WSParamCS>**
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
209 : Pas de liste de valeurs pour ce type de code de sélection
212 : Code de sélection inconnu
|| Valeurs possibles pour un code de sélection de type Sur Liste (getLibelles)
Lorsque l'on administre les codes de sélection de type "Sur Liste", on leur attribue des valeurs possibles.
Seules ces valeurs pourront être choisies lorsque l'on ajoutera ce code de sélection à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif.
Avec ce service, on récupère les valeurs possibles d'un code de sélection identifié par son code.
__Trame :__
**${color}[#0080ff](<ges:getLibelles>)**
${color}[#0080ff](<!—Paramètres obligatoires:-->)
<!--Integer - Identifiant interne du code de sélection. Soit l'id de la structure WSParamCS -->
**<type>4521</type>**
**${color}[#0080ff](</ges:getLibelles>)**
__ Retour :__
List<libelle> : Liste de libellés correspondant aux <valeurs> de la structure WSParamCS.
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide
209 : Pas de liste de valeurs pour ce type de code de sélection
|| Ajouter un code sélection à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (createCodeSelectionEntite)
Permet d'associer un code de sélection et sa valeur sur une fiche client, une facture ou un tarif.
Nous parlons ici uniquement des codes de sélection de type 0, à savoir les éléments du référentiel des codes de sélection dont la structure d'échange WSParamCS contient :
<typeMenu>0</typeMenu>
<typeMenuLabel>Code de sélection</typeMenuLabel>
Ici l'on ne peut faire que des créations. Il faut utiliser updateCodeSelectionByRefInterneCs pour modifier une valeur.
__Trame :__
**${color}[#0080ff](<ges:createCodeSelectionEntite>)**
${color}[#0080ff](<!—Paramètres obligatoires:-->)
<!--String - indique a quelle entité le code de sélection est lié. Les valeurs possibles sont les suivantes : -->
<!-- Client -->
<!-- Abonnement -->
<!-- Facture -->
<!-- Ligne facture -->
<!-- Tarif -->
**<Entite>Client</Entite>**
<!--Integer - Identifiant interne aboweb correspondant à l'entité. A savoir : -->
<!-- le code du client pour l'entité Client -->
<!-- la référence de l'abonnement pour l'entité Abonnement -->
<!-- la référence interne de la facture pour l'entité Facture -->
<!-- la référence interne de la ligne de facture pour l'entité Ligne facture -->
<!-- la référence interne du tarif pour l'entité Tarif -->
**<refTechnEntite>45</refTechnEntite>**
<!--Integer - Identifiant interne du code de sélection. Soit l'id de la structure WSParamCS -->
**<refCs>4521</refCs>**
<!--String - Valeur du code de sélection. Soit, si le type de saisie du CS est : -->
<!-- '1 : saisie libre', indiquer une valeur de type string -->
<!-- '2 : sur liste', indiquer une des valeurs contenue dans la structure du WSParamCS correspondant au refCS-->
<!-- '3 : Oui-Non', indiquer la valeur true ou false -->
**<valeurCs>MA VALEUR</valeurCs>**
**${color}[#0080ff](</ges:createCodeSelectionEntite>)**
__ Retour :__
Integer : Identifiant du code de sélection associé au client. Soit l'ID de la structure d'échange WSCodeSelection.
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide
1307 : La valeur refCs existe déja.
|| Modifier la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (updateCodeSelectionByRefInterneCs).
Permet de modifier la valeur d'un code de sélection sur une fiche client, un abonnement, une facture ou un tarif.
Chaque valeur de code de sélection ajoutée pour un client, un abonnement, une facture ou un tarif est identifié par une référence unique.
C'est cette référence qui doit être indiquée en paramètre.
__Trame :__
**${color}[#0080ff](<ges:updateCodeSelectionByRefInterneCs>)**
${color}[#0080ff](<!—Paramètres obligatoires:-->)
<!--Integer - Référence interne de la valeur qui a été associée à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif. Soit l'ID de la structure d'échange WSCodeSelection -->
**<refInterneCs>382382</refInterneCs>**
<!--String - Nouvelle valeur à associé au code de sélection. Soit, si le type de saisie du CS est : -->
<!-- '1 : saisie libre', indiquer une valeur de type string -->
<!-- '2 : sur liste', indiquer une des valeurs contenue dans la structure du WSParamCS correspondant au refCS-->
<!-- '3 : Oui-Non', indiquer la valeur true ou false -->
**<newValue>MA NOUVELLE VALEUR</newValue>**
**${color}[#0080ff](</ges:updateCodeSelectionByRefInterneCs>)**
__ Retour :__
Integer :
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide
|| Supprimer la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (deleteCodeSelection)
Permet de supprimer la valeur d'un code de sélection sur une fiche client, un abonnement, une facture ou un tarif.
Chaque valeur de code de sélection ajoutée pour un client, un abonnement, une facture ou un tarif est identifié par une référence unique.
C'est cette référence qui doit être indiquée en paramètre.
__Trame :__
**${color}[#0080ff](<ges:deleteCodeSelection>)**
${color}[#0080ff](<!—Paramètres obligatoires:-->)
<!--Integer - Référence interne de la valeur qui a été associée à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif. Soit l'ID de la structure d'échange WSCodeSelection -->
**<refInterneCs>382382</refInterneCs>**
**${color}[#0080ff](</ges:deleteCodeSelection>)**
__ Retour :__
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide
|| Liste des codes de sélection et valeurs associés à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (getCodeSelection)
Retourne la liste des codes de sélection et valeurs associés à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif.
Voir la structure d'échange WSCodeSelection pour plus de détails.
__Trame :__
**${color}[#0080ff](<ges:getCodeSelection>)**
${color}[#0080ff](<!—Paramètres obligatoires :-->)
<!--String - indique a quelle entité le code de sélection est lié. Les valeurs possibles sont les suivantes : -->
<!-- Client -->
<!-- Abonnement -->
<!-- Facture -->
<!-- Ligne facture -->
<!-- Tarif -->
**<Entite>Client</Entite>**
<!--Integer - Identifiant interne aboweb correspondant à l'entité. A savoir : -->
<!-- le code du client pour l'entité Client -->
<!-- la référence de l'abonnement pour l'entité Abonnement -->
<!-- la référence interne de la facture pour l'entité Facture -->
<!-- la référence interne de la ligne de facture pour l'entité Ligne facture -->
<!-- la référence interne du tarif pour l'entité Tarif -->
**<refTechnEntite>45</refTechnEntite>**
${color}[#0080ff](<!—Paramètres optionnels :-->)
<!--Integer - Identifiant interne du code de sélection. Soit l'id de la structure WSParamCS -->
**<refCs>4521</refCs>**
<!--Integer – Index du premier élément de la liste (commence par 0) - Les codes de sélections sont ordonnés par id croissant -->
**<offset>?</offset>**
**${color}[#0080ff](</ges:getCodeSelection>)**
__ Retour :__
Structure d’échange **List<WSCodeSelection >**
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
209 : Pas de liste de valeurs pour ce type de code de sélection
212 : Code de sélection inconnu
|| A NE PLUS UTILISER : Ajouter un code sélection pour un client (createCodeSelection)
Ce WS a été conservé pour les clients qui l'utilisent déjà et possède donc déjà la documentation de ce WS.
Il faut désormais utiliser le WS documenté plus haut : Ajouter un code sélection à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (createCodeSelectionEntite).
|| A NE PLUS UTILISER : Modification de la valeur d'un code sélection associé client (updateCodeSelection)
Ce WS a été conservé pour les clients qui l'utilisent déjà et possède donc déjà la documentation de ce WS.
Il faut désormais utiliser le WS documenté plus haut : Modifier la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (updateCodeSelectionByRefInterneCs).
|| A NE PLUS UTILISER : Liste des valeurs des codes de sélection d'un client (listCodeSelection)
Ce WS a été conservé pour les clients qui l'utilisent déjà et possède donc déjà la documentation de ce WS.
Il faut désormais utiliser le WS documenté plus haut : Modifier la valeur d'un code sélection associé à un client, à un abonnement, à une facture, à une ligne facture ou à un tarif (updateCodeSelectionByRefInterneCs).