Installation

MapadirectSDK, client PHP pour l'API de la marketplace Mapadirect

Latest Version Total Downloads Requirements

MapaDirectSDK est une librairie PHP permettant de connecter votre site marchand à la marketplace MapaDirect.

La librairie permert de synchroniser son catalogue de produits et recevoir les commandes prises sur la marketplace.

Documentation

Vous trouverez ici la documentation de la librairie MapaDirectSDK.

Installer mapadirectsdk

Nous recommandons d'installer MapaDirectSDK via composer Composer.

# Install Composer
curl -sS https://getcomposer.org/installer | php

Ensuite, lancer la commande Composer command pour installer la dernière version de la librairie MapaDirectSDK:

php composer.phar require mapadirectsdk/mapadirectsdk

Après installation vous devez appeler l'autoload de Composer :

require 'vendor/autoload.php';

Vous pourrez ensuite mettre à jour la librairie MapaDirectSDK en utilisant composer:

composer.phar update

Guide des versions

Version Status Packagist Namespace Repo Doc PSR-7 PHP Version
1.x EOL mapadirectsdk/mapadirectsdk MapaDirectSDK master develop No >= 5.6

Validateur, Exceptions & Logger

Validateurs de données soumises à l'API à travers les webservices

Le SDK possède une validation des données avant soumission à MapaDirect. Si les données à envoyer ne sont pas 100% conforme, la requète ne sera pas transmise à l'API et jettera une exception.

Les données des webservices produits et commandes disposent du même système de validation. La classe MDApiWrapperValidator ressence la liste des validateurs spécifiques.

Enfin cette documentation précise pour chaque webservice la liste des validations présentes sur chaque champs.

Exceptions

Exceptions appliquées aux webservices

Les wrappers des webservices sont les enveloppes qui permettent d'encapsuler les données à envoyées. La plupart du temps, le développeur dispose de getters et setters pour envoyer ou recevoir des données à travers l'API.

MDApiWrapperValidatorException permet de catcher les erreurs du valideur de données soumises à l'API.

L'appel d'un Wrapper n'étant pas défini par le SDK jetera une \Exception PHP.

Exceptions appliquées au Webhook

Le webhook de commande sert à recevoir les nouvelles commandes de la part de Mapadirect ainsi que la mise à joru des statuts (reception du colis par le client, validation du règlement, ...).

La réception de données non valide sur votre webhook (secret partagé - webhookHash), données non exploitable, ... jetera une exception de type WebhookErrorException.

Si le corps de l'appel au webhook de commande est un tableau vide, le SDK retournera une exception WebhookPingException ce qui permet de vérifier que l'accès à votre webhook est bien ouvert.

Logger

Le SDK dispose d'un logger qui a valeur d'interface. Il n'est pas prévu que le logger du SDK dispose de la possibilité d'écrire les logs quelques part. Pour récupérer les logs des requètes à l'API et erreurs du validateur, il est nécessaire de créer un adapter du logger MapaDirectSDK\Logger\MDApiLogger

Exemple :

use MapaDirectSDK\Logger\MDApiLogger as MDApiLoggerDefault;

class MDApiLogger extends MDApiLoggerDefault
{

    public function write($level = 'info', $message = '', $wrapper = '')
    {
        file_put_contents($level . '.file.log', '[' . $wrapper . ']' . $message);
    }
}

NB: Dans tous les exemples suivants, le logger ne sera pas instancié.

Vous pouvez instancier le client avec un logger comme suit.

$apiClient = new \MapaDirectSDK\MDApiClient();
$apiClient->setLogger(new MDApiLogger);

1. Auth

Enveloppe pour s'authentifier à l'API

Description

Le webservice d'authentification permet de retourner la clef d'API qui devra ensuite être utilisée par tous les autres webservices afin d'authentifier le marchand sur l'API MapaDirect.

L'appel à ce webservice est indispensable lors de la première utilisation de l'API MapaDirect.

Vous devez spécifier l'URL du webhook et le hash de sécurité (secret partagé avec MapaDirect). Si vous devez par la suite changer l'url ou le hash du webhook, vous devrez renouveller l'appel à l'authentification.

HTTP header:

Path: /users/authenticate
Method: GET
Authorization: Basic authentication
X-SIRET: Siret_du_marchand
X-WEBHOOKURL: https://you-shop-domain.tld/webhook-mapadirect
X-WEBHOOKHASH: a_secret_path_phrase_to_authenticate_the_webhook

