Ce document a pour but d’expliquer le fonctionnement des web-services aux développeurs partenaires du projet La Presse Libre utilisant cette technologie. Actuellement, trois web-services sont à implémenter dans votre solution pour assurer une bonne communication avec la plateforme La Presse Libre :

• Un service de vérification, qui permettra à La Presse Libre de vérifier l’existence d’un compte utilisateur dans la base de données du partenaire.
• Un service de création de compte, qui permettra de propager un nouveau compte créé sur La Presse Libre dans la base de données partenaire.
• Un service de mise à jour de compte, qui permettra de mettre à jour un compte utilisateur (abonnement / reconduite de l’abonnement ou informations personnelles) sur la plateforme partenaire.

Différents SDK sont mis à votre disposition pour vous aider à implémenter les web service La Presse Libre selon la technologie utilisée sur votre plateforme. Voici la liste des SDK proposés :

• PHP
• ASP.NET
• NodeJS

Une documentation propre à chaque SDK vous sera fournie en complément de ce document dans lequel vous trouverez des précisions liées à la technologie employée.

Avant de commencer l’implémentation des web services, assurez-vous que votre application est correctement configurée. Voici comment procéder

Le message envoyé et attendu en réponse par LPL pour chaque web-service est au format JSON. Pour sécuriser les connexions entre les différentes plateformes partenaires, il sera nécessaire d’utiliser un chiffrement HTTPS. Pour vérifier l’identité des plateformes lors d’échange d’informations, des headers supplémentaires seront ajoutés dans chaque requête http. Ils auront pour caractéristiques :

Chaque partenaire se verra remettre un code secret qui ne devra absolument pas transiter d’une plateforme à une autre. Pour vérifier l’identité de l’émetteur du message, il sera nécessaire de comparer la valeur du header X-LPL avec celle résultant de la fonction de hachage SHA-1 des valeurs de X-TS, X-PART et du code secret fourni. Si les deux signatures correspondent cela signifie que l’émetteur est de confiance.

La signature sera présentée comme suit : 1+1425630521+a285b6478b254 (X-PART + X-TS + code secret)

Les 3 parties de la signature seront séparées par des signes " + " pour faciliter leur différenciation. Il est donc important que les valeurs ne contiennent pas de signe " + " auquel cas elles ne pourront plus être différenciées.

Voici un exemple de signature hachée via SHA-1 telle qu’on la retrouvera dans le header http : afba34a2a11ab13eeba5d0a7aa22bbb6120e177b

Le récepteur devra construire la signature qu’il attend (X-PART + X-TS + code secret), effectué un hachage SHA-1 puis comparer la signature obtenue avec celle présente dans le header X-LPL. Si les deux signatures correspondent, la transaction est acceptée.

Pour construire la signature, le récepteur devra récupérer :

• Le code partenaire : Chaque partenaire aura un code unique qu’il devra stocker dans le fichier de configuration de son application. Il va lui permettre de vérifier que le message lui est destiné.
• Le timestamp : Présent dans le header http. Il va permettre de limiter les attaques de type « replay » consistant à intercepter des paquets de données et à les retransmettre tels quel (sans aucun déchiffrement) au serveur de destination. Il faudra donc vérifier l’intervalle entre les différentes transactions et les rejeter si le délai est trop long.
• Le code secret : Permet d’identifier l’expéditeur du message. Il sera également stocké dans le fichier de configuration de l’application.

Pour des raisons de sécurités supplémentaires, lorsque le body des requêtes http contiendrons des informations (requêtes POST, PUT), elles seront chiffrées à l’aide d’un algorithme de chiffrement AES utilisant une clé de 256 bits puis codé en base64. Les partenaires devront donc implémenter les algorithmes de chiffrement/déchiffrement pour pouvoir lire et envoyer les données.

Ce service a pour but de récupérer des informations utilisateur sur une plateforme partenaire à partir de paramètres fournis par LPL.

URL d’appel : https://nom_de_domaine_partenaire/ws/verification ?crd=credentials

Type de requête HTTP : GET

Modèle de données : Ces modèles vous seront fournis avec le SDK

Dans le cas où une correspondance est trouvée côté partenaire, ce dernier devra stocker en base de données le code utilisateur transmis dans la requête. Ceci va permettre d’identifier de manière unique le compte partenaire à n’importe quel moment même dans le cas où l’utilisateur aurait changé l’adresse mail de son compte côté partenaire ou côté LPL.

