Installation

MapadirectSDK, client PHP for the MAPAdirect marketplace API

Latest Version Total Downloads Requirements

MapaDirectSDK is a PHP library for connecting your online store to MapaDirect marketplace.

The library allows you to synchronize your product catalog and receive orders from the marketplace.

Documentation

You will find here the documentation of the MapaDirectSDK library. (Version FR)

Install mapadirectsdk

We advise you to install MapaDirectSDK via compose Composer.

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

Then, run the command Composer to install the latest version of the MapaDirectSDK library:

php composer.phar require mapadirectsdk/mapadirectsdk

After installation you have to call'Composer autoload:

require 'vendor/autoload.php';

You can then update the MapaDirectSDK library using 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

Validator, Exceptions & Logger

Validators of data subject to the'API through the webservices

The SDK has data validation before submission to MapaDirect. If the data to be sent are not 100% consistent, the request will not be transmitted to the 'API and will throw an exception.

The data from the products and orders webservices have the same validation system. The classMDApiWrapperValidator identify the list of specific validators.

Finally this documentation gives for each webservice a list of validations present on each field.

Exceptions

Exceptions applied to the webservices

The webservices' wrappers are the envelopes that'encapsulate the data to be sent. Most of the time, the developer has getters and setters to send or receive data through the'API.

MDApiWrapperValidatorException allows to catch the errors of the data validator subject to the API.

The call of a Wrapper which is not defined by the SDK will throw a\Exception PHP.

Exceptions applied to the Webhook

The order webhook allows to receive new orders from Mapadirect as well as the status update (receipt of the package by the customer, validation of the payment,...).

The reception of invalid data on your webhook (shared secret - webhookHash),non exploitable data, ... will throw an exception of the form WebhookErrorException.

If the body of the call to the order webhook is an empty array, the SDK will return an exception WebhookPingException which allows to check that the access to your webhook is open.

Logger

The SDK has a logger which has value of 'interface. It 'is not planned that the SDK has the ability to'write logs somewhere. To recover the request logs to the'API and validator errors, it is necassary to create a logger's adaptationMapaDirectSDK\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: In all the following examples, the logger will not be instantiated.

You can instantiate the customer with a logger as follows.

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

1. Auth

Envelope to'authenticate to the'API

Description

The authentication webservice 'authentication allows to return the API key'API which will then have to be used by all the others webservices to authenticate the seller on 'MapaDirect API.

A call to this webservice is essential for the first utilisation of the MapaDirect API.

You should specify the webhook URL and the security hash (shared secret with MapaDirect). If you later need to change the url or the webhook hash, vous will need to renew the call to authentication.

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

The authentication is established from the seller ID / password on MapaDirect marketplace.

List of validators included in the SDK

Field Message
X-SIRET The siret is mandatory and is a sequence of 14 digits
X-WEBHOOKURL The webhook URL must be valid in the sense of the filter PHP FILTER_VALIDATE_URL
X-WEBHOOKHASH The webhook hash is mandatory and must be a string of length 88.

The envelope of the answer is established in json.

Answer's HTTP header :

Status Message
200 OK
401 Erreur

Error messages :

  • 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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}

$data = $client->getResponse()->getContent();
if ($client->getResponse()->isSuccess()) {
    $apiKey = $data['apiKey'];
    // store API_key somewhere like in a database
} else {
    // List of errors returned by the MAPAdirect marketplace API
    $error = $data['message'];
}

2. GetTaxes

Envelope to list the taxes (TVA)

Description

The webservice GetTaxes allows to list all the available taxes (TVA).

It is necessary during the initialization of your catalog to get the taxes ID to complete your product catalog with the tax value corresponding to the taxation of your products.

We strongly recommend to set up a system to cache to reply of this webservice.

HTTP header:

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

Theauthentication is established from the token Api Key of the seller on the MapaDirect returned by the authentication.

List of the validators included in the SDK

Field Message
X-SIRET The siret is mandatory and should by be a sequence of 14 digits.

Lenvelope of the answer is established in json.

Answer's HTTP header:

Status Message
200 OK

Answer's body :