L'authentification est établie à partir de l'identifiant / mot de passe du marchand sur la marketplace MapaDirect.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET Le siret est obligatoire et être un chiffre de 14 caractères
X-WEBHOOKURL L'URL du webhook doit être une URL valide au sens du filtre PHP FILTER_VALIDATE_URL
X-WEBHOOKHASH Le webhook hash est obligatoire et être une chaine de caractère de moins de 88 caractères.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK
401 Erreur

Messages d'erreur :

  • Unknown SIRET number
  • Unauthorized
  • ...

Exemple

use MapaDirectSDK\MDApiClient

$wrapper = MDApiClient::getWrapper('Auth');
$wrapper->setCredentials('you.marchand.email@domain.tld:password');
$wrapper->setSiret('20220220220220');
$wrapper->setWebHookUrl('https://you-shop-domain.tld/module/mapadirect/ordersSync');
$wrapper->setWebHookHash('488e7cafd8fc88f386ba2a88574a7f35');

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

$data = $client->getResponse()->getContent();
if ($client->getResponse()->isSuccess()) {
    $apiKey = $data['apiKey'];
    // store API_key somewhere like in a database
} else {
    // Liste des erreurs retourné par l'API MapaDirect
    $error = $data['message'];
}

2. GetTaxes

Enveloppe pour lister les taxes (TVA)

Description

Le webservice GetTaxes permet de lister toutes les taxes (TVA) disponible.

Il est nécessaire à l'initialisation de votre catalogue de récupérer les identifiants de taxes afin de compléter votre catalogue de produits avec les valeurs de taxe correspondant à la fiscalité de vos produits.

Nous recommandons très fortement de mettre en place un système permettant de mettre en cache la réponse de ce webservice.

HTTP header:

Path: /taxes
Method: GET
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET Le siret est obligatoire et être un chiffre de 14 caractères

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK

Corps de la réponse :

[
   {
      "tax_id":2,
      "tax":"TVA 2.1%"
   },
   {
      "tax_id":3,
      "tax":"TVA 5.5%"
   },
   {
      "tax_id":4,
      "tax":"TVA 10%"
   },
   {
      "tax_id":5,
      "tax":"TVA 20%"
   },
   {
      "tax_id":1,
      "tax":"TVA 0%"
   }
]

Exemple

use MapaDirectSDK\MDApiClient;

$wrapper = MDApiClient::getWrapper('GetTaxes');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
    // mise en cache de $data recommandée
} else {
    // Désolé mais l'API retour une erreur 500...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

3. GetCategories

Enveloppe pour lister l'arborescence des catégories

Description

Le webservice GetCategories permet de lister toutes les catégories disponible sur la marketplace MapaDirect.

Il est indispensable à l'initialisation de votre catalogue de récupérer la liste des categories. Vous pourrez ainsi soumettre votre catalogue de produits en les associant à l'arborescence de la marketplace MapaDirect.

Nous recommandons très fortement de mettre en place un système permettant de mettre en cache la réponse de ce webservice.

HTTP header de la requète :

Path: /catalog/categories/tree
Method: GET
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK

Corps de la réponse :

[{
    "id": 0,
    "parentId": 0,
    "name": "Couches and chairs",
    "description": "<p>List of couches and chairs for your living room.</p>",
    "slug": "couches-and-chairs",
    "image":
    {
        "id": 0
    },
    "position": 0,
    "productCount": 123,
    "seoData":
    {
        "title": "Online Shopping for Electronics, Apparel, Computers, Books, DVDs & more",
        "description": "Online shopping from the earth's biggest selection of books, magazines, music, DVDs, videos, electronics & dsl, gourmet food & just about anything else."
    },
    "categoryPath":
    [
            {
                "id": 8,
                "name": "Couches and chairs",
                "slug": "couches-and-chairs"
            }
    ]
}]

Exemple

use MapaDirectSDK\MDApiClient;

$wrapper = MDApiClient::getWrapper('GetCategories');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);

$client = new MDApiClient();
$client->call($wrapper);
$data = $client->getResponse()->getContent();
// mise en cache de $data recommandée

$data retourne un tableau php comme décrit dans le corps de la réponse.

4. AddProduct

Enveloppe pour ajouter un produit

Description

Le webservice AddProduct permet d'envoyer un produit sur la marketplace mapadirect.

HTTP header:

