API pour la gestion des paniers
===============================

Il existe 3 opérations pour la gestion des paniers, ``get``, ``add`` et ``modify``. Le déroulement le plus fréquent d'une commande via l'api est le suivant :

1. Ajout d'un ou plusieurs articles via ``add``.
2. Redirection du client vers le tunnel de création de commande sur le site de la Librairie Dialogues.

Bases communes à toutes les opérations
--------------------------------------

L'API est disponible via des requêtes HTTP POST et GET. Chaque opération retourne un object JSON comportant un attribut ``cart`` si possible et un attribut ``error_list`` dans le cas ou la requête serait malformée. Le code de réponse HTTP (200 ou 400) permet aussi de tester si une requête a été correctement traitée.

Les paramètres sont a envoyer comme formulaire pour les requêtes POST et variables encodées pour les requêtes GET.

L'opération ``add``
-------------------

C'est l'opération permettant d'ajouter un ou plusieurs articles (``items``) au panier. C'est aussi la méthode à utiliser pour créer un panier. Il faut alors omettre le paramètre ``cart_id``.

**adresse**
    http://demo.librairiedialogues.fr/ws/cart/add/
**méthode http**
    POST seulement
**paramètre optionnel**
    * ``cart_id``, s'il est absent, on crée un nouveau panier
**paramètres obligatoires**
    * ``affiliate_id``
    * un ou plusieurs ``items``, sous la forme ``item.x.y`` où ``y`` est un attribut de la ligne à ajouter (comme ``ean13`` et ``quantity``) et ``x`` un entier permettant de regrouper les attributs d'une même ligne.

Voici les paramètres permettant à l'affilié *lemagasinducoin* de créer un nouveau panier avec un exemplaire de *La peine du menuisier* et deux exemplaire des *Déferlantes*::

    affiliate_id=lemagasinducoin
    item.1.ean13=9782752904133
    item.1.quantity=1
    item.2.ean13=9782841569342 
    item.2.quantity=2

La réponse du serveur est la suivante::

    {"cart": {"items": [{"ean13": "9782752904133",
                         "name": "La peine du menuisier - Marie Le Gall - Phébus",
                         "unit_price_inc_tax": "20.00",
                         "discount_rate": "5.00",
                         "line_total_inc_tax": "19.00",
                         "quantity": 1},
                        {"ean13": "9782841569342",
                         "name": "Les déferlantes - Claudie Gallay - Éd. du Rouergue",
                         "unit_price_inc_tax": "21.50",
                         "discount_rate": "5.00",
                         "line_total_inc_tax": "40.85",
                         "quantity": 2}],
              "total_inc_tax_ex_shipping": "59.85",
              "items_number": 3,
              "checkout_url": "http://demo.librairiedialogues.fr/ws/cart/merge/8d026e395aead442b10a3627efd8ae2186f42c7b/",
              "affiliate_id": "lemagasinducoin",
              "cart_id": "8d026e395aead442b10a3627efd8ae2186f42c7b"}}

L'opération ``modify``
----------------------

C'est l'opération permettant de modifier le contenu d'un panier. On peut ainsi supprimer des articles, modifier des quantités. Le paramètre ``cart_id`` est donc obligatoire pour identifier le panier à modifier.

**adresse**
    http://demo.librairiedialogues.fr/ws/cart/modify/
**méthode http**
    POST seulement
**paramètres obligatoires**
    * ``affiliate_id``
    * ``cart_id``
    * un ou plusieurs ``items``, sous la forme ``item.x.y`` où ``y`` est un attribut de la ligne à ajouter (comme ``ean13`` et ``quantity``) et ``x`` un entier permettant de regrouper les attributs d'une même ligne.

Voici les paramètres permettant à l'affilié *lemagasinducoin* de modifier le panier précédent::

    affiliate_id=lemagasinducoin
    cart_id=8d026e395aead442b10a3627efd8ae2186f42c7b
    item.43.ean13=9782752904133
    item.43.quantity=0
    item.42.ean13=9782841569342
    item.42.quantity=1

La réponse du serveur est la suivante::

    {"cart": {"items": [{"ean13": "9782841569342",
                         "name": "Les déferlantes - Claudie Gallay - Éd. du Rouergue",
                         "unit_price_inc_tax": "21.50",
                         "discount_rate": "5.00",
                         "line_total_inc_tax": "20.43",
                         "quantity": 1}],
              "total_inc_tax_ex_shipping": "20.43",
              "items_number": 1,
              "checkout_url": "http://demo.librairiedialogues.fr/ws/cart/merge/8d026e395aead442b10a3627efd8ae2186f42c7b/",
              "affiliate_id": "lemagasinducoin",
              "cart_id": "8d026e395aead442b10a3627efd8ae2186f42c7b"}}

L'opération ``get``
-------------------

C'est l'opération la plus simple, permettant de récupérer le contenu d'un panier.

**adresse**
    http://demo.librairiedialogues.fr/ws/cart/get/
**méthode http**
    GET ou POST
**paramètres obligatoires**
    * ``affiliate_id``
    * ``cart_id``

Voici les paramètre permettant à l'affilié *lemagasinducoin* de récupérer le panier précédent::

    affiliate_id=lemagasinducoin
    cart_id=8d026e395aead442b10a3627efd8ae2186f42c7b

La réponse du serveur est la suivante::

    {"cart": {"items": [{"ean13": "9782841569342",
                         "name": "Les déferlantes - Claudie Gallay - Éd. du Rouergue",
                         "unit_price_inc_tax": "21.50",
                         "discount_rate": "5.00",
                         "line_total_inc_tax": "20.43",
                         "quantity": 1}],
              "total_inc_tax_ex_shipping": "20.43",
              "items_number": 1,
              "checkout_url": "http://demo.librairiedialogues.fr/ws/cart/merge/8d026e395aead442b10a3627efd8ae2186f42c7b/",
              "affiliate_id": "lemagasinducoin",
              "cart_id": "8d026e395aead442b10a3627efd8ae2186f42c7b"}}

L'attribut ``checkout_url``
---------------------------

C'est l'url vers laquelle le client doit être redirigé pour finir sa commande. Elle est fournie à chaque réponse. Le client arrive sur la page de visualisation de son panier sur le site de la Librairie Dialogues, le panier est attaché à sa session.