Guide intégrateur

Intégration Relais Pickup DPD

Objet

La présente section du document, à destination des webdesigner, a pour objectif de définir l’ensemble des modifications des thèmes graphiques nécessaires à la mise en œuvre de l’offre DPD.

Rétrocompatibilité

Les clients ne souhaitant PAS utiliser l’offre DPD n’ont aucune modification à faire. Les changements effectués sur le processus de commande sont totalement compatibles avec leurs thèmes graphiques actuels. Il peut cependant être intéressant d’intégrer les modifications des templates suivants qui apportent des améliorations ergonomiques et fonctionnelles (cf. leur section respective ci dessous).

Les clients qui souhaitent utiliser l’offre DPD doivent procéder à la mise à jour des fichiers suivants de leur thème graphique :

Dans tous les cas, nous recommandons la mise en place de toutes les modifications, facultatives et obligatoires, décrites dans ce document, même pour les clients ne voulant pas utiliser DPD.

Le détail de ces modifications est exposé dans les sections suivantes.

Template widget/commandes/transporteur/dpd.html

Utilisation du template

La page /ecommerce/dpd.html est utilisée comme page portail afin d'accueillir l'iframe de choix de point relais. Cette page sert également de page de retour. En cas d’erreur ou d’indisponibilité de la plateforme DPD, ce template est également utilisé.

Rétrocompatibilité

Ce template est inexistant dans les thèmes actuellement déployés. Sa présence est obligatoire pour utiliser l’offre DPD. Si le transporteur est activé malgré l’absence de ce fichier dans le thème graphique du site, un message d’erreur indiquant ce défaut de configuration sera affiché à la place de la page portail, empêchant alors de finir le processus de commande pour les acheteurs ayant choisit le transporteur DPD Relais Pickup.

Récapitulatif des balises et bloc disponibles

Bloc Balise Description
main.intitule {intitule} La Balise intitule contient l’intitulé du widget « Livraison » tel qu’il est défini dans la configuration de ce dernier. Le Bloc main.intitule n’est pas affiché si la valeur de l'intitulé est vide.
main.erreurs Le Bloc erreurs est affiché si la page contient des erreurs
main.erreurs.erreur {erreur} Chaque erreur est affichée dans son propre bloc et affectée à la balise erreur
main.formulaire {iframe} Adresse de l'iframe pour l'intégration générique de la recherche de points relais
{gmaps_key} Affiche la clé API GoogleMaps
{transporteur_id} Identifiant du transporteur DPD Relais Pickup
{adresse} Affiche l'adresse de livraison courante
{ville} Affiche la ville de livraison courante
{cp} Affiche le code postal de livraison courant

Exemple complet

<!-- BEGIN:main -->
    <!-- BEGIN:intitule --><h2>{intitule}</h2><!-- END:intitule -->
    <!-- BEGIN:erreurs -->
        <div>
        <!-- BEGIN:erreur -->{erreur}<br /><!-- END:erreur -->
        </div>
     <!-- END:erreurs -->
    <!-- BEGIN:formulaire -->
        <iframe src="{iframe}"></iframe>
    <!-- END:formulaire -->
    <a href="/ecommerce/transporteurs.html">Choisir un autre mode de Livraison</a>
<!-- END:main -->

Alternative d'intégration

Il est égalment possible de se passer de l'iframe et de faire une intégration sur mesure dans le site le choix du point relais. A la charge de l'intégrateur de developper l'ensemble des codes HTML, CSS et Javascript. Il est cependant conseillé de s'inspirer du fonctionnement de la page à l'intérieur de l'iframe (visible à l'adresse /embed/dpd.html du site un fois que le transporteur DPD Relais Pickup est séléctionné dans le tunnel de commande).

Kiubi fournit des données complémentaires dans le template du widget pour faciliter cette intégration :

Il est obligatoire d'intégration le choix du point relais dans le bloc main.formulaire.

L'initialisation d'une cart GoogleMaps est possible en utlisant le clé API GoogleMaps configurée dans le transporteur DPD Relais Pickup avec {gmaps_key}.

L'API Front-office dispose d'un endpoint de recherce des points relais. Grâces aux balises {transporteur_id}, {adresse}, {ville} et {cp} il est possible de forger une requête vers ce endpoint et récupérer une liste de point relais : 

GET /api/v1/cart/carriers/{transporteur_id}/pickup?address={adresse}&city={ville}&zipcode={cp}

Ou plus simplement avec le client API Front-office :

kiubi.get('/cart/carriers/'+transporteur_id+'/pickup', {
    address:'...',
    city:'...',
    zipcode:'...'
});

Pour désigner un point relais comme adresse de livraison de la commande, il faut forger une requête de type POST vers la page /ecommerce/dpd.html avec un paramètre data comportant le JSON suivant : 

{
    status: 'ok',
    relay: {
        relay_id : 'XXXX',
        name: 'XXXX',
        address : 'XXXX',
        city : 'XXXX'
        zipcode : 'XXXX'
    }
}

Si le point relais est accepté, l'utilisateur est redirigé vers la page de récapitulatif de commande. Sinon un message d'erreur est affiché par le bloc main.erreurs et le bloc main.formulaire n'est pas affiché.

Pour forcer l'affichage d'une erreur, il suffit de changer le paramètre data avec un JSON équivalant à : 

{
    status: 'error',
    error: 'Message d\'erreur'
}