| Services documentés dans cet article
Structure d'échange (WSAdresse)
Création et modification d'adresse (createOrUpdateAdresseEx)
Suppression d'une adresse ( deleteAdresseEx)
Visualisation d'une adresse ( getAdresseByRefAdresse)
Liste des adresses d'un client (getAdresses)
Liste des adresses d'un type donné d'un client ( getAdressesByTypeAdresse)
Liste des clients en doublons (getDoublonsClients)
| 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:getAdresse>
[…]
</ges:getAdresse>
</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 adresses
**URL :** http://preprod.aboweb.com/aboweb/AdresseService?wsdl
Le compte utilisateur sur cet environnement sera communiqué par mail.
| Description des nouveautés ( à partir de la version 2.19 ) :
Les anciennes versions des services de l'API Adresses pourront toujours être utilisées, mais il est préconisé d'utiliser les nouvelles versions pour les raisons suivantes :
Dans les anciennes versions, une adresse est identifiée par le code client et le type d'adresse. Or on peut avoir plusieurs adresses différentes pour les types suivants :
- Adresse de livraison : 1
- Adresse de relance d’abonnement : 2
- Adresse de facturation : 3
Pour corriger ce problème, de nouveaux services ont été ajouté à l'API Adresses. Dans ces nouveaux services, une adresse sera identifiée par sa référence ( identifiant unique de l'adresse).
| 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.
|| WSAdresse
(*) 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.
(**) typeAdresse :
- Adresse principale : 0
- Adresse de livraison : 1
- Adresse de relance d’abonnement : 2
- Adresse de facturation : 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'adresse (createOrUpdateAdresseEx)
Si l'on renseigne en paramètre une référence qui n'existe pas, alors il s'agira d'une création d'adresse. Mais attention : on n'utilisera pas la référence donnée en paramètre pour créer l'adresse. Une autre référence sera calculée et retournée par le service.
|| Création d'adresse (updateAdresse)
|| Suppression d'une adresse ( deleteAdresseEx)
|| Visualisation d'une adresse ( getAdresseByRefAdresse)
|| Liste des adresses d'un client (getAdresses)
|| Liste des adresses d'un type donné d'un client ( getAdressesByTypeAdresse)
|| Liste des clients en doublons (getDoublonsClients)
Nous avons la structure d’échange WSAdresse en entrée, mais il n’est pas nécessaire de remplir tous les champs de la structure d'échange pour trouver les doublons.
Il suffit de remplir les champs suivants :
Pour la recherche par NOM+NO VOIE+MOT DIRECTEUR+CP+VILLE+CODE ISO PAYS il suffit de remplir les champs suivants. Les autres sont facultatifs et ne seront pas pris en compte :
Attention : le NOM est le nom renseigné dans le champ NOM de l’adresse AboWeb. On ne prend jamais en compte la société.
<typeDoublon>1</typeDoublon>
<adresse>
<nom>?</nom>
<noVoie>?</noVoie>
<ville> ?</ville>
<motDirecteur> ?</motDirecteur>
<cp> ?</cp>
<codeIsoPays> ?</codeIsoPays>
</adresse>
Option : Si l’on renseigne en plus l’email <email>?</email>, et que l’on ne trouve pas de clients qui entre en doublons sur les NOM+NO VOIE+MOT DIRECTEUR+CP+VILLE+CODE ISO PAYS, alors on fera une deuxième recherche sur l’email en question.
Pour la recherche par EMAIL il suffit de remplir les champs suivants. Les autres sont facultatifs et ne seront pas pris en compte :
<typeDoublon>2</typeDoublon>
<adresse>
<email>?</email>
</adresse>