Documentation API

Remarques générales

Commandes

Contenus et classification des contenus

Cotations

Dictionnaire des pays

Dictionnaire des points relais

État de la commande

Traduction des paramètres

URL de push

PROTOCOLE

Le protocole à utiliser pour tous les appels à l’API est https.

ENCODAGE

Les URIs d’appel à l’API v1 sont construites d’après le modèle suivant :

https://www.envoimoinscher.com/api/v1/[/][.../chemin/.../]/ressource
                                    

La langue par défaut est « fr », c’est la seule langue disponible à l’heure actuelle. C’est la langue des noms de paramètres à fournir dans les requêtes et des libellés des réponses. Par contre, les noms des ressources et les balises des documents XML de réponse sont toujours en anglais. Se référer à l’annexe pour une correspondance entre les noms français des paramètres et les balises en anglais associées.

L’URI doit être en minuscules.

FORMATS DES URLS ET REQUÊTES

Les requêtes sont à réaliser en :

  • GET (pour une consultation de ressource, une cotation),
  • POST (pour une commande).

Les paramètres sont à fournir :

  • dans le chemin de l’URI pour les requêtes GET de type ‘dictionnaire’,
  • avec une chaîne de requête (« query string ») spécifiant la valeur de chacun d’eux pour les requêtes GET ou POST de cotation ou de prise de commande.

FORMATS DES RÉPONSES

Toutes les réponses sont au format XML, sans attributs.

CODES DE RETOUR

Le code de retour HTTP peut être :

  • 200 : succès,
  • 400 : requête invalide,
  • 401 : accès interdit,
  • 404 : ressource non trouvée,
  • 500 : erreur interne du serveur.

En cas d’erreur, le corps de la réponse est un document XML structuré comme suit :

<error>
<code>code de l'erreur</code>
<message>message associé</message>
</error>
                                    

AUTHENTIFICATION

Chaque requête API nécessite la présence d’un en-tête authentification HTTP basic composé du login et du mot de passe que vous utilisez sur le site. En plus de cela, il faut rajouter une en-tête access_key dont la valeur correspond à la clé API attachée à votre compte.

TYPE DES ENVIRONNEMENTS

L’API est disponible sur deux serveurs : de production et de test. Dans la première phase de développement il vous est conseillé de travailler uniquement avec le serveur de test. Les commandes que vous allez passer sur ce serveur sont factices et en conséquence vous ne serez pas facturés. Le serveur de test pointe vers https://test.envoimoinscher.com.

Par contre, toutes les commandes passées sur le serveur de production sont bien réelles. Vous serez facturés. Le serveur de production pointe vers https://www.envoimoinscher.com.

PARAMÈTRES

Dans la réponse de cotation vous pouvez obtenir les éléments qui contiennent les informations facultatives à fournir, entre autres, pour les options. Chaque noeud est composé du code, libellé et type. Ce dernier détermine quel type de données est attendu par l’API. Les types possibles retournés dans la réponse sont :

  • string – une chaîne de caractères,
  • float – un nombre en virgule flotante,
  • boolean – true ou false,
  • enum – une liste de valeurs, qui peuvent être des identifiants renvoyant à un dictionnaire de données.

INFORMATIONS

  • On traite un envoi par commande,
  • la personne facturée (payeur) est la personne authentifiée. Cette personne doit être un client en compte ayant choisi le mode de paiement par prélèvement différé,
  • vous avez la possibilité de tester l’API sans être en prélèvement différé,
  • le pays d’expédition est pour l’instant restreint à la France et à l’Espagne,
  • les paramètres à fournir en POST sont hiérarchisés, avec le point (« . ») comme séparateur de niveau. Par exemple, package.weight correspond au poids du colis.

POST/API/V1/ORDER

Paramètres :

(type = ‘pli’, ‘colis’, ‘encombrant’, ‘palette’, N = numéro de colis (1, 2, 3…)) :

type.valeur en euros, obligatoire pour certains opérateurs et certaines destinations, utilisé aussi pour l’assurance valeur déclarée

ParamètreRemarques
platformapi / library
platform_versionvide / version de la plateforme utilisée
module_versionvide / votre numéro de version
type_N.poids
type_N.longueur
type_N.largeur
type_N.hauteurParamètre obligatoire sauf pour les envois de type “pli”
code_contenufacultatif, ‘200’ (non spécifié) par défaut – obligatoire (et 200 exclus) si l’on spécifie une valeur déclarée pour l’assurance
type.descriptiondescription de votre envoi
expediteur.payscode iso
expediteur.code_postalsauf si pas de code postal pour le pays concerné
expediteur.type‘particulier’ ou ‘entreprise’, pour une entreprise ou un particulier
expediteur.societe“nom_de_la_societe” obligatoire si type = entreprise
expediteur.ville
expediteur.adressenuméro et rue – s’il y a plusieurs lignes, les séparer avec ‘|’
expediteur.titre
expediteur.prenom
expediteur.nom
expediteur.email
expediteur.tel
expediteur.tel2
destinataire.payscode iso
destinataire.code_postalsauf si pas de code postal pour le pays concerné
destinataire.type‘particulier’ ou ‘entreprise’, pour une entreprise ou un particulier
destinataire.societe“nom_de_la_societe” obligatoire si type = entreprise
destinataire.ville
destinataire.adressenuméro et rue – s’il y a plusieurs lignes, les séparer avec ‘|’
destinataire.titre
destinataire.prenom
destinataire.nom
destinataire.email
destinataire.tel
destinataire.tel2
collectedate de collecte souhaitée au format YYYY-MM-DD
délai‘aucun’ => offres triées par prix décroissant,
‘minimum’ => offres triées par délai croissant,
‘course’ => seules les offres de course avec livraison dans la journée

