Se connecter à l'API Cubyn – Centre d'aide Cubyn

L'API Cubyn est le moyen le plus flexible d'intégrer vos systèmes avec ceux de Cubyn.
Elle permet notamment :

d'importer les informations sur vos expéditions
de suivre vos expéditions : statut d'expédition & numéro de suivi
d'être informé de tout changement de statut de vos expéditions.

Vous pouvez retrouver toute la documentation de notre API sur ce site dédié : http://developers.cubyn.com.

Connexion à l’API Cubyn

Afin de vous connecter à l’API de Cubyn, il vous faut dans un premier temps ajouter l’application API Cubyn sur votre espace. Pour cela, suivez ces étapes :

Accédez à l'onglet Applications
Cliquez sur le bouton +
Cliquez sur Installer à côté de l'icône API Cubyn
Renseignez le nom de l’application que vous souhaitez afficher sur votre espace
Confirmez

Pour vous connecter à cette application depuis votre service, il vous faut récupérer votre clé API. Vous trouverez celle-ci dans le détail de l’application précédemment créée auquel vous pouvez accéder en cliquant sur la clé à molette accessible depuis l'onglet Applications. Cela vous permettra de récupérer votre clé API.

Grâce à cette connexion API, il vous est possible de réaliser les actions suivantes :

1- Envoi de stock

Afin de réaliser un envoi de stock, il vous est nécessaire de nous indiquer le nombre de colis à expédier ainsi que de nous fournir le détail par produit : SKU, nom du produit, code-barres et quantité. Ces éléments seront à rentrer dans les emplacements indiqué sur la requête d’envoi de stock que l’on peut retrouver ici.

{
 "packingUnits": 2,
 "items": [{
    "sku": "SKU1",
    "productName": "Name1",
    "barcode": "123456789",
    "quantity": 4
 },
 {
    "sku": "SKU2",
    "productName": "Name2",
    "barcode": "234567890",
    "quantity": 90
 }]
}

Vous obtiendrez en réponse l'identifiant WIO associé (pid) à votre envoi de stock ainsi que le nombre de colis et de produits déclaré.

{
 ...
 "pid": "184569",
 ...
 "declaredPackingUnits": 2,
 "receivedPackingUnits": 0,
 "completedPackingUnits": 0,
 "declaredItems": 94,
 "storedItems": 0,
 "createdAt": "2020-05-25T09:37:29.000Z",
 "updatedAt": "2020-05-25T09:37:29.000Z",
 "receiptStartedAt": null,
 "validatedAt": "2020-05-25T09:37:29.000Z",
 "completedAt": null,
 "deletedAt": null,
 ...
}

2- Suivi de l’inventaire

Il vous est possible de suivre en temps réel votre inventaire en utilisant la requête associée que l’on retrouve ici.

Cette requête vous affichera différentes informations par SKU dont notamment le nombre de produits en cours de réception, disponible, en cours de traitement et expédiés mais également le(s) code-barres associé(s).

[
 {
 ...
 "sku": "iPhone_10_32G_new",
 "sanitizedSku": "IPHONE-10-32G-NEW",
 "name": "iPhone 10 32G new",
 "isVirtual": false,
 "isBundle": false,
 "createdAt": "2020-05-07T14:59:45.000Z",
 "updatedAt": "2020-05-07T14:59:45.000Z",
 ...
 "stock": {
    "hadStockInbounded": true,
    "quantityAvailable": 7,
    "quantityOutbounded": 0,
    "quantityInbounding": 0,
    "quantityOutbounding": 1,
    ...
 },
 ...
 },
...
]

3- Création d’expédition

Afin de créer des expéditions, il vous est nécessaire de fournir différentes informations concernant le destinataire de l’envoi mais aussi les SKU des produits ainsi que ls quantité que vous souhaitez expédier. Le détail des informations nécessaire à la création d’une expédition est disponible ici.

{ 
 "type":"SHIPMENT",
 "firstName":"Sophie", 
 "lastName":"Martin", 
 "items":[ 
 { 
    "reference":"SKU1", 
    "count":1 
 } 
 ], 
 "orderRef": "Order1", 
 "address":{ 
    "line1":"13 rue Lecourbe", 
    "zip":"75007", 
    "city":"Paris",
    "country":"France", 
    "additionalInformation":"code 9898" 
 },
 "value": 10.99
}