Path: /products
Method: POST
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Corps de la requète :

{
    "product": "Very comfortable chair.",
    "product_code": "4006381333933",
    "infinite_stock": null,
    "status": "A",
    "main_category": 456,
    "green_tax": 0.45,
    "free_shipping": "N",
    "tax_ids": [
        "0": 5
    ],
    "inventory": [
        {
            "combination": { },
            "amount": 5,
            "price": 48.4,
            "combination_code": "4006381333933"
        }
    ]
}

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères
product Le titre du produit est obligatoire.
product_code Le code produit est obligatoire et être un EAN13 valide.
infinite_stock Le stock infini est obligatoire et doit être un booléen.
status Le statut du produit est obligatoire et doit être l'une des valeurs suivantes : A (available) H (hidden) D (disabled).
inventory Le tableau d'inventory (objet php standard) est obligatoire doit être un tableau.
inventory[0].amount La quantité en stock doit être un entier naturel en positif.
inventory[0].price Le prix s'entend HT, est obligatoire et doit être un nombre décimal.
inventory[0].combination Le tableau de combinaison est obligatoire doit être un tableau ayant pour clef le champs company_id et pour valeur la main_category. Exemple : combination => [12 => 1144]
inventory[0].combination_code Le code produit n'est pas obligatoire et être un EAN13 valide.
green_tax L'éco participation devra être inclus dans le prix HT (champs price) et sera affiché sur la commande à titre indicatif. Ce champs est obligatoire et doit être un nombre décimal.
tax_ids La TVA est obligatoire et doit être indiquée sous forme de tableau ayant pour valeur l'identifiant de la Taxe. Exemple poru la TAV à 20% : tax_ids => [0 => 5]
main_category La categorie est obligatoire et doit être entier naturel positif correspondant à une categorie MapaDirect.
free_shipping La gratuité des frais de port pour un produit est obligatoire et doit être l'une des valeurs suivantes : Y (yes) ou N (No)

NB : product_code correspond à l'EAN du produit.

Corps de la réponse :

{
    "product_id": 12345
}

Il est très important de conserver une correspondance entre l'identifiant de vos produits sur votre site marchand et l'identifiant sur la marketplace mapadirect.

Exemple

use MapaDirectSDK\MDApiClient;

$inventory = new \stdClass;
$inventory->amount = (int) 123;
$inventory->price = (float) 15.0000;
$inventory->combination = [];

$product = [
    'product_code' => '1234565410333',
    'product' => 'Very comfortable chair',
    'infinite_stock' => 0,
    'status' => 'A',
    'green_tax' => 0.99,
    'free_shipping' => 'N',
    'main_category' => 1932,
    'tax_ids' => [5],
    'inventory' => [$inventory]
];

$wrapper = MDApiClient::getWrapper('AddProduct');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setInput($product);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

$data = $client->getResponse()->getContent();
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Désolé mais l'API retourne une erreur 500 en cas de soumission de données impropres...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

5. GetProduct

Enveloppe pour récupérer les informations d'un produit

Description

Le webservice GetProduct permet de récupérer les informations d'un produit que vous avez préalablement soumis.

HTTP header:

Path: /products/{productId}
Method: GET
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET Le siret est obligatoire et être un chiffre de 14 caractères

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 The product.
404 The product was not found.

Corps de la réponse :

{
   "product_id":39667,
   "product_code":"3700688558930",
   "status":"D",
   "company_id":16,
   "approved":"Y",
   "weight":0,
   "timestamp":1539278245,
   "updated_timestamp":1540290381,
   "is_edp":"N",
   "unlimited_download":"N",
   "free_shipping":"N",
   "avail_since":0,
   "tax_ids":[
      4
   ],
   "crossed_out_price":0,
   "affiliate_link":"",
   "infinite_stock":false,
   "product_template_type":"product",
   "product":"Fluocompact 55 W (Croissance) 4000 °K 840 xxx",
   "short_description":"",
   "full_description":"",
   "category_ids":[
      1147
   ],
   "main_category":1147,
   "main_pair":[

   ],
   "image_pairs":[

   ],
   "video":null,
   "attachments":[

   ],
   "inventory":[
      {
         "combination":[

         ],
         "amount":3,
         "price":3
      }
   ],
   "green_tax":1,
   "supplier_ref":"",
   "condition":"N",
   "free_features":[

   ],
   "geolocation":{
      "latitude":null,
      "longitude":null,
      "label":null,
      "zipcode":null
   }
}