PARAMÈTRES OPTIONNELS DE FILTRAGE DES OFFRES

ParamètreRemarques
operateurcode de l’opérateur à séléctionner
servicecode du service à séléctionner – operateur doit être spécifié dans ce cas
prix_max_ttc
prix_max_ht
prix_exact_ttc
prix_exact_ht
url_trackingLa page (sur votre serveur) qui va intercepter l’état de vos commandes et mettre à jour
votre suivi interne, toujours fonctionnel mais bientôt obsolète au profit d’url_push
url_pushElle servira à alimenter la page (sur votre serveur) avec des informations sur l’état de vos envois.
Elle vous fournira également les documents associés à vos envois.

PARAMÈTRES FACULTATIFS DES OPTIONS

ParamètreRemarques
assurance.emballagele type d’emballage utilisé (choix disponibles : Boîte, Caisse, Bac, Emballage isotherme, Etui, Malle, Sac, Tube)
assurance.fermeturela fermeture utilisée (choix disponibles : Fermeture autocollante, Ruban adhésif, Agrafes, Clous, Collage,
Ruban de cerclage, Sangle ou feuillard, Agraphes et cerclage, Clous et cerclage)
assurance.fixationla fixation utilisée (choix disponibles : Sans système de stabilisation, Film transparent, Film opaque,
Film opaque et sangles, Film transparent et sangles, Sangle ou feuillard uniquement)
assurance.materiaule matériau utilisé (choix disponibles : Carton, Bois, Carton blindé, Film opaque, Film transparent, Métal, Papier,
Papier armé, Plastique et carton, Plastique, Plastique opaque, Plastique transparent, Polystyrène)
assurance.nombrele nombre des colis sur la palette (int, uniquement pour l’envoi d’une palette)
assurance.protectionla protection intérieure utilisée (choix disponibles : Sans protection particulière, Calage papier, Bulles plastiques,
Carton antichoc, Coussin air, Coussin mousse, Manchon carton (bouteille), Manchon mousse (bouteille), Matelassage, Plaque mousse,
Polystyrène, Coussin de calage, Sachet bulles)
assurance.selectionsi true, l’assurance sera prise en compte (et soumise à une validation)
contre-remboursement.selectionla sélection de l’option contre remboursement
contre-remboursement.valeurla valeur attendue du contre-remboursement
depot.pointrelaisle point relais de dépôt ; string, l’identifiant du point
disponibilite.HDEstring; date en format H:i : signifie la disponibilité pour l’enlèvement
disponibilite.HLEstring; date en format H:i : signifie la disponibilité pour la livraison
livraison_imperative.DILla date à laquelle votre colis doit forcément être livré. Dans le tableau des options il est représenté par livraison_imperative.DIL
(string – la date en format d-m-Y, uniquement certains transporteurs)
retrait.pointrelaisle point relais de retrait ; string, l’identifiant du point
type_emballage.emballageLe type d’emballage de l’envoi ; string, l’identifiant du type d’emballage (la liste des types d’emballages est retournée par une Cotation sur les offres Colissimo)

S’il n’y a pas d’erreur, la réponse vaut pour confirmation de la commande (indépendamment des éventuelles confirmations par mail).

DTD SIMPLIFIÉE DE LA RÉPONSE :

cotation
  shipment
    (letter|package|bulky|pallet)
      weight
      length
      width
      height?
      quantity
    content
    collection_date
    delay
    description
    shipper
      type
      country
      zipcode
      city
      address
      company?
      title
      firstname
      lastname
      email
      phone
      phone2?
    recipient
      type
      country
      zipcode
      city
      address
      company?
      title
      firstname
      lastname
      email
      phone
      phone2?
  offer*
    mode
    url
    operator
      code
      label
      logo
    service
      code
      label
    price
      currency
      tax-inclusive
      tax-exclusive
      detail
        line+
        label
        currency
        tax-inclusive
        tax-exclusive
    collection
      type
        code
        label
      date
      time
      label
  delivery
    type
    date
    time?
    delay
    label
  alert*
  characteristics
    label*
                                    

Mode d’une offre : « COM » (pour le mode commande, signifie que cette offre peut être commandée via EMC) ou « SYN » (pour le mode syndication, signifie que cette offre est comparée à titre indicatif mais ne peut être commandée via EMC).

Types de collecte :

  • POST_OFFICE : dépôt en bureau de poste,
  • DROPOFF_POINT : dépôt en point relai,
  • HOME : enlèvement à domicile,
  • COMPANY : enlèvement en entreprise.

Types de livraison :

  • PICKUP_POINT : retrait en point relai,
  • HOME : livraison à domicile,
  • COMPANY : livraison en entreprise.

Les alertes sont des informations importantes à afficher à l’utilisateur (quand l’utilisation de l’API le permet).

Les informations obligatoires (« mandatory_informations ») sont des paramètres qu’il faudra obligatoirement fournir pour commander l’offre concernée. Elles sont normalisées et seront listées en annexe – le code client peut soit décider de les fixer à une valeur donnée, soit les demander à l’utilisateur à l’étape pré-commande (en affichant un checkbox / un edit / un select suivant le type de donnée).