[
   {
      "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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
    // recommended caching of $data 
} else {
   // Sorry but the API returns an error 500...
   // That's why we have set up a very strict validator in this SDK with all the known error cases.
}

$data return a php array as described in the answer body.

3. GetCategories

Envelope to list the'category tree

Description

The webservice GetCategories lists all the categories available on the MapaDirect marketplace.

It is essential during the initialization of your catalog to get the category list. You will then be able to submit your product catalog by associating them to the MapaDirect marketplace tree.

We strongly recommend you to set up a system to cache your reply to this webservice.

Request HTTP header:

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

The authentication is established from the token Api Key of the seller on MapaDirect marketplace returned by the authentication.

The answer envelope is established in json.

Answer's HTTP header:

Status Message
200 OK

Answer's body:

[{
    "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();
// recommended caching of $data 

$data return a php array as described in the answer body.

4. AddProduct

Envelope to add a product

Description

The webservice AddProduct allows to send a product to MAPAdirect marketplace.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MapaDirect returned by the authentication.

Request's body :

{
    "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"
        }
    ]
}

List of validators included in the SDK

Field Message
X-SIRET (sent in header) the siret is mandatory and must be a sequence of 14 digits
product The product title is mandatory.
product_code The product code is mandatory and must be a valid EAN13.
infinite_stock The infinite stock is mandatory and must be boolean.
status The product status is mandatory and must be one of the following value: A (available) H (hidden) D (disabled).
inventory The array inventory (standard php object) is mandatory and must be an array.
inventory[0].amount The stock quantity must be a natural number.
inventory[0].price The price is written as tax-free, is mandatory and must be a decimal number.
inventory[0].combination The combination table is mandatory and must be an array with the company_id field and the main_category value. Example : combination => [12 => 1144]
inventory[0].combination_code The product code is not mandatory and is a valid EAN13.
green_tax The eco participation must be included in the HT price (price field) and will be displayed on the order as an indication. This field is mandatory and must be a decimal number.
tax_ids The TVA is mandatory and must be indicated as a table having for value the tax ID. Example for TVA 20% : tax_ids => [0 => 5]
main_category The category is mandatory and must be a natural number corresponding to a MapaDirect category.
free_shipping Indicating free shipping for a product is mandatory and must be one of the following values: Y (yes) ou N (No)

NB : product_code corresponds to the product EAN.

Answer's body:

{
    "product_id": 12345
}

It is very important to keep the matching between your product ID on your website and the ID on mapadirect marketplace.

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 {
    // Sorry but the API returns an error 500 in case of submission of incorrect data...
    // That's why we have set up a very strict validator in the SDK with all the known error cases.
}

$data returns a ohp array as described in the answer body.

5. GetProduct

Envelope to recover product's information

Description

The webservice GetProduct allows to recover product's information that you have submitted beforehand.

HTTP header:

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

The authentication is established from a token Api Key of the seller on the MapaDirect marketplacereturned by the authetication.

List of validators included in the SDK

Field Message
X-SIRET The siret is mandatory and must be a sequence of 14 digits.

The envelope of the answer is established in json.

Answer's HTTP header:

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

Answer's body:

{
   "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: Some fields are not used by 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) {
    // List of errors returned by SDK.
    $client->getErrors();
    exit;
}
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
   // Sorry but the API returns an error 500.
   // That is why we have put into place a very strict validator in this SDK with every case of known error.
}

$data return a php table as described in the answer's body .

6. UpdateProduct

Envelope to update a product

Description

The webservice UpdateProduct allows to send a product on the MAPAdirect marketplace API.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MapaDirect marketplace return by the authentification.

Request's body::

{
    "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"
        }
    ]
}

List of included validators by the SDK

Fields Message
X-SIRET (envoyé en header) The siret is mandatory and is a sequence of 14 digits.
product_id The MapaDirect identifier of the product is mandatory and must be a natural number.
product The product title is mandatory.
product_code The product code is mandatory and must be a valid EAN13.
infinite_stock The infinite stock is mandatory and must be a boolean.
status The product status is mandatory and must be one of the following values: A (available) H (hidden) D (disabled).
inventory The inventory table (standard php object) is mandatory and must a table.
inventory[0].amount The quantity in stock must be natural number.
inventory[0].price The price is written as tax-free, is mandatory and must be a decimal number.
inventory[0].combination The combination table is mandatory and must be an array with the company_id field and the main_category value. Example : combination => [12 => 1144]
inventory[0].combination_code The product code is not mandatory and is a valid EAN13
green_tax The eco participation must be included in the HT price (price field) and will be displayed on the order as an indication. This field is mandatory and must be a decimal number
tax_ids The TVA is mandatory and must be indicated as a table having for value the tax ID. Example for TVA 20% : tax_ids => [0 => 5]
main_category The category is mandatory and must be a natural number corresponding to a MapaDirect category.
free_shipping Indicating free shipping for a product is mandatory and must be one of the following values: Y (yes) ou N (No)