NB: Certain champs ne sont pas utilisé par MapaDirect.

Exemple

use MapaDirectSDK\MDApiClient;

$productId = 123;

$wrapper = MDApiClient::getWrapper('GetProduct');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($productId);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Désolé mais l'API retour une erreur 500...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

6. UpdateProduct

Enveloppe pour mettre à jour un produit

Description

Le webservice UpdateProduct permet d'envoyer un produit sur la marketplace MapaDirect.

HTTP header:

Path: /products/{productId}
Method: PUT
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Corps de la requète :

{
    "product_id": "12345",
    "product": "Very comfortable chair.",
    "product_code": "4006381333933",
    "infinite_stock": null,
    "status": "A",
    "main_category": 456,
    "green_tax": 0.45,
    "free_shipping": "N",
    "tax_ids": [
        "0": 5
    ],
    "inventory": [
        {
            "combination": { },
            "amount": 5,
            "price": 48.4,
            "combination_code": "4006381333933"
        }
    ]
}

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères
product_id L'identifiant MapaDirect du produit est obligatoire et doit être un entier naturel en positif.
product Le titre du produit est obligatoire.
product_code Le code produit est obligatoire et être un EAN13 valide.
infinite_stock Le stock infini est obligatoire et doit être un booléen.
status Le statut du produit est obligatoire et doit être l'une des valeurs suivantes : A (available) H (hidden) D (disabled).
inventory Le tableau d'inventory (objet php standard) est obligatoire doit être un tableau.
inventory[0].amount La quantité en stock doit être un entier naturel en positif.
inventory[0].price Le prix s'entend HT, est obligatoire et doit être un nombre décimal.
inventory[0].combination Le tableau de combinaison est obligatoire doit être un tableau ayant pour clef le champs company_id et pour valeur la main_category. Exemple : combination => [12 => 1144]
inventory[0].combination_code Le code produit n'est pas obligatoire et être un EAN13 valide.
green_tax L'éco participation devra être inclus dans le prix HT (champs price) et sera affiché sur la commande à titre indicatif. Ce champs est obligatoire et doit être un nombre décimal.
tax_ids La TVA est obligatoire et doit être indiquée sous forme de tableau ayant pour valeur l'identifiant de la Taxe. Exemple poru la TAV à 20% : tax_ids => [0 => 5]
main_category La categorie est obligatoire et doit être entier naturel positif correspondant à une categorie MapaDirect.
free_shipping La gratuité des frais de port pour un produit est obligatoire et doit être l'une des valeurs suivantes : Y (yes) ou N (No)

(*) le company_id est votre identifiant retourné dans lors de l'authentification.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 The product.
404 The product was not found.

Corps de la réponse :

{
    "product_id": 12345
}

Exemple

use MapaDirectSDK\MDApiClient;

$inventory = new \stdClass;
$inventory->amount = (int) 123;
$inventory->price = (float) 15.0000;
$inventory->combination = [];

$productId = 12345;
$product = [
    'product_id' => $productId
    'product_code' => '1234565410333',
    'product' => 'Very comfortable chair',
    'infinite_stock' => 0,
    'status' => 'A',
    'green_tax' => 0.99,
    'free_shipping' => 'N',
    'main_category' => 1932,
    'tax_ids' => [5],
    'inventory' => [$inventory]
];

$wrapper = MDApiClient::getWrapper('UpdateProduct');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($productId);
$wrapper->setInput($product);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

$data = $client->getResponse()->getContent();
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Désolé mais l'API retourne une erreur 500 en cas de soumission de données impropres...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

7. DeleteProduct

Enveloppe pour supprimer un produit

Description

Le webservice AddProduct permet d'envoyer un produit sur la marketplace mapadirect.

HTTP header:

Path: /products/{productId}
Method: DELETE
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET Le siret est obligatoire et être un chiffre de 14 caractères

HTTP header de réponse :

Statut Message
200 Product removed.
400 Product not found.

Exemple

use MapaDirectSDK\MDApiClient;

$productId = 123;

$wrapper = MDApiClient::getWrapper('DeleteProduct');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($productId);

