Documentation API

En bref

L'API REST de Shipper relie votre boutique en ligne, votre ERP ou votre logiciel logistique à votre compte Shipper. Elle permet de :

• demander en une requête les offres de plusieurs transporteurs ;
• commander l'envoi à partir de l'offre choisie ;
• télécharger les étiquettes, la facture et les documents de douane ;
• suivre et annuler un envoi.

Vous ouvrez les accès depuis votre compte Shipper. Votre développeur fait l'intégration dans un environnement de test, la sandbox, puis vous passez en production.

Mise en route en 4 étapes

1. Invitez votre développeur dans la sandbox

   Dans Mon compte › API, section « Accès à l'environnement de développement », indiquez l'adresse e-mail de votre développeur. Il reçoit une invitation, choisit son mot de passe et se connecte à la sandbox avec cette adresse.

   La sandbox est entièrement fictive : votre développeur n'a accès ni à votre compte ni à vos données. Pour lui retirer l'accès, supprimez son adresse ; pour confier la sandbox à quelqu'un d'autre, remplacez-la. La personne retirée est prévenue par e-mail.

2. Développez et testez

   Dans la sandbox, votre développeur renseigne une adresse de facturation, ajoute des crédits (paiements fictifs), puis crée sa clé dans Mon compte › API. Il peut alors demander des devis et commander des envois de test, sans rien expédier.

3. Demandez la mise en production

   Quand l'intégration est prête, ouvrez Mon compte › API dans votre compte Shipper et cliquez sur « Demande de mise en production ». Un ticket suit la demande ; comptez 48 à 72 heures. Vous êtes averti dès que l'accès est actif.

4. Créez vos clés de production

   Une fois l'accès actif, « Ajouter une clé » génère une clé et son mot de passe. Le mot de passe ne s'affiche qu'une fois : notez-le, sinon il faudra créer une nouvelle clé.

   Chaque clé peut être limitée à une liste d'adresses IP, modifiable ensuite. Vous pouvez créer autant de clés que nécessaire, par exemple une par système.

Serveurs

Les clés sont propres à chaque environnement : une clé de la sandbox ne fonctionne pas en production.

Authentification

Chaque requête s'authentifie en HTTP Basic avec la clé et son mot de passe : en-tête Authorization: Basic suivi de clé:mot de passe encodé en base64. Les outils HTTP le font pour vous :

curl -u "VOTRE_CLE:VOTRE_MOT_DE_PASSE" \
     -H "Accept: application/json" \
     https://api.sandbox.shipper.ch/quotation/12345

Une clé limitée à des adresses IP refuse les requêtes venant d'ailleurs. Gardez le mot de passe sur votre serveur : jamais dans le JavaScript d'une page web ni dans une application installée chez vos clients.

Déroulement d'un envoi

1. Devis : envoyez l'expéditeur, le destinataire et les colis à POST /quotation. La réponse donne un quotationId et les offres des transporteurs.
2. Choix : retenez l'offre qui vous convient (son quoteId).
3. Commande : POST /order avec le quoteId, la date d'enlèvement et, si l'envoi passe la douane, les articles de douane.
4. Documents : GET /order/{orderId}/document/{type} renvoie le fichier : labels (étiquettes), invoice (facture) ou customs (douane).
5. Suivi : GET /order/{orderId}/tracking.

Routes

• POST /quotation Créer un devis (offres de plusieurs transporteurs)
• GET /quotation/{quotationId} Relire un devis
• POST /order Commander un envoi à partir d'une offre
• GET /order/{orderId} Relire une commande
• GET /order/{orderId}/tracking Suivre l'envoi
• GET /order/{orderId}/document/{type} Télécharger un document
• GET /order/{orderId}/cancel Annuler la commande

Champs, valeurs autorisées et exemples complets : référence de l'API.

Requêtes et réponses

Les requêtes POST envoient un corps JSON (Content-Type: application/json) ; les requêtes GET passent leurs paramètres dans l'adresse. Demandez du JSON en retour avec Accept: application/json.

Sauf pour un document téléchargé (le corps est alors le fichier), la réponse est un objet JSON qui contient toujours header : error et endpoint, plus errorCode, errorMessage et errorField en cas d'erreur. Le code HTTP indique le résultat :

Références produit pour l'UE

Pour un envoi depuis la Suisse (ou un autre pays hors UE) à un particulier dans l'UE, l'UE exige deux références par article de douane :

• merchantProductId : votre référence article (SKU) ;
• manufacturerProductId : la référence du fabricant (modèle ou numéro de pièce). Si vous fabriquez le produit, reprenez votre référence article.

standardProductId (code GTIN ou EAN) est facultatif. Le destinataire est un particulier quand quotation.to.isCompany vaut false.

Dans votre espace client

Les devis demandés par l'API apparaissent dans vos devis, avec l'expéditeur, le destinataire et les tarifs proposés. Les envois commandés par l'API apparaissent dans vos expéditions, marqués « API », et un filtre les sépare des envois faits sur le site.

Aide

Une question sur l'intégration ? Ouvrez un ticket depuis votre compte ou écrivez-nous à E-mail : notre équipe technique vous répond.