Le prix de l’assurance est renseigné si et seulement si :

  • La requête contient un paramètre « assurance=true »,
  • la valeur déclarée est fourni pour l’envoi correspondant dans les paramètres POST (paramètre « valeur »),
  • le type d’objet est différent de 100 (« non spécifié »),
  • le type d’objet est couvert par l’assureur,
  • le pays de destination est couvert par l’assureur.

Les options sont actives si tous les paramètres POST correspondants sont renseignés lors d’une commande.

FACTURE PRO-FORMA

Certaines commandes peuvent exiger les informations supplémentaires qui vont servir à générer une facture pro-forma. Vous devez passer alors les paramètres suivants et incrémenter le numéro du paramètre pour chaque type de produits que vous envoyez :

ParamètreRemarques
raisonla raison de votre envoi (vente, réparation)
proforma_1.description_enla description du produit envoyé en anglais
proforma_1.description_frla description du produit envoyé en français
proforma_1.nombrela quantité du produit expédié
proforma_1.valeurla valeur unitaire du produit expédié
proforma_1.originel’origine du produit envoyé
proforma_1.poidsle poids unitaire du produit envoyé

Example :

POST /api/v1/order expediteur.pays=FR&expediteur.code_postal=75002&expediteur.type=entreprise&expediteur.ville=Paris&expediteur.adresse=15%2C+rue+Marsollier&expediteur.civilite=M&expediteur.prenom=Jon&expediteur.nom=Snow&expediteur.email=jsnow%40boxtal.com&expediteur.tel=0606060606&expediteur.infos=Some+additional+information+about+this+address&expediteur.societe=Boxtale+SAS&destinataire.pays=US&destinataire.code_postal=10036&destinataire.type=entreprise&destinataire.ville=New+York&destinataire.adresse=123+W+43rd+St&destinataire.civilite=Mme&destinataire.prenom=Jane&destinataire.nom=Doe&destinataire.email=jdoe%40boxtal.com&destinataire.tel=0606060606&destinataire.infos=&destinataire.societe=Boxtale+SAS&colis_1.poids=4&colis_1.longueur=7&colis_1.largeur=8&colis_1.hauteur=11&collecte=2017-04-23&delai=aucun&code_contenu=10120&operateur=UPSE&service=ExpressSaver&disponibilite.HDE=09%3A00&disponibilite.HLE=19%3A00&colis.description=Newspapers&assurance.selected=false&platform=library&platform_version=2.0.1&module_version=1.1.5&destinataire.etat=NY&raison=sale&proforma_1.description_en=L'Equipe+newspaper+from+1998&proforma_1.description_fr=Le+journal+L'Equipe+de+1998&proforma_1.number=1&proforma_1.value=12&proforma_1.origine=FR&proforma_1.poids=3.9&colis.valeur=12                                    

EXEMPLE DE RÉPONSE

<?xml version="1.0" encoding="UTF-8"?>
  <order>
    <shipment>
      <reference>1108161838UPSE2403FR</reference>
      <package>
        <weight>4.0</weight>
        <length>11</length>
        <width>8</width>
        <height>7</height>
        <quantity>1</quantity>
      </package>
      <content>10120</content>
      <collection_date>2011-08-22</collection_date>
      <delay>aucun</delay>
      <shipper>
        <type>entreprise</type>
        <country>FR</country>
        <zipcode>69002</zipcode>
        <city>LYON</city>
      </shipper>
      <recipient>
        <type>entreprise</type>
        <country>FR</country>
        <zipcode>75008</zipcode>
        <city>PARIS</city>
      </recipient>
      <labels>
        <label>
          http://test.envoimoinscher.com/bordereaux/Y1EZa19quPzkR2FIU1QjxtJpdkrbQzKI/1108161838UPSE2403FR_bordereau_1.pdf
        </label>
      </labels>
      <offer>
        <mode>COM</mode>
        <url> http://test.envoimoinscher.com/choix.html?envoi=eFR69002j0-eFR75008j60&ope=UPSE&srv=Standard </url>
        <operator>
          <code>Standard</code>
          <label>UPS Standard</label>
          <logo> http://test.envoimoinscher.com/operateurs/UPSE/logo_upse.gif </logo>
        </operator>
        <service>
          <code>Standard</code>
          <label>UPS Standard</label>
        </service>
        <price>
          <currency>EUR</currency>
          <tax-exclusive>12.19</tax-exclusive>
          <tax-inclusive>14.58</tax-inclusive>
          <detail>
            <line>
              <label>Prestation de transport, commande et traitement</label>
              <currency>EUR</currency>
              <tax-exclusive>12.19</tax-exclusive>
              <tax-inclusive>14.58</tax-inclusive>
            </line>
          </detail>
        </price>
        <collection>
          <type>
            <code>COMPANY</code>
            <label>enlèvement en entreprise</label>
          </type>
          <date>2011-08-22</date>
          <time>17:30</time>
        </collection>
        <delivery>
          <type>
            <code>COMPANY</code>
            <label>enlèvement en entreprise</label>
          </type>
          <date>2011-08-23</date>
          <time>19:00</time>
          <label>Livraison à l'adresse du destinataire le mardi 23 août avant 19:00</label>
        </delivery>
        <alert>
          Avant de passer commande, assurez-vous que l'expéditeur pourra imprimer le bordereau d'expédition UPS. Les colis doivent obligatoirement être emballés et leur contenu suffisamment protégé. Un emballage rigide (en bois, en carton triple cannelure, ...) est obligatoire pour tout contenu susceptible d'être déformé ou endommagé. Eviter les espaces vides à l'intérieur des colis. Votre envoi ne doit pas contenir de verre ni d'élément liquide.
        </alert>
        <characteristics>
          <label>Enlèvement de l'envoi à l'adresse de l'expéditeur le lundi 22 août</label>
          <label>Livraison à l'adresse du destinataire le mardi 23 août avant 19:00</label>
          <label>Délai non garanti</label>
          <label>Livraison contre signature ou cachet commercial</label>
          <label>Suivi en ligne possible</label>
          <label>la responsabilité contractuelle d'UPS est régie et est limitée conformément aux règles applicables (Convention de Varsovie ou Convention CMR, Convention de Montréal)</label>
        </characteristics>
      </offer>
    </shipment>
  </order>
                                    