$client = new MDApiClient();
$client->call($wrapper);
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}
// product deleted
if ($client->getResponse()->isSuccess()) {
    // vous n'aurez pas de message en retour
} else {
    // Désolé mais l'API retour une erreur 500...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

8. SetShippingProduct

Enveloppe de paramètrage des frais de port par produit

Description

Le webservice SetShippingProduct permet de mettre à jour les frais de port associé à un produit. Il est nécessaire de prévoir un appel distinct de createProduct ou updateProduct.

NB : La création des transporteurs se fait directement sur la marketplace MapaDirect.

HTTP header:

Path: /products/{productId}
Method: PUT
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

L'enveloppe de la réponse est établie en json.

Corps de la requète :

{
    "status": "A",
    "rates":
    [
        {
            "amount": 0,
            "value": 3.99
        },
        {
            "amount": 1,
            "value": 1.99
        }
    ]
}

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères.
status Le statut des frais d'expédition est obligatoire et doit être l'une des valeurs suivantes : A (activé) D (désactivé).
rates.0.amount La valeur amount doit valoir 0 prix pour le premier article envoyé.
rates.0.value La valeur des frais de port pour le premier article envoyé doit être un chiffre décimal et s'entend HT.
rates.1.amount La valeur amount doit valoir 2 prix pour le premier article envoyé.
rates.1.value La valeur des frais de port à partir du deuxième article envoyé doit être un chiffre décimal et s'entend HT.

HTTP header de réponse :

Statut Message
200 OK

Corps de la réponse :

{
  "shipping_id": 0,
  "status": "A",
  "shipping": "TNT Express",
  "delivery_time": "24h",
  "rates": [
    {
      "amount": 0,
      "value": 3.99
    },
    {
      "amount": 1,
      "value": 1.99
    }
  ],
  "description": "<p>TNT shipping without tracking.</p>"
}

La première valeur de "rates" correspond au frais de port pour l'achat d'un produit. Si une deuxième valeur est saisie, les produits suivant se verront appliqué les frais avec cette deuxième valeur.

Exemple

use MapaDirectSDK\MDApiClient;

$productId = 123;
$productShipping = [
    "status": "A",
    "rates" => [
        [
            "amount": 0,
            "value": 3.99

        ],[
            "amount": 1,
            "value": 1.99
        ]
    ]
];

$wrapper = MDApiClient::getWrapper('SetShippingProduct');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($productId);
$wrapper->setInput($productShipping);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Désolé mais l'API retour une erreur 500...
    // c'est pourquoi nous avons mis en place un validateur très strict dans ce SDK avec tous les cas d'erreur connu.
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

1. Ping

Enveloppe pour tester l'appel de votre webhook order

Description

Le webservice Ping permet de demander à l'API mapadirect d'appeler votre webhook order afin de vérifier qu'il est bien accessible.

HTTP header:

Path: /ping
Method: GET
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET Le siret est obligatoire et être un chiffre de 14 caractères

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK
400 Webhook indisponible

Rappel : En cas d'erreur sur la définition de l'URL du webhook, pour indiquer à MapaDirect d'envoyer vos commandes sur à une autre adresse, veuillez relancer la procédure d'authentification.

Corps de la réponse en cas de succès :

{
   "statusCode":201,
   "body":{
      "success":true,
      "message":"Ping OK"
   },
   "headers":{
      "server":"nginx/1.6.2",
      "date":"Mon, 22 Oct 2018 12:57:26 GMT",
      "content-type":"application/json",
      "content-length":"36",
      "connection":"close"
   },
   "request":{
      "uri":{
         "protocol":"http:",
         "slashes":true,
         "auth":null,
         "host":"your.domain.tld",
         "port":80,
         "hostname":"your.domain.tld",
         "pathname":"/module/mapadirect/ordersSync",
         "path":"/module/mapadirect/ordersSync",
         "href":"http://your.domain.tld/module/mapadirect/ordersSync"
      },
      "method":"PUT",
      "headers":{
         "Content-Type":"application/json",
         "Accept":"*/*",
         "X-WEBHOOKHASH":"xxxxxxxxxxxxxxxxxx",
         "content-length":2
      }
   }
}

Corps de la réponse en cas d'erreur (ici, on a une redirection 302 sur l'URL du webhook) :