(*) The company_id is the ID returned during the authentication.

The answer's envelope is established in json.

Answer's HTTP header:

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

Answer's body:

{
    "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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}

$data = $client->getResponse()->getContent();
if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Sorry but the API returns an error 500 in case of submission of incorrect data...
    // That's why we have set up a very strict validator in this SDK with every case of known error.
}

$data returns a php table as described in the answer's body.

7. DeleteProduct

Envelope to delete a product

Description

The DeleteProduct webservice deletes the product from the mapadirect marketplace.

HTTP header:

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

The authentication is established from the token Api Key of the seller onthe MAPAdirect marketplace returned by the authentication.

List of valued included in the SDK

Field Message
X-SIRET The siret is mandatory and must be a sequence of 14 digits

Answer's HTTP header:

Status 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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}
// product deleted
if ($client->getResponse()->isSuccess()) {
    // You will not have messages in return
} else {
   // Sorry but the API returns an error 500...
   // That'why we have set up a very strict validator in this SDK with every case of known error.
}

$data return a php table as described in the answer's body

8. SetShippingProduct

Envelope to parameterize the shipping fees per product

Description

The webservice SetShippingProduct allows to update the shipping fees associated to a product. It is necessary to plan a distinct call ofcreateProduct or updateProduct.

NB : The creation of shippers is directly done on the MAPAdirect marketplace.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MAPAdirect marketplace returned by the authentication.

The answer's envelope is established in json.

Request's body:

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

List of validators included in the SDK

Field Message
X-SIRET (envoyé en header) The siret is mandatory and a sequence of 14 digits.
status The shipping fees' status is mandatory and must be one of the following values: A (active) D (inactive).
rates.0.amount The value amount must be 0 pirce for the first sent article.
rates.0.value The value of the shipping fees for the first article sent must be a decimal number (given in tax free)
rates.1.amount The value amount must cost twice the price of the first sent article.
rates.1.value The value shipping fees from the second sent article must be a decimal number (given in tax free)

Answer's HTTP header:

Status Message
200 OK

Answer's body:

{
  "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>"
}

The first value of "rates" corresponds to the shipping fees for the purchase of a product. If a second value is given, the following products will have shipping fees corresponding to this second value.

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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    // Sorry but the API returns an error 500...
    // That's why we have set up a very strict validator in this SDK with every case of known error.
}

$data returns a php table as described in the answer's body.

1. Ping

Envelope to test the call to your webhook order

Description

The webservice Ping allows to ask the API mapadirect to call your webhook order to check that we can access it.

HTTP header:

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

The authentication is established from the tokenApi Key of the seller on the MAPAdirect marketplace returned by the authentication.

List of validators included in the SDK

Field Message
X-SIRET The siret is mandatory and must be a sequence of 14 digits

The answer's envelope is established in json.

Answer's HTTP :

Status Message
200 OK
400 Webhook indisponible

Recall: in case of error on the definition of the webhook URL, to indicate to MAPAdirect to send your orders on another address, please redo the authentication process.

Answer's body in case of success :

{
   "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
      }
   }
}

ANswer's body in case of error (here is a redirection 302 on the webhook URL) :

{
   "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) {
    // List of errors returned by the 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 returns a php table as described in the answer's body.

To know the technical specifications of the webhook ping, please read the Webhooks rubric > Ping.

2. ApproveOrder

Envelope to approve an order after an order deposit

Description

The webservice ApproveOrder allows to confirm the take over of the order. This state corresponds to "Commande enregistrée" and/or "En cours de préparation" for the seller.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MAPAdirect marketplace returned by the authentication.

Request's body automaticly generated by the SDK :

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

NB : It is unuseful to prepare the request's body. The default values below are imposed by MapaDirect.

List of validators included in the SDK

Field Message
X-SIRET (sent in header) The siret is mandatory and is a sequence of 14 digits.
approved Must value true.
do_not_create_invoice The purchase process in public market imose the creation of an invoice after the receipt of the product. Must value true.

The answer's envelope is established in json.

Answer's HTTP header :

Status Message
200 OK
404 The order doesn't exist

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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // List of errors returned by the API 
}

$data returns a php table as described in the answer's body.

3. SetTracking

Envelope to send the tracking numbers of the shipped packages

Description