Ces méthodes peuvent servir à construire un select HTML avec une option par contenu, et de regrouper ces options par groupes en fonction des catégories des contenus.

GET/API/V1/CONTENT_CATEGORIES

Toutes les catégories de contenus.

DTD SIMPLIFIÉE DE LA RÉPONSE :

content_categories
  content_category*
    code
    label
                                    

RÉPONSE :

<?xml version="1.0" encoding="UTF-8"?>
  <content_categories>
    <content_category>
    <code>10000</code>
    <label>Documents</label>
    </content_category>
    <content_category>
    <code>20000</code>
    <label>Alimentation et matières périssables</label>
    </content_category>
    ...
    </content_categories>
                                    

GET/API/V1/CONTENTS

Tous les contenus.

DTD SIMPLIFIÉE DE LA RÉPONSE :

contents
  content*
    code
    label
    category
                                    

RÉPONSE :

<?xml version="1.0" encoding="UTF-8"?>
  <contents>
    <content>
    <code>100</code>
    <label<>Contenu non spécifié</label>
    <categorie>0</categorie>
    </content>
    <content>
    <code>10100</code>
    <label>Documents sans valeur commerciale</label>
    <categorie>10000</categorie>
    </content>
    ...
  </contents>
                                    

GET/API/V1/CONTENT_CATEGORY/ID_CATEGORIE/CONTENTS

Toutes les contenus d’une catégorie.

DTD SIMPLIFIÉE DE LA RÉPONSE :

content_categories
  content_category*
    code
    label
                                    

RÉPONSE :

<?xml version="1.0" encoding="UTF-8"?>
  <content_categories>
    <content_category>
      <code>10000</code>
      <label>Documents</label>
    </content_category>
    <content_category>
      <code>20000</code>
      <label>Alimentation et matières périssables</label>
    </content_category>
  …
  </content_categories>
                                    

GET/API/V1/COTATION

Une cotation concerne un envoi unique, constitué d’un objet (pli, colis, encombrant, palette) unique. Le pays d’expédition est pour l’instant restreint à la France. Les paramètres à fournir en GET sont hiérarchisés, avec le point (« . ») comme séparateur de niveau. Par exemple, package.weight correspond au poids du colis.

PARAMÈTRES

(type = ‘pli’, ‘colis’, ‘encombrant’, ‘palette’, N = numéro de colis (1, 2, 3…))

ParamètreRemarques
type_N.poids
type_N.longueur
type_N.largeur
type_N.hauteur sauf pour type: pli
code_contenu le contenu de votre envoi (voir rubrique 'Contenus et classification de contenus')
type.valeur en euros, obligatoire pour certains opérateurs et certaines destinations, utilisé aussi
pour l’assurance valeur déclarée
expediteur.pays code iso
expediteur.code_postal sauf si pas de code postal pour le pays concerné
expediteur.type ‘particulier’ ou ‘entreprise’, pour une entreprise ou un particulier
destinataire.pays code iso
destinataire.code_postal sauf si pas de code postal pour le pays concerné
destinataire.type ‘particulier’ ou ‘entreprise’, pour une entreprise ou un particulier
collecte date de collecte souhaitée au format YYYY-MM-DD
délai ‘aucun’ => offres triées par prix décroissant,
‘minimum’ => offres triées par délai croissant,
‘course’ => seules les offres de course avec livraison dans la journée

PARAMÈTRES OPTIONNELS DE FILTRAGE DES OFFRES

ParamètreRemarques
opérateur code de l’opérateur à séléctionner
prix_max_ttc
prix_max_ht
prix_exact_ttc
prix_exact_ht

PARAMÈTRES ADDITIONNELS

Dans la réponse a une demande de cotation sont indiquées pour chaque offre de service les paramètres requis et optionnels spécifiques à cette offre. Lorsqu’ils sont déjà spécifiés, la cotation en tiendra compte dans le prix renvoyé (si les paramètres en question ont une incidence sur le prix).