{
   "object":"302 - undefined",
   "invalidities":{
      "errors":[
         {
            "name":"StatusCodeError",
            "statusCode":302,
            "message":"302 - undefined",
            "options":{
               "headers":{
                  "Content-Type":"application/json",
                  "Accept":"*/*",
                  "X-WEBHOOKHASH":"xxxxxxxxxxxxxxxxxx"
               },
               "method":"PUT",
               "json":true,
               "resolveWithFullResponse":true,
               "uri":"http://your.domain.tld/module/mapadirect/ordersSync",
               "body":{

               },
               "simple":true,
               "transform2xxOnly":false
            },
            "response":{
               "statusCode":302,
               "headers":{
                  "server":"nginx/1.6.2",
                  "date":"Thu, 25 Oct 2018 16:23:51 GMT",
                  "content-type":"text/html; charset=UTF-8",
                  "content-length":"0",
                  "connection":"close",
                  "expires":"Mon, 26 Jul 1997 05:00:00 GMT",
                  "last-modified":"Thu, 25 Oct 2018 16:23:51 GMT",
                  "cache-control":"no-store, no-cache, must-revalidate, post-check=0, pre-check=0",
                  "pragma":"no-cache",
                  "location":"../"
               },
               "request":{
                  "uri":{
                     "protocol":"http:",
                     "slashes":true,
                     "auth":null,
                     "host":"your.domain.tld",
                     "port":80,
                     "hostname":"your.domain.tld",
                     "hash":null,
                     "search":null,
                     "query":null,
                     "pathname":"/module/mapadirect/ordersSync",
                     "path":"/module/mapadirect/ordersSync",
                     "href":"http://your.domain.tld/module/mapadirect/ordersSync"
                  },
                  "method":"PUT",
                  "headers":{
                     "Content-Type":"application/json",
                     "Accept":"*/*",
                     "X-WEBHOOKHASH":"xxxxxxxxxxxxxxxxxx",
                     "content-length":2
                  }
               }
            }
         }
      ]
   }
}

Exemple

use MapaDirectSDK\MDApiClient;

$wrapper = MDApiClient::getWrapper('Ping');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
}


$client = new MDApiClient();
$client->call($wrapper);
$success = $client->getResponse()->isSuccess();

$data retourne un tableau php comme décrit dans le corps de la réponse.

Pour connaître les spécifications techniques du webhook ping, veuillez lire la rubrique Webhooks > Ping.

2. ApproveOrder

Enveloppe pour approver une commande suite au dépôts d'une commande

Description

Le webservice ApproveOrder permet de confirmer la prise en charge de la commande. Cet état correspond à "Commande enregistrée" et/ou "En cours de préparation" chez le marchand.

HTTP header:

Path: /orders/{orderId}
Method: PUT
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Corps de la requète automatiquement générée par le SDK :

{
   "approved" : true,
   "do_not_create_invoice" : true
}

NB : Il est inutile de préparer le corps de la requète. Les valeurs par défaut ci-dessus sont imposées par MapaDirect.

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères.
approved Doit valoir vrai.
do_not_create_invoice Le processus d'achat en marché public impose une création de facture après réception de la marchandise. Doit valoir vrai.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK
404 La commande n'existe pas.

Exemple

use MapaDirectSDK\MDApiClient;

$orderId = 123;

$wrapper = MDApiClient::getWrapper('ApproveOrder');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($orderId);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // Liste des erreurs retournées par l'API
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

3. SetTracking

Enveloppe d'envoi des numéros de tracking des colis expédiés

Description

Le webservice SetTracking permet d'envoyer un numéro de tracking d'une commande.

HTTP header:

Path: /shipments
Method: POST
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Corps de la requète :

{
   "order_id" : "123",
   "comments" : "Colissimo https://sample.com/FDSXXX",
   "trackign_number": "FDSXXX",
   "products": {
        "123456": 3
   }
}

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères.
order_id Le numéro de commande est obligatoire et doit être un entier naturel.
comments Texte contenant l'URL de tracking si possible.
trackign_number Numéro de tracking. Par défaut vauqt "colis_non_suivi" si non défini.
products Tableau des produits expédiés contenant [id_produit => quantité]

NB : Si plusieurs colis sont nécessaire, il est possible d'appeler plusieurs fois le webservice avec la liste des produit contenu dans chaque colis.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK
400 Un des attributs de la requête est erroné.

Corps de la réponse :

{
    "shipment_id":122
}

A priori, cette donnée n'a pas nécessite d'être conservée hormis à usage de log.

Exemple

use MapaDirectSDK\MDApiClient;

$orderId = 123;
$tracking = [
   "comments" => "Colissimo https://tracking.colissimo.com/FDSXXX",
   "trackign_number" => "FDSXXX",
   "products" => [
        "123456" => 3
   ]
];