Pour des raisons de sécurité, les identifiants ne passent pas en clair dans les paramètres de l’url. Ils ont été préalablement chiffrés côté LPL avec l’algorithme de chiffrement AES avec une clé de 256 bits puis codé en base64. La clé de chiffrement et de déchiffrement sera commune aux deux plateformes. Les identifiants après chiffrement ne forment donc qu’un seul paramètre nommé « crd ».

Exemple :

https://<nom_de_domaine_partenaire>/ws/verif?crd=EAAAAN0IgBKpv388vEIGMolrwNM2s/CmbTWzgusRYCCESiu6LjN95xf7ojfJHYQpCAq6G+zKK/WsrNSnKHpyj/tIjwzLJZ5dEcLSxrYNLAjxR/CL

Après déchiffrement du paramètre crd nous obtenons la chaine de caractères suivante :

{\"Mail\":\"[email protected]\",\"Password\":\"XXXXXXXXXXXXX\",\"CodeUtilisateur\":\"XXXXXXXXXX\"}

Pour pouvoir récupérer les identifiants de l’utilisateur, il suffira d’utiliser une fonction de décodage de structure JSON.

Il existe 3 cas d’utilisation du web service de vérification :

• après déchiffrement ne contient qu’une adresse mail et un code utilisateur: Cela signifie que l’utilisateur vient de s’inscrire sur LPL et que la plateforme vérifie automatiquement si il possède un compte avec la même adresse mail sur la plateforme partenaire. Le partenaire devra donc uniquement rechercher l’adresse mail transmise dans la requête en base de données.
• après déchiffrement contient une adresse mail, un mot de passe et le code utilisateur : Dans le cas où l’adresse mail de l’utilisateur sur LPL n’est pas la même que celle utilisée sur une plateforme partenaire, l’utilisateur a la possibilité de lier ses deux comptes en renseignant ses identifiants partenaire depuis ses paramètres de compte LPL. Dans ce cas, le partenaire devra rechercher l’adresse mail transmise dans la requête en base de données mais également s’assurer de la validité du couple adresse mail et mot de passe.
• après déchiffrement ne contient qu’un code utilisateur : Dans le cas où l’utilisateur souhaite souscrire un abonnement, il est important de vérifier de nouveau son compte utilisateur lié côté partenaire pour s’assurer qu’il n’a pas souscrit d’abonnement depuis la plateforme partenaire entre temps ou que son abonnement n’a pas expiré ou n’a pas été annulé (pour cause de remboursement par exemple).

Structure du flux de réponse (JSON)

Cas n°1 : le compte existe

{	
    "AccountExist" : true,
    "Mail" : "[email protected]",
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa",
    "TypeAbonnement" : "mensuel",
    "DateSouscription" : "2015-02-04",
    "DateExpiration" : "2015-03-04",
    "PartenaireID" : 2
}

Cas n°2 : le compte n’existe pas

{
    "AccountExist" : false,
    "Mail" : "[email protected]",
    "CodeUtilisateur" : null,
    "TypeAbonnement" : null,
    "DateSouscription" : null,
    "DateExpiration" : null,
    "PartenaireID" : 2 
}

Ce service a pour but de fournir des informations concernant un utilisateur à la plateforme partenaire pour qu’elle puisse lui créer un compte et propager son abonnement. À noter que l’appel de ce service est fait après que l’utilisateur ait composé son abonnement et qu’il ait relié ses comptes partenaires. Les données d’entrée fournies par LPL seront sérialisées en JSON dans le body de la requête.

URL d’appel : https://nom_de_domaine_partenaire/ws/creationCompte

Type de requête HTTP : POST

Modèle de données : Ces modèles vous seront fournis avec le SDK

Ce web service sera appelé uniquement si la vérification n’a pas abouti et que l’utilisateur n’a pas lié ses comptes manuellement.

Encore une fois, il est primordial de stocker le code utilisateur transmis lors de la création du compte utilisateur côté partenaire pour les futurs appels du web service de mise à jour.

Structure du flux de réponse (JSON)

{	 
    "Pseudo" : "Pierrot",
    "Mail" : "[email protected]",
    "Password" : "pass",
    "TypeAbonnement" : "mensuel",
    "DateSouscription" : "2015-02-04",
    "DateExpiration" : "2015-03-04",
    “Tarif” : 3.50
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa",
    "Statut" : 6
}

Dans le cas où le compte existe déjà sur la plateforme partenaire, ce dernier devra renvoyer le paramètre IsValid à false et signaler grâce au champ CodeEtat la raison. Ce cas de figure devrait être rare mais peut survenir si l’utilisateur change son adresse mail LPL, qu’il possède déjà un compte avec cette adresse mail sur la plateforme partenaire et qu’il a omis de lier ce compte. De plus, dans le cas où le nom d’utilisateur existe (code 3), nous allons générer un nouveau nom d’utilisateur en ajoutant un nombre aléatoire compris entre 0 et 999 à la fin (ex : UserName123) et renvoyer une requête de création. Ce web service sera lancé au maximum 3 fois, si nous obtenons 3 réponses négative la propagation sera stoppée.

Structure du flux de réponse (JSON)

Cas n°1 : succès de l'opération

{	 
    "IsValid" : true,
    “PartenaireID” : 2,
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa", 
    "CodeEtat" : 1
}

Cas n°2 : échec de l'opération

{	 
    "IsValid" : false,
    “PartenaireID” : 2,
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa"
    "CodeEtat" : 2
}

Ce service a pour but de mettre à jour les comptes utilisateurs sur les plateformes partenaire pour la propagation de l’abonnement à partir des paramètres fournis par LPL. Ce service sera exécuté après la validation du paiement de l’utilisateur et lors de la reconduite ou de l’annulation d’un abonnement. Les données d’entrées fournies par LPL seront sérialisées en JSON dans le body de la requête.

URL d’appel : https://nom_de_domaine_partenaire/ws/majCompte

Type de requête HTTP : PUT

Modèle de données : Ces modèles vous seront fournis avec le SDK

Pour ce web service, le partenaire devra s’appuyer sur le code utilisateur pour identifier le compte à mettre à jour. Le code ayant été préalablement stocké en base de données lors de la vérification dans le cas où une correspondance a été trouvée ou lors de la création de compte.

Structure du flux d’envoi (JSON)

{	 
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa",
    "TypeAbonnement" : "mensuel",
    "DateSouscription" : "2015-02-04",
    "DateExpiration" : "2015-03-04",
    "Tarif" : 3.50,
    "Statut" : 2
}

Structure du flux de réponse (JSON)

Cas n°1 : succès de l'opération

{	 
    "IsValid" : true,
    “PartenaireID” : 2,
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa", 
    "CodeEtat" : 1
}

Cas n°2 : échec de l'opération

{	 
    "IsValid" : false,
    “PartenaireID” : 2,
    "CodeUtilisateur" : "e5016836-dfbe-49e1-82d7-b8ac300da6aa"
    "CodeEtat" : 4
}

Comme cité plus haut, il y a plusieurs cas d’utilisation du web service de mise à jour :

• Après le règlement de l’abonnement utilisateur :

• Si le paiement réussi, le partenaire recevra en paramètre de la requête le statut 1 et devra alors mettre à jour la date d’expiration et activer l’abonnement
• Si le paiement échoue, le partenaire recevra en paramètre de la requête le statut 3 et devra alors suspendre l’abonnement jusqu’à ce qu’une nouvelle requête de mise à jour lui soit transmise avec le statut 1 pour activer l’abonnement ou 5 pour l’annuler.

• Tous les mois pour le renouvellement de l’abonnement :

• Si le paiement réussi, le partenaire recevra en paramètre de la requête le statut 1 et une date d’expiration et devra alors reconduire l’abonnement pour un mois en mettant la date d’expiration à jour.
• Si le paiement échoue, le partenaire recevra en paramètre de la requête le statut 3 et devra alors suspendre l’abonnement jusqu’à ce qu’une nouvelle requête de mise à jour lui soit transmise avec le statut 1 pour activer l’abonnement ou 5 pour l’annuler.

• Lorsque l’utilisateur ne souhaite pas renouveler son abonnement : le partenaire recevra en paramètre de la requête le statut 4 et devra alors résilié l’abonnement. Dans ce cas, l’utilisateur doit avoir accès à son abonnement jusqu’à la date d’expiration de l’abonnement.
• Lorsque l’utilisateur souhaite annuler immédiatement son abonnement : le partenaire recevra en paramètre de la requête le statut 5 et devra alors annuler l’abonnement. Il est important que l’annulation de l’abonnement prenne effet immédiatement après la réception de la requête.
• Lorsque l’utilisateur souhaite se faire rembourser son abonnement : le partenaire recevra en paramètre de la requête le statut 7 et devra alors annuler l’abonnement. Il est important que l’annulation de l’abonnement prenne effet immédiatement après la réception de la requête.