cotation
  shipment
    (letter|package|bulky|pallet)
      weight
      length
      width
      height?
      quantity
    content
    collection_date
    delay
    description
    shipper
      type
      country
      zipcode
      city
    recipient
      type
      country
      zipcode
      city
  offer*
    mode
    url
    operator
      code
      label
      logo
    service
      code
      label
    price
      currency
      tax-inclusive
      tax-exclusive
    collection
    type
      code
      label
    date
    time
    label
  delivery
    type
    code
    label
    date
    time | delay
    label
  alert*
  characteristics
    label*
  mandatory_informations?
    parameter*
      code
      label
      type
        boolean
        |string
        |float
        |enum
          value+
  insurance?
    currency
    tax-inclusive
    tax-exclusive
  options?
    option
      code
      label
      parameter+
        code label
        type
          boolean
          |string
          |float
          |enum
            value+
      price
        currency
        tax-inclusive
        tax-exclusive
                                    

Mode d’une offre : « COM » (pour le mode commande, signifie que cette offre peut être commandée via EMC) ou « SYN » (pour le mode syndication, signifie que cette offre est comparée à titre indicatif mais ne peut être commandée via EMC).

Types de collecte :

  • POST_OFFICE : dépôt en bureau de poste,
  • DROPOFF_POINT : dépôt en point relais,
  • HOME : enlèvement à domicile,
  • COMPANY : enlèvement en entreprise.

Types de livraison :

  • PICKUP_POINT : retrait en point relai,
  • HOME : livraison à domicile,
  • COMPANY : livraison en entreprise.

Les alertes sont des informations importantes à afficher à l’utilisateur (quand l’utilisation de l’API le permet).

Les informations obligatoires (« mandatory_informations ») sont des paramètres qu’il faudra obligatoirement fournir pour commander l’offre concernée. Elles sont normalisées et seront listées en annexe – le code client peut soit décider de les fixer à une valeur donnée, soit les demander à l’utilisateur à l’étape pré-commande (en affichant un checkbox / un edit / un select suivant le type de donnée).

Le prix de l’assurance est renseigné si et seulement si :

  • la requête contient un paramètre « assurance=true »,
  • la valeur déclarée est fourni pour l’envoi correspondant dans les paramètres POST (paramètre « valeur »),
  • le type d’objet est différent de 100 (« non spécifié »),
  • le type d’objet est couvert par l’assureur,
  • le pays de destination est couvert par l’assureur.

Les options sont actives si tous les paramètres GET correspondants sont renseignés lors d’une commande. Les paramètres peuvent apparaître aux mêmes niveaux hiérarchiques que shipper et recipient.

Exemple :

GET/api/v1/cotation expediteur.pays=FR&expediteur.code_postal=44000&expediteur.ville=Nantes&expediteur.type=particulier& expediteur.adresse= 1% 2C+rue+Racine&destinataire.pays=FR&destinataire.code_postal=75002&destinataire.ville=Paris&destinataire.type= particulier&destinataire.adresse=1% 2C+rue+du+Grand+Lebrun&colis_1.poids=3&colis_1.longueur=7&colis_1.largeur=8& colis_1.hauteur=11&colis_2.poids=3&colis_2.longueur=7&colis_2.largeur=8&colis_2.hauteur=11&collecte=2011-08-24& delai=aucun&code_contenu=10120
                                    

RÉPONSE