The webservice SetTracking allows to send the tracking number of a command.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MAPAdirect marketplace returned for the authentication.

Request's body :

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

List of validators included in the SDK

Field Message
X-SIRET (envoyé en header) The siret is mandatory and msut be a sequence of 14 digits.
order_id The order number is mandatory and must be a natural number.
comments Text containing the tracking URL if available.
trackign_number Tracking number. By default, "colis_non_suivi" if non defined.
products Table of shipped products containing [id_produit => quantity]

NB : If several packages are necessary, it is possible to call several times the webservice with a list of products containing in each package.

The answer's envelope is established in json.

Answer's HTTP header :

Status Message
200 OK
400 One of the request's attributes is wrong.

Answer's body :

{
    "shipment_id":122
}

A priori, this data can be not kept except as log usage.

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) {
    // List of errors returned by the SDK 
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // List of errors returned by the API 
}

NB : To respect the nomenclature of the call of the MAPAdirect webservices, the SDK allows to enter the order id order_id by defining it by setId which will complete the request'

$data returns a php table as described in the answer's body.

4. SetInvoiceData

Envelope to send invoice number and date

Description

The webservice SetInvoiceData allows to send the invoice information of the seller to MAPAdirect.

HTTP header:

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

The authentication is established from the token Api Key of the seller on the MapaDirect marketplace returned by the authentication.

Request's body:

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

List of validators included in the SDK

Champs Message
X-SIRET (envoyé en header) The siret is mandatory and must be a sequence of 14 digits.
invoiceNumber The invoice number is mandatory and must be composed of at least one digit.
invoiceDate The invoice date is mandatory and must be under ISO 8601 format.

The answer's envelope is established in json.

Answer's HTTP header :

Status Message
200 OK
400 One of the request's attributes is missing or the invoiceDate is not fitting the JSON format
403 Case where the user calling is not the seller declared on the order.
404 The order doesn't exist.

Answer's body :

{
    "securitizationUrl": "test"
}

SecuritizationUrl is not present if the seller has chosen to be paid by URICA. securitizationUrl is the URL allowing the seller to validate the repurchase of its invoice by URICA.

Note : the interfacing with URICA is under development.

The attribute securitizationUrl will not valorized with « test » until our work terminates.

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) {
    // List of errors returned by the SDK
    $client->getErrors();
    exit;
}

if ($client->getResponse()->isSuccess()) {
    $data = $client->getResponse()->getContent();
} else {
    $data = $client->getResponse()->getContent();
    // List of errors returned by the API 
}

$data returns a php table as described in the answer's body.

1. Order

Order Webhook

Description

Your application must have a controller publicly exposed allowing MAPAdirect to send new orders and order status' updates.

NB : The webhook url is defined during the authentication see Auth Wrapper.

The authetication webservice allows to configure the webhook order URL as well as the token (shared secret) allowing to check that the request comes mapadirect.

Request's HTTP header (that you will receive) :

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

Request's body (example) :

{
    "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",
    "serviceCode": "",
    "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
        }
    ]
}

The answer's envelope must be established in json.

Answer's HTTP header (that you must return) :

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

Warning : the redirections 301 or 302 are not followed !

List of command status :

Status Comment
SENT The order submitted by the client and "sent" to the seller on its command's reception webhook .
VALIDATED The order is valid on MapaDirect and in treatment by the seller.
SHIPPED The order has been shipped. (to come)
RECEIVED The client has received the order.
EMITTED The invoice has been generated and La facture a été générée et dematerialiazed
TOTALLYPAID The invoice has been paid (totally).
ERROR Order rejected, a priori not sent since not handled for the moment

Exemple

The SDK mapadirect has a class allowing to check the token.

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 to test accessibility

Description

To test the availability of your webhook order, you can call the ping webservice that will execute a request on your webhook to check that the key has been well configured and that it is available.

To test as close as possible to the conditions of sending of the webhook order , the call envelope remains the same as order, but the request's body will be empty.

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

The request's boy will remain empty {}.

The answer's envelope must be established in json.

Answer's HTTP header (that you should return) :

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

Answer's body :

{
    "message": "Ping valid"
}

The message returned by your ping webhook will be transfered and returned by the Ping webservice.

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;
}

Contact-us

For every technical problems, please create a new "issue" on the project MAPAdirect SDK on github https://github.com/202-ecommerce/mapadirectSDK.

You can also directly contact us by email : : mapadirect-support@202-ecommerce.com

MapaDirect SDK

No matches.