| Services documentés dans cet article
Structure d'échange (WSClients)
Création et modification d'un client (createOrUpdateClientEx)
Authentification d'un client par son email (authenticateEncrypteByEmail)
Modification du statut d'un client (UpdateStatut)
Visualisation d'un client identifié par son code (getClient)
Visualisation d'un client identifié par un ancien code (getClientByAncienCode)
Visualisation d'un client identifié par son email (findClientByEmail)
Liste de tous les clients (getClients)
Nombre total de clients (getNbClients)
Liste des clients d'un tiers (getPayesPar)
Nombre de clients d'un tiers (getNbPayesPar)
Liste des clients ayant une valeur de code de sélection particulière (getClientsByCodeSelection)
Nombre de clients ayant une valeur de code de sélection particulière (getNbClientsByCodeSelection)
Liste des clients ayant une origine particulière (getClientsByOrigine
Nombre de clients ayant une origine particulière (getNbClientsByOrigine)
Liste des clients ayant un code transco particulier (getClientsByCodeClientTransco)
Nombre de clients ayant un code transco particulier (getNbClientsByCodeClientTransco)
Liste des clients modifiés entre 2 dates (getClientsModifiedBetween)
Nombre de clients modifiés entre 2 dates (getNbClientsModifiedBetween)
Liste des clients ayant un type donné (getClientsByType)
Nombre de clients ayant un type donné (getNbClientsByType)
Envoi d'un mot de passe par mail (sendPassword)
Liste des clients par type et code postal (getClientsWithCriteria)
Nombre de clients par type et code postal (getNbClientsWithCriteria)
| 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:getClient>
[…]
</ges:getClient>
</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 clients
**URL :** http://preprod.aboweb.com/aboweb/ClientService?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.
|| WSClients
(*) CodeClient : le « code client » est récupéré lors de la création du client dans AboWeb. Il n’est pas modifiable par la suite.
(*) Liste de valeurs des statuts possibles pour un client :
Normal : 0
Tiers : 1
Payés par : 2
Prospect : 3
| 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 ».
|| Création et modification d'un client (createOrUpdateClientEx)
__Variable système WS_FORCE_UPDATE_ONLY_SENDING_PARAMS __
Le fonctionnement du WS createOrUpdateClientEx dépend d'une variable système WS_FORCE_UPDATE_ONLY_SENDING_PARAMS.
Selon la valeur de cette variable, il faut ou non impérativement renseigner tous les paramètres possibles du client lors d'une modification de client.
Pour les éditeurs qui ont commencé à utiliser Aboweb à partir de juillet 2019, la variable système sera celle par défaut à savoir **True**.
Pour les éditeurs qui ont commencé avant, la variable système a été paramétrée en accord avec eux. Si l'éditeur n'avait rien demandé de particulier elle doit être à **False**. Si un éditeur souhaite changer de fonctionnement, il peut en faire la demande.
__Fonctionnement selon la valeur de la variable système WS_FORCE_UPDATE_ONLY_SENDING_PARAMS __
Si WS_FORCE_UPDATE_ONLY_SENDING_PARAMS = **False**
Si Les rubriques passées en paramètres correspondant aux colonnes en Lecture/Ecriture de la structure WSClient sont remplacées, les rubriques non passées en paramètre correspondant aux colonnes en Lecture/Ecriture sont effacées.
Si WS_FORCE_UPDATE_ONLY_SENDING_PARAMS = **True**
Si Les rubriques passées en paramètres correspondant aux colonnes en Lecture/Ecriture de la structure WSClient sont remplacées, les rubriques non passées en paramètre correspondant aux colonnes en Lecture/Ecriture sont conservée dans l’état ou elles étaient.
Après modification des champs, la cohérence globale du client est vérifiée avant enregistrement.
|| Mise à jour du client (updateClient)
|| Authentification d'un client par son email (authenticateEncrypteByEmail)
|| Modification du statut d'un client (UpdateStatut)
Liste de valeurs des statuts possibles pour un client :
Normal : 0
Tiers : 1
Payés par : 2
Prospect : 3
|| Visualisation d'un client identifié par son code (getClient)
|| Visualisation d'un client identifié par un ancien code (getClientByAncienCode)
|| Visualisation d'un client identifié par son email (findClientByEmail)
|| Liste de tous les clients (getClients)
|| Nombre total de clients (getNbClients)
|| Liste des clients d'un tiers (getPayesPar)
|| Nombre de clients d'un tiers (getNbPayesPar)
|| Liste des clients ayant une valeur de code de sélection particulière (getClientsByCodeSelection)
|| Nombre de clients ayant une valeur de code de sélection particulière (getNbClientsByCodeSelection)
|| Liste des clients ayant une origine particulière (getClientsByOrigine)
|| Nombre de clients ayant une origine particulière (getNbClientsByOrigine)
|| Liste des clients ayant un code transco particulier (getClientsByCodeClientTransco)
|| Nombre de clients ayant un code transco particulier (getNbClientsByCodeClientTransco)
|| Liste des clients modifiés entre 2 dates (getClientsModifiedBetween)
!
|| Nombre de clients modifiés entre 2 dates (getNbClientsModifiedBetween)
|| Liste des clients ayant un type donné (getClientsByType)
|| Nombre de clients ayant un type donné (getNbClientsByType)
|| Envoi d'un mot de passe par mail (sendPassword)
__Exemple de trame :__
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ges="http://www.gesmag.com/">
<soapenv:Header/>
<soapenv:Body>
<ges:sendPassword>
** <refSociete>1</refSociete>**
** <email>[email protected]</email>**
</ges:sendPassword>
</soapenv:Body>
</soapenv:Envelope>
__Exemple de retour ( ici le mail a bien été envoyé) :__
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<S:Body>
<ns2:sendPasswordResponse xmlns:ns2="http://www.gesmag.com/">
** <result>true</result>**
</ns2:sendPasswordResponse>
</S:Body>
</S:Envelope>
__Exemple de retour erreur ( ici l'email ne correspondait à aucun contact) :__
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<S:Fault xmlns:ns4="http://www.w3.org/2003/05/soap-envelope">
** <faultcode>204</faultcode>**
** <faultstring>Client inexistant</faultstring>**
</S:Fault>
</S:Body>
</S:Envelope>
|| Liste des clients par type et code postal (getClientsWithCriteria)
Retourne une liste de 50 clients maximum, ordonnée par «code client» croissant.
Retourne :
* la liste des clients d'un type donné,
* ou la liste des clients d'un type et d'un code postal donné.
Les types de clients possibles sont :
* Client
* Tiers
* Payés par
* Prospect
* Prescripteur
__Trame :__
**${color}[#0080ff](<ges:getClientsWithCriteria>)**
**<criteria>**
${color}[#0080ff](<!—Paramètres obligatoires :-->)
<!--Integer - Type de contacts à rechercher. Les valeurs possibles sont les suivantes : -->
<!-- 0 : Client -->
<!-- 1 : Tiers -->
<!-- 2 : Payés par -->
<!-- 3 : Prospect -->
<!-- 4 : Prescripteur -->
**<typeClient>0</typeClient>**
${color}[#0080ff](<!—Paramètres optionnels :-->)
<!--String - Code postal -->
**<cp>35000</cp>**
**</criteria>**
${color}[#0080ff](<!—Paramètres optionnels :-->)
<!--Integer – Index du premier élément de la liste (commence par 0) - Les clients sont ordonnés par code client croissant – Ce WS retourne 50 clients maximum – Par défaut on retourne les 50 premiers clients. Si l on souhaite les 50 suivants indiquer 50 dans offset, puis 100 pour les 50 suivants et ainsi de suite -->
**<offset>0</offset>**
**${color}[#0080ff](</ges:getClientsWithCriteria>)**
__ Retour :__
Structure d’échange **List<WSClients >**
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide
|| Nombre de clients par type et code postal (getNbClientsWithCriteria)
Retourne :
* le nombre de clients d'un type donné,
* ou le nombre de clients d'un type et d'un code postal donné.
Les types de clients possibles sont :
* Client
* Tiers
* Payés par
* Prospect
* Prescripteur
__Trame :__
**${color}[#0080ff](<ges:getNbClientsWithCriteria>)**
**<criteria>**
${color}[#0080ff](<!—Paramètres obligatoires :-->)
<!--Integer - Type de contacts à rechercher. Les valeurs possibles sont les suivantes : -->
<!-- 0 : Client -->
<!-- 1 : Tiers -->
<!-- 2 : Payés par -->
<!-- 3 : Prospect -->
<!-- 4 : Prescripteur -->
**<typeClient>0</typeClient>**
${color}[#0080ff](<!—Paramètres optionnels :-->)
<!--String - Code postal -->
**<cp>35000</cp>**
**</criteria>**
**${color}[#0080ff](</ges:getNbClientsWithCriteria>)**
__ Retour :__
<!--Integer - Nombre de clients correspondant aux critères : -->
**<result>2</result>**
__ Erreurs :__
100 : Erreur technique
101 : Erreur d’authentification
200 : Erreur fonctionnelle
202 : Donnée invalide