<?xml version="1.0" encoding="UTF-8"?>
  <cotation>
    <shipment>

      <package>
        <weight>3.0</weight>
        <length>11</length>
        <width>8</width>
        <height>7</height>
        <quantity>1</quantity>
      </package>

      <package>
        <weight>3.0</weight>
        <length>11</length>
        <width>8</width>
        <height>7</height>
        <quantity>1</quantity>
      </package>

      <content>10120</content>
      <collection_date>2011-08-22</collection_date>
      <delay>aucun</delay>

      <shipper>
        <type>particulier</type>
        <country>FR</country>
        <zipcode>44000</zipcode>
        <city>NANTES</city>
      </shipper>

      <recipient>
        <type>particulier</type>
        <country>FR</country>
        <zipcode>75008</zipcode>
        <city>PARIS</city>
      </recipient>

      <offer>

        <mode>COM</mode>

        <url> http://www.envoimoinscher.com/choix.html?envoi=pFR44000j0-pFR75002j60&ope=SOGP&srv=RelaisColis </url>

        <operator>
          <code>SOGP</code>
          <label>Relais Colis</label>
          <logo> http://www.envoimoinscher.com/operateurs/SOGP/logo_sogp.gif </logo>
        </operator>

        <service>
          <code>Relais Colis</code>
          <label>Relais Colis®</label>
        </service>

        <price>
          <currency>EUR</currency>
          <tax-exclusive>10.37</tax-exclusive>
          <tax-inclusive>12.40</tax-inclusive>
        </price>

        <collection>
          <type>
            <code>DROPOFF_POINT</code>
            <label>dépôt en point relais</label>
          </type>
          <date>2011-08-24</date>
          <label>Vous déposez votre envoi dans un Relai Colis® à partir du mercredi 24 août</label>
        </collection>

        <delivery>
          <type>
            <code>PICKUP_POINT</code>
            <label>retrait en point relais</label>
          </type>
          <date>2011-08-31</date>
          <label>Le Relais Colis® d'arrivée peut être choisi par le destinataire. Mise à disposition en Relais Colis® à partir du mercredi 31 août avant 15h. L'envoi reste à disposition pendant 14 jours</label>
        </delivery>

        <alert>
          Vérifiez bien que le poids et les dimensions de votre colis sont exactes. Assurez vous que votre colis ne contient pas de denrées périssables, des bouteilles, des liquides ou des matières dangereuses ou interdites. Dans le cas contraire votre envoi pourrait être détruit ou refusé lors de sa prise en charge dans un Relais Colis®. L'expéditeur s'interdit de remettre en Relais Colis® des documents originaux et uniques dont le remplacement est impossible.
        </alert>

        <characteristics>
          <label>Vous déposez votre envoi dans un Relais Colis® à partir du mercredi 24 août</label>
          <label>Le Relais Colis® d'arrivée peut être choisi par le destinataire</label>
          <label>Mise à disposition en Relais Colis® à partir du mercredi 31 août avant 15h. L'envoi reste à disposition pendant 14 jours</label>
          <label>Délai non garanti : le destinataire est informé de la mise à disposition de l'envoi par email</label>
          <label>Suivi en ligne possible</label>
          <label>Assurance contractuelle en cas de perte, déterioration ou spoliation de votre envoi : indemnité de 23€ par kg</label>
        </characteristics>

        <mandatory_informations>
          <parameter>
            <code>colis.description</code>
            <label>description du contenu de l'envoi</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>colis.valeur</code>
            <label>valeur déclarée du contenu de l'envoi</label>
            <type><float/></type>
          </parameter>

          <parameter>
            <code>expediteur.civilite</code>
            <label>civilite de l'expéditeur</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>expediteur.nom</code>
            <label>nom de l'expéditeur</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>expediteur.prenom</code>
            <label>prenom de l'expéditeur</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>expediteur.email</code>
            <label>email de l'expéditeur</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>destinataire.civilite</code>
            <label>civilite du destinataire</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>destinataire.nom</code>
            <label>nom du destinataire</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>destinataire.prenom</code>
            <label>prenom du destinataire</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>destinataire.email</code>
            <label>email du destinataire</label>
            <type><string/></type>
          </parameter>

          <parameter>
            <code>depot.pointrelais</code>
            <label>choix du point relais de départ</label>
            <type>
              <enum>
                <value>SOGP-O1130</value>
                <value>SOGP-O1128</value>
                <value>SOGP-O1164</value>
                <value>SOGP-O1129</value>
                <value>SOGP-O1044</value>
                <value>SOGP-O1113</value>
                <value>SOGP-O1170</value>
                <value>SOGP-O1177</value>
                <value>SOGP-O1154</value>
                <value>SOGP-O1106</value>
              </enum>
            </type>
          </parameter>

          <parameter>
            <code>retrait.pointrelais</code>
            <label>choix du point relais d'arrivée</label>
            <type>
              <enum>
                <value>SOGP-A1120</value>
                <value>SOGP-A1246</value>
                <value>SOGP-A1168</value>
                <value>SOGP-A1171</value>
                <value>SOGP-A1070</value>
                <value>SOGP-A1169</value>
                <value>SOGP-A1262</value>
                <value>SOGP-A1138</value>
                <value>SOGP-A1062</value>
                <value>SOGP-A1249</value>
              </enum>
            </type>
          </parameter>
        </mandatory_informations>
      </offer>

      <offer>
      <mode>COM</mode>
      <url> http://www.envoimoinscher.com/choix.html?envoi=pFR44000j0-pFR75002j60&ope=UPSE&srv=Standard </url>

      <operator>
        <code>UPSE</code>
        <label>UPS</label>
        <logo> http://www.envoimoinscher.com/operateurs/UPSE/logo_upse.gif </logo>
      </operator>

      <service>
        <code>Standard</code>
        <label>UPS Standard</label>
      </service>

      <price>
        <currency>EUR</currency>
        <tax-exclusive>18.41</tax-exclusive>
        <tax-inclusive>22.02</tax-inclusive>
      </price>

      <collection>
        <type>
          <code>HOME</code>
          <label>enlèvement à domicile</label>
        </type>
        <date>2011-08-24</date>
        <time>17:30</time>
        <label>Enlèvement de l'envoi à l'adresse de l'expéditeur le mercredi 24 août</label>
      </collection>

      <delivery>
        <type>
          <code>HOME</code>
          <label>livraison à domicile</label>
        </type>
        <date>2011-08-25</date>
        <time>19:00</time>
        <label>Livraison à l'adresse du destinataire le jeudi 25 août avant 19:00</label>
      </delivery>

      <alert>
        Avant de passer commande, assurez-vous que l'expéditeur pourra imprimer le bordereau d' expédition UPS. Les colis doivent obligatoirement être emballés et leur contenu suffisamment protégé. Un emballage rigide (en bois, en carton triple cannelure, ...) est obligatoire pour tout contenu susceptible d'être déformé ou endommagé. Eviter les espaces vides à l'intérieur des colis. Votre envoi ne doit pas contenir de verre ni d'élément liquide.
      </alert>

      <characteristics>
        <label>Enlèvement de l'envoi à l'adresse de l'expéditeur le mercredi 24 août</label>
        <label>Livraison á l'adresse du destinataire le jeudi 25 août avant 19:00</label>
        <label>Délai non garanti</label>
        <label>Livraison contre signature ou cachet commercial</label>
        <label>Suivi en ligne possible</label>
        <label>La responsabilité contractuelle d'UPS est régie et est limitée conformément aux règles applicables (Convention de Varsovie ou Convention CMR, Convention de Montréal)</label>
      </characteristics>

      <mandatory_informations>
        <parameter>
          <code>colis.description</code>
          <label>description du contenu de l'envoi</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>colis.valeur</code>
          <label>valeur déclarée du contenu de l'envoi</label>
          <type><float/></type>
        </parameter>

        <parameter>
          <code>expediteur.civilite</code>
          <label>civilite de l'expéditeur</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>expediteur.nom</code>
          <label>nom de l'expéditeur</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>expediteur.prenom</code>
          <label>prenom de l'expéditeur</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>expediteur.email</code>
          <label>email de l'expéditeur</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>destinataire.civilite</code>
          <label>civilite du destinataire</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>destinataire.nom</code>
          <label>nom du destinataire</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>destinataire.prenom</code>
          <label>prenom du destinataire</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>destinataire.email</code>
          <label>email du destinataire</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>disponibilite.HDE</code>
          <label>Heure de fin de disponibilité pour l'enlèvement</label>
          <type><string/></type>
        </parameter>

        <parameter>
          <code>disponibilite.HLE</code>
          <label>Heure de début de disponibilité pour l'enlèvement</label>
          <type><string/></type>
        </parameter>
      </mandatory_informations>

      <options>
        <option>
          <code>contre-remboursement</code>
          <name>Contre-remboursement</name>
          <parameter>
            <code>contre-remboursement.selection</code>
            <label>Paramètre de séléction de l'option : Contre-remboursement</label>
            <type><boolean/></type>
          </parameter>
          <parameter>
            <code>contre-remboursement.valeur</code>
            <label>Valeur attendue du contre-remboursement</label>
            <type><float/></type>
          </parameter>
          <price>
            <currency>EUR</currency>
            <tax-exclusive>15.00</tax-exclusive>
            <tax-inclusive>17.94</tax-inclusive>
          </price>
        </option>

        <option>
          <code>assurance</code>
          <name>Assurance Ad-Valorem</name>

          <parameter>
            <code>assurance.selection</code>
            <label>Paramètre de séléction de l'option : Assurance Ad-Valorem</label>
            <type><boolean/></type>
          </parameter>

          <parameter>
          <code>assurance.emballage</code>
          <label>Type d'emballage utilisé</label>
            <type>
              <enum>
                <value>Boîte</value>
                <value>Caisse</value>
                <value>Bac</value>
                <value>Emballage isotherme</value>
                <value>Étui</value>
                <value>Malle</value>
                <value>Sac</value>
                <value>Tube</value>
              </enum>
            </type>
          </parameter>

          <parameter>
            <code>assurance.materiau</code>
            <label>Matériau utilisé</label>
            <type>
              <enum>
                <value>Carton</value>
                <value>Bois</value>
                <value>Carton blindé</value>
                <value>Film opaque</value>
                <value>Film transparent</value>
                <value>Métal</value>
                <value>Papier</value>
                <value>Papier armé</value>
                <value>Plastique et carton</value>
                <value>Plastique</value>
                <value>Plastique opaque</value>
                <value>Plastique transparent</value>
                <value>Polystyrène</value>
              </enum>
            </type>
          </parameter>

          <parameter>
            <code>assurance.protection</code>
            <label>Protection intérieure utilisée</label>
            <type>
              <enum>
                <value>Sans protection particulière</value>
                <value>Calage papier</value>
                <value>Bulles plastiques</value>
                <value>Carton antichoc</value>
                <value>Coussin air</value>
                <value>Coussin mousse</value>
                <value>Manchon carton</value>
                <value>Manchon mousse</value>
                <value>Matelassage</value>
                <value>Plaque mousse</value>
                <value>Polystyrène</value>
                <value>Coussin de calage</value>
                <value>Sachet bulles</value>
              </enum>
            </type>
          </parameter>

          <parameter>
            <code>assurance.fermeture</code>
            <label>Fermeture utilisée</label>
            <type>
              <enum>
                <value>Fermeture utilisée</value>
                <value>Ruban adhésif</value>
                <value>Agrafes</value>
                <value>Clous</value>
                <value>Collage</value>
                <value>Ruban de cerclage</value>
                <value>Sangle ou feuillard</value>
                <value>Agrafes et cerclage</value>
                <value>Clous et cerclage</value>
              </enum>
            </type>
          </parameter>
        </option>
      </options>
      </offer>
                                    