$wrapper = MDApiClient::getWrapper('SetTracking');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($orderId);
$wrapper->setInput($tracking);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // Liste des erreurs retournées par l'API
}

NB : Pour respecter la nomenclature d'appel des webservices de MapaDirect, le SDK permet de saisir l'id de commande order_id en le définissant par setId ce qui completera le corps de la requète.

$data retourne un tableau php comme décrit dans le corps de la réponse.

4. SetInvoiceData

Enveloppe pour envoyer les numéro et date de facture

Description

Le webservice SetInvoiceData permet d'envoyer les informations de facturation du marchand à MapaDirect.

HTTP header:

Path: /orders/{orderId}/setinvoicedata
Method: PUT
Authorization: token your_api_key
X-SIRET: Siret_du_marchand

L'authentification est établie à partir du token Api Key du marchand sur la marketplace MapaDirect retourné par l'authentification.

Corps de la requète :

{
   "invoiceNumber" : "F132465",
   "invoiceDate" : "2018-06-07T17:56:00.000Z"
}

Liste des validateurs inclus dans le SDK

Champs Message
X-SIRET (envoyé en header) Le siret est obligatoire et être un chiffre de 14 caractères.
invoiceNumber Le numéro de facture est obligatoire et disposer d'au moins un chiffre.
invoiceDate Le date de la facture est obligatoire être au format ISO 8601.

L'enveloppe de la réponse est établie en json.

HTTP header de réponse :

Statut Message
200 OK
400 Un des attributs de la requête est manquant ou invoiceDate n'est pas au format JSON.
403 Cas où l'utilisateur appelant n'est pas le marchand déclaré sur la commande.
404 La commande n'existe pas.

Corps de la réponse :

{
    "securitizationUrl": "test"
}

SecuritizationUrl n'est présent que si le marchand a choisi de se faire payer par URICA. securitizationUrl est l'URL permettant au marchand de valider le rachat de facture par URICA.

Note : l'interfaçage avec URICA est en développement.

L'attribut securitizationUrl sera donc valorisé avec « test » jusqu'à ce que nos travaux aboutissent.

Exemple

use MapaDirectSDK\MDApiClient;

$orderId = 123;
$invoice = [
   invoiceNumber : "F132465",
   invoiceDate : "2018-06-07T17:56:00.000Z"
];

$wrapper = MDApiClient::getWrapper('SetInvoiceData');
$wrapper->setToken($apiKey);
$wrapper->setSiret($siret);
$wrapper->setId($orderId);
$wrapper->setInput($invoice);

$client = new MDApiClient();
try {
    $client->call($wrapper);
} catch (MDApiWrapperValidatorException $e) {
    // Liste des erreurs retournées par le SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // Liste des erreurs retournées par l'API
}

$data retourne un tableau php comme décrit dans le corps de la réponse.

1. Order

Order Webhook

Description

Votre application doit disposer d'un controller exposé publiquement permettant à Mapadirect de vous envoyer les nouvelles commandes et les mises à jour des statuts des commandes.

NB : L'url du webhook est définie lors de l'authentification voir Auth Wrapper.

Le webservice d'authentification permet de configurer l'URL du webhook order ainsi que le jeton (secret partagé) permettant de vérifier que la requète provient de mapadirect.

HTTP header de la requète (que vous receverez) :

Path: /webhook-mapadirect
Method: POST
Authorization: token a_secret_path_phrase_to_authenticate_the_webhook

Corps de la requète (exemple) :