Une fois la requête envoyée, elle vous retournera une synthèse de l’expédition avec les informations associées.

{
 ...
 "trackingId": "CUB131958015",
 "status": "CREATED",
 ...
 "address": {
 "line1": "13 rue Lecourbe",
 "line2": "",
 "zip": "75007",
 "city": "Paris",
 "state": "",
 "country": "FR",
 "additionalInformation": "code 9898"
 },
 "firstName": "Sophie",
 "lastName": "Martin",
 "value": 10.99,
 "deliveryMode": "standard",
 "deliverySigned": false,
 "objectCount": 1,
 "insurance": 0,
 "isAdvalorem": false,
 "orderRef": "Order1",
 "createdAt": "2020-05-25T10:07:28.000Z",
 "updatedAt": "2020-05-25T10:07:28.000Z",
 ...
 "items": [
 {
 "reference": "SKU1",
 "count": 1
 }
 ],
 ...
}

4- Suivi des expéditions

Enfin, il vous est possible de suivre vos expéditions en utilisant la requête associée que l’on retrouve ici.

En indiquant l’id à la fin de la requête, vous retrouverez le détail de l’expédition avec notamment le détail des informations du destinataire et le statut de l'expédition. Vous pouvez également avoir l’intégralité des informations si vous ne renseignez pas d’id.

5- Webhook

Il vous est également possible de rajouter dans les réglages de l’application API Cubyn l’URL du Webhook auquel nous pouvons envoyer des informations sur vos colis.

L’envoi d'information va être déclenché dès que votre expédition va subir un changement de statut dans nos entrepôts ou dès que l’expédition est envoyée. Il vous est possible de sélectionner les événements pour lesquels vous souhaitez être alerté. Ce choix s’effectue dans les réglages de l’application API Cubyn.

Nos systèmes vont générer une requêtes POST qui contiendront trois éléments principaux :

L’évènement sur votre expédition ayant déclenché l’envoi de la requête
Votre clé API
Le détail de votre expédition

Le détail de ces différents éléments est disponible dans la rubrique Webhook du chapitre Suivi des expéditions accessible ici.

Attention : nous vous recommandons de nous fournir un URL de webhook sous la forme HTTPs ainsi que de comparer fréquemment votre clé API à celle qui apparaît dans les requêtes envoyées afin sécuriser au maximum votre système.

🚨 Pour que les Wehbooks soient envoyées, la commande associée doit nécessairement avoir été créée via la clé API de la connexion. Si la commande a été créée manuellement, aucun Wehbook n'est envoyé.

Annexes

1- Joindre un fichier à votre expédition

Il vous sera nécessaire dans certaines situations de joindre un fichier à votre expédition, pour cela vous trouverez, dans la section Guide, accessible ici, le chapitre Parcel attachements qui vous indique la requête à effectuer pour joindre un fichier. Cette requête vous renverra une confirmation du fichier joint à votre expédition.

2- Construire la page de tracking Cubyn

Cubyn offre une page de suivi qui est commune à tous les transporteurs avec qui nous interagissons. Nous vous recommandons vivement de l'utiliser. Pour cela, il vous suffit de créer votre numéro de tracking puis, avec ce-dernier, vous rendre sur la page de tracking. Vous retrouverez le détail de ces étapes ici.

3- Expédier avec Cubyn Relay

Afin d’expédier vos colis en point relais, il vous est nécessaire de préciser le relayPickupRef. Ceci correspond à la localisation du point relais désiré, nous vous recommandons d’utiliser notre programme en ligne afin de le choisir. Travaillant actuellement avec Mondial Relay, il vous est tout de même possible de choisir votre point relais en utilisant leur plugin.

Pour plus d’information sur cet interface rendez-vous ici.

4- Réaliser des test sur l'environnement Sandbox

Cubyn offre un environnement Sandbox où vous pourrez tester votre intégration avant de vous lancer. Pour un accès à un compte Sandbox, veuillez demander à votre représentant commerciale chez Cubyn. Pour plus d’information sur cet interface rendez-vous ici.