GET/API/V1/COUNTRIES

Liste de tous les pays.

DTD SIMPLIFIÉE DE LA RÉPONSE

countries
  country*
    code
    label
                                    

RÉPONSE

<?xml version="1.0" encoding="UTF-8"?>
  <countries>
    <country>
      <code>P1</code>
      <label>ACORES (PORTUGAL)</label>
    </country>

    <country>
      <code>AF</code>
      <label>AFGHANISTAN</label>
    </country>
    ...
  </countries>
                                    

GET/API/V1/DROPOFF_POINT/DROPOFF_POINT_CODE/INFORMATIONS

Dictionnaire des points relais de départ.

GET/API/V1/PICKUP_POINT/PICKUP_POINT_CODE/INFORMATIONS

Dictionnaire des points relais d’arrivée.

DTD SIMPLIFIÉE DE LA RÉPONSE

pickup-point|dropoff_point
  code
  name
  address
  city
  zipcode
  country
  phone
  description
  schedule
    day*
  weekday
  open_am
  close_am
  open_pm
  close_pm
                                    

RÉPONSE

<?xml version="1.0" encoding="UTF-8"?>
  <dropoff_point>
    <code>SOGP-O1164</code>
    <name>PETIT CASINO CHANTENAY</name>
    <address>7 rue Garibaldy</address>
    <city>NANTES</city>
    <zipcode>44100</zipcode>
    <country>FR</country>
    <phone></phone>
    <description></description>
    <schedule>
      <day>
        <weekday>1</weekday>
        <open_am>08:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm>15:00:00</open_pm>
        <close_pm>20:00:00</close_pm>
      </day>
      <day>
        <weekday>2</weekday>
        <open_am>08:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm>15:00:00</open_pm>
        <close_pm>20:00:00</close_pm>
      </day>
      <day>
        <weekday>3</weekday>
        <open_am>08:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm>15:00:00</open_pm>
        <close_pm>20:00:00</close_pm>
      </day>
      <day>
        <weekday>4</weekday>
        <open_am></open_am>
        <close_am></close_am>
        <open_pm>16:00:00</open_pm>
        <close_pm>20:30:00</close_pm>
      </day>
      <day>
        <weekday>5</weekday>
        <open_am>08:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm>15:00:00</open_pm>
        <close_pm>20:00:00</close_pm>
      </day>
      <day>
        <weekday>6</weekday>
        <open_am>08:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm>15:00:00</open_pm>
        <close_pm>20:00:00</close_pm>
      </day>
      <day>
        <weekday>7</weekday>
        <open_am>09:00:00</open_am>
        <close_am>13:00:00</close_am>
        <open_pm></open_pm>
        <close_pm></close_pm>
      </day>
    </schedule>
  </dropoff_point>
                                    