{
    "id": 123456,
    "taxExclusiveAmount": 121.76,
    "taxInclusiveAmount": 146.11,
    "legalMonetaryTotal": {
        "taxExclusiveAmount": 121.76,
        "taxInclusiveAmount": 146.11,
        "totalTaxAmount": 24.352
    },
    "shippingCostLine": {
        "taxExclusiveAmount": 12.5,
        "taxInclusiveAmount": 15,
        "totalTaxAmount": 2.5,
        "VATRate": 20
    },
    "timestamp": 1532092031,
    "status": "EMITTED",
    "siretNumber": "19781123300010",
    "paymentMethod": "",
    "shippingAddress": {
        "company": "LYCEE DE VILLAROY",
        "contactFullName": "Patricia Jeannot",
        "contactPhone": "0123456789",
        "address": "2 RUE EUGENE RAFFIN",
        "address2": "",
        "city": "GUYANCOURT",
        "zipcode": "78280",
        "country": "FR"
    },
    "billingAddress": {
        "company": "LYCEE DE VILLAROY",
        "contactFullName": "Patricia Jeannot",
        "contactPhone": "0123456789",
        "address": "2 RUE EUGENE RAFFIN",
        "address2": "",
        "city": "GUYANCOURT",
        "zipcode": "78280",
        "country": "FR"
    },
    "items": [
        {
          "name": "Cordon RJ45 catégorie 5e F/UTP jaune - 3 m",
          "quantity": 1,
          "referenceCode": "854106",
          "taxExclusiveAmount": 3.49,
          "taxExclusiveUnitPrice": 3.49,
          "taxInclusiveAmount": 4.19,
          "totalTaxAmount": 0.698,
          "VATRate": 20
        },{
          "name": "Cordon RJ45 catégorie 5e F/UTP vert - 3 m",
          "quantity": 1,
          "referenceCode": "854107",
          "taxExclusiveAmount": 3.49,
          "taxExclusiveUnitPrice": 3.49,
          "taxInclusiveAmount": 4.19,
          "totalTaxAmount": 0.698,
          "VATRate": 20
        }
    ]
}

L'enveloppe de la réponse doit être établie en json.

HTTP header de réponse (que vous devez retourner) :

Statut Message
200 Order valid
400 The order format is invalid
409 The order has already been processed
50x Internal Server

Attention : les redirections 301 ou 302 ne sont pas suivies !

Liste des status de commande :

Statut Commentaire
SENT La commande est soumise par le client et "envoyée" au marchand sur son webhook de réception de commande.
VALIDATED La commande est valide sur MapaDirect et cours de traitement par le marchand.
SHIPPED La commande est expédié. (à venir)
RECEIVED Le client a reçu la commande.
EMITTED La facture a été générée et dématérialisée.
TOTALLYPAID La facture a été payée (entièrement).
ERROR Commande rejetée, a priori non envoyé car non géré pour l'instant

Exemple

Le SDK mapadirect dispose d'une classe permettant de vérifier le jeton.

use MapaDirectSDK\Webhooks\WebhookOrder;
use MapaDirectSDK\Webhooks\WebhookPingException;
use MapaDirectSDK\Webhooks\WebhookErrorException;
use MapaDirectSDK\Webhooks\WebhookRequest;

$webhook = new WebhookOrder();
$webhook->setWebHookHash('a_secret_path_phrase_to_authenticate_the_webhook');
$webhook->setRequest(new WebhookRequest);
try {
    $webhook->process();
    $data = $webhook->getData();

    // create or update the order
} catch (\Exception $e) {
    if ($e instanceof WebhookPingException || $e instanceof WebhookErrorException) {
        echo $e->sendResponse();
        exit;
    }
}

2. Ping

Webhook de test d'accessibilité

Description

Pour tester la disponibilité de votre webhook order, vous pouvez appeller le webservice ping qui exécutera une requète sur votre webhook afin de vérifier que la clef est correctement configuré et qu'il est bien accessible.

Pour tester au plus proche des conditions d'envoi du webhook order, l'enveloppe d'appel reste la même que order, mais le corps de la requète sera vide.

Path: /webhook-mapadirect
Method: POST
Authorization: token a_secret_path_phrase_to_authenticate_the_webhook

Le corps de la requète sera envoyé vide {}.

L'enveloppe de la réponse doit être établie en json.

HTTP header de réponse (que vous devez retourner) :

Statut Message
200 Ping valid
400 Token not valid
50x Internal Server

Corps de la réponse :

{
    "message": "Ping valid"
}

Le message retourné par votre webhook de ping sera transféré et retrouné par le webservice de Ping.

Exemple

use MapaDirectSDK\Webhooks\WebhookOrder;
use MapaDirectSDK\Webhooks\WebhookPingException;
use MapaDirectSDK\Webhooks\WebhookErrorException;
use MapaDirectSDK\Webhooks\WebhookRequest;

$wrapper = new WebhookOrder();
$wrapper->setWebHookHash('a_secret_path_phrase_to_authenticate_the_webhook');
$wrapper->setRequest(new WebhookRequest);
try {
    $webhook->process();
} catch (WebhookPingException | WebhookErrorException $e) {
    echo $e->sendResponse();
    exit;
}

MapaDirect SDK

No matches.