Cette ressource permet de vérifier en temps réel l’état d’une commande passée via l’API.

GET/API/V1/ORDER_STATUS/$REFERENCE/INFORMATIONS

Le paramètre $reference signifie la référence EnvoiMoinsCher.com de la commande (par exemple : 1209161836UPSE9311FR).

DTD SIMPLIFIÉE DE LA RÉPONSE

order
  emc_reference
  state
  carrier_reference
  label_available
  label_url
                                    

RÉPONSE

<?xml version="1.0" encoding="UTF-8"?>
  <order>
    <emc_reference>1209161836UPSE9311FR</emc_reference>
    <state>Commande validée par le transporteur</state>
    <carrier_reference>1Z82R54X6898122001</carrier_reference>
    <label_available>1</label_available>
    <label_url> http://test.envoimoinscher.com/documents?type=bordereau&envoi =1209161836UPSE9311FR </label_url>
  </order>
                                    

Les paramètres fournis peuvent être exprimés soit en français, soit en anglais.
Voici le dictionnaire des traductions :

Paramètre en françaisParamètre en anglais
expediteurshipper
destinatairerecipient
collectecollecte_date
delaidelay
envoishipment
pliletter
colispackage
encombrantbulky
palettepallet
poidsweight
longueurlength
largeurwidth
hauteurheight
payscountry
codepostalzipcode
typetype
particulierindividual
societecompany
code_contenucontent_code
aucunnone
coursecourier
assuranceinsurance
civilitetitle
prenomfirstname
nomlastname
adresseaddress
villecity
telphone
tel2phone2
infosdetails
fonctionrole
proformaproforma
raisonreason
nombrenumber
valeurvalue
reference_externeexternal_reference
operateuroperator
prix_max_ttcmax_tax_inclusive_price
prix_max_htmax_tax_exclusive_price
prix_exact_ttcexact_tax_inclusive_price
prix_exact_htexact_tax_exclusive_price

Si vous choisissez de mettre en place un système de notification pour le suivi d’envoi, il vous faudra utiliser url_push. Lors d’une commande, une URL de push sera générée.

Elle doit être construite sur le modèle suivant :

www.mon-site.com?order=number&key=number
                                    

Les paramètres order et key sont cités ici à titre d’exemple, le choix de ces paramètres est à votre discrétion.

URL de push permet d’obtenir des informations sur l’état de la commande, ou sur les documents associés à la commande.

Le serveur d’envoimoinscher vous enverra des notifications sous cette forme :

url_push?order=number&key=number&type=tracking& ...
                                    

ou encore :

url_push?order=number&key=number&type=status& ...
                                    

Si le paramètre principal type prend la valeur de tracking, les paramètres associées seront les suivants : text, localisation, etat, date.

Si le paramètre principal type prend la valeur de status, les paramètres associées seront les suivants : emc_reference, carrier_reference, label_url et optionnellement : remise, manifest, connote, proforma, b13a.

manifest (optionnel) : url du document de suivi TNT International.

ParamètreParamètres associés
type :
“tracking”
text : message émanant du transporteur relatif au statut de l’envoi.
localisation : localisation géographique de l’objet envoyé.
etat : flag qui donne l’état de la commande, il existe 4 états.
CMD : envoi pris en compte par le transporteur
ENV : envoi en cours d’acheminement
ANL : commande annulée
LIV : envoi livré
date : date de mise à jour du status.
envoi : référence envoimoinscher.
type :
“status”
emc_reference : référence envoimoinscher.
carrier_reference : référence du transporteur.
label_url : url du bordereau d’expédition.
remise (optionnel) : url du bordereau de remise Coliposte.
connote (optionnel) : url du eçu de prise en charge TNT International.
proforma (optionnel) : url de la facture proforma pour les envois internationaux.
b13a (optionnel) : url de la déclaration d’exportation b13a pour l’export depuis le Canada.