DOCUMENTATION

API DELIVERY PRO

Grâce à notre API sécurisé, accessible avec votre compte Delivery Pro, vous avez la possibilité d’enregistrer facilement et rapidement tous vos colis en envoyant toutes vos données au format JSON.

Explication des différentes variables du JSON à utiliser

Ci-contre, le JSON que vous devez envoyer vers notre API en utilisant la méthode POST ou PUT (Choisissez la méthode qui vous convient).

Vous devez utiliser le lien API affiché dans votre module API de votre compte.

Toutes les variables marquées d’une astérisque * sont obligatoires.

Certaines peuvent être absentes du JSON en fonction des options d’automatisation que vous renseignez dans le module API de votre compte.

Exemple, le lieu de chargement est toujours le même :

Dans ce cas, renseignez une seule fois les variables de chargement dans votre module API de votre compte. Vous n’avez plus besoin d’inclure celles-ci dans votre JSON. Notre API se chargera automatiquement de compléter les champs manquants avec les données renseignées.

[
{
ID Unique
"order_uniqid": "", ID unique de la commande provenant de votre base de données. Cet ID nous évitera les doublons et vous servira en retour de voir le statut d'enregistrement et de livraison.
Client
"client_number": "", Numéro/référence du client donneur d'ordre. Tous vos clients doivent au préalable être enregistrés dans le module "Clients" de votre compte Shagya. Vous pouvez être votre propre client.
Livreur
"deliverer_email": "", Email du livreur prenant en charge la livraison. Tous vos livreurs doivent au préalable être enregistrés et validés dans le module "Livreurs" de votre compte Shagya.
Colis
"pack_ref": "", Référence du colis propre à vous
"pack_nb": "", Le nombre de colis à livrer
Chargement
"pickup_company": "", Le nom de la société
"pickup_contact": "", La personne de contact
"pickup_phone": "", Le téléphone de cette personne
"pickup_address": "", L'adresse + Numéro
"pickup_pc": "", Le code postal
"pickup_city": "", La ville
"pickup_lat": "", La latitude
"pickup_long": "", La longitude
"pickup_date": "", La date
Format US : "XXXX-XX-XX"
Exemple : "2023-06-24" pour le 24 juin 2023)
"pickup_hour": "", L'heure
Soit "am" (entre 8h et midi)
Soit "pm" (entre midi et 18h)
Soit "XX:XX" pour une heure précise
Exemple: "09:30" pour 9h30 du matin
Livraison
"delivery_company": "", Le nom de la société
"delivery_contact": "", La personne de contact
"delivery_phone": "", Le téléphone de cette personne
"delivery_address": "", L'adresse + Numéro
"delivery_pc": "", Le code postal
"delivery_city": "", La ville
"delivery_lat": "", La latitude
"delivery_long": "", La longitude
"delivery_date": "", La date
(Même principe que "pickup_date")
"delivery_hour": "" L'heure
(Même principe que "pickup_hour")
}
]

Exemple d’un JSON

Vous avez la possibilité d’enregistrer plusieurs commandes simultanément si vous le souhaitez.

Placez toujours le JSON dans un tableau entre crochets [  ]

  • Pour une seule commande : [ {…} ]
  • Pour plusieurs commandes : [ {…}, {…}, {…} ]

Le JSON ci-contre de John et Jane Doe indique que :

Dans cet exemple, le lieu de chargement reste le même car les données y afférentes ont été renseignées dans le module API. C’est pourquoi certaines variables “pickup” sont absentes du JSON.

  • John a une société. (la variable “delivery_company” est remplie) 
  • Jane n’en a pas. (la variable “delivery_company” est vide) 
  • Jane n’a pas souhaité donner son téléphone privée, ni les coordonnées GPS de son domicile. (Les variables sont absentes)

Dans votre JSON :

Les variables facultatives peuvent être absentes ou incluses avec une valeur vide. Cependant, assurez-vous de remplir correctement tous les champs obligatoires dans le format requis, tel que le format américain pour les dates.

 

[
  {
    "order_uniqid": 4056,
    "client_number": "C-102011",
    "deliverer_email": "livreur@gmail.com",
    "pack_ref": "HB345DEFR45DKJG",
    "pack_nb": 1,
    "pickup_date": "2023-06-08",
    "pickup_hour": "09:30",
    "delivery_company": "John Company",
    "delivery_contact": "John Doe",
    "delivery_phone": "+687123456",
    "delivery_address": "Rue du Test, 23",
    "delivery_pc": "98800",
    "delivery_city": "Nouméa",
    "delivery_lat": -22.2745864,
    "delivery_long": 166.442419,
    "delivery_date": "2023-06-08",
    "delivery_hour": "10:00"
  },
  {
    "order_uniqid": 4057,
    "client_number": "C-102011",
    "deliverer_email": "livreur@gmail.com",
    "pack_ref": "KF455DEFR45DKJG",
    "pack_nb": 2,
    "pickup_date": "2023-06-08",
    "pickup_hour": "10:30",
    "delivery_company": "",
    "delivery_contact": "Jane Doe",
    "delivery_address": "Rue du Test, 45",
    "delivery_pc": "98800",
    "delivery_city": "Nouméa",
    "delivery_date": "2023-06-08",
    "delivery_hour": "11:00"
  }
]

API en mode “Enregistrement” ou “Test”

Utilisez ce lien en mode POST ou PUT pour envoyer votre JSON :
https://api.shagya.nc/votre-clé-api/save
https://api.shagya.nc/votre-clé-api/test

Le mode Test vous permet de vérifier si votre JSON est exempt d’erreurs. Il est similaire au mode “Enregistrement” à l’exception qu’il ne sauvegarde aucune donnée dans notre système.

Si les variables ont été correctement introduites,
vous recevez en retour ce JSON :

[
    {
        "order_uniqid": 2466,
        "status": "saved"
    }
]

Si une ou plusieurs erreurs ont été détectées,
vous recevez en retour ce JSON :

[
    {
        "order_uniqid": 2467,
        "status": "not_saved",
        "errors": {
        	"pickup_company": "missing",
        	"pickup_date": "format"
        }
    }
]

API en mode “Lecture”

Utilisez ce lien en mode POST ou PUT pour lire les statuts :
https://api.shagya.nc/votre-clé-api/read

L’API en mode lecture renvoie uniquement les colis livrés.

Ci-dessous, un exemple de JSON en réponse :

  • John Doe a été livré.
  • Jane n’a pas été livrée car elle n’apparaît pas dans le JSON. 
[
    {
        "order_uniqid": 4056,
        "delivery_contact": "John Doe",
        "delivery_status": "delivered"
    }
]

Filtre

Vous avez la possibilité de filtrer le résultat en envoyant en mode POST un JSON. Ci-dessous la liste des filtres possibles.

[
    {
        "date_from": "2023-06-01",
        "date_to": "2023-06-30",
        "order_uniqid_from": 4000,
        "order_uniqid_to": 5000,
        "client_number": "C-102011",
        "deliverer_email": "livreur@gmail.com",
        "pack_ref": "REF-345-DNGHJ-23",
        "limit": 50,
        "sort": "desc"
    }
     
]

Si vous n’utilisez aucun filtre, vous devez envoyer un JSON contenant un tableau vide comme ci-dessous.

[]

Différents messages d’erreurs

“already_saved”

  • La commande ayant cet ID unique a déjà été sauvegardée.

“date_today”

  • La date indiquée dans votre JSON est antérieure à celle d’aujourd’hui. Celle-ci doit être égale ou postérieure.

“delivery_date”

  • Si la date de livraison et la date de chargement se situent dans la même année, la date de livraison doit être égale ou postérieure à la date de chargement.

“delivery_hour”

  • Si la livraison a lieu le même jour que le chargement, l’heure de livraison doit être postérieure à l’heure de chargement et ne peut en aucun cas être égale.

“limit_reached”

  • Le compte a atteint sa limite mensuelle de colis privés.

“number_only”

  • La valeur doit être un nombre positif uniquement.

“missing_value”
La valeur est manquante. Champ obligatoire.

“wrong_email”

  • L’adresse e-mail du livreur est incorrecte. Soit elle a été mal orthographiée, soit elle n’a pas été enregistrée et validée dans le compte Shagya.

“wrong_format”

  • Le format n’a pas été respecté.

“wrong_number”

  • Le nombre indiqué est incorrect.

Différentes options de filtre

“date_from”

  • Date Format : “XXXX-XX-XX”
  • Opérateur SQL : “>=”
  • Filtre les livraisons à partir de cette date

“date_to”

  • Date Format : “XXXX-XX-XX”
  • Opérateur SQL : “<=”
  • Filtre les livraisons jusqu’à cette date

“order_uniqid_from”

  • Nombre uniquement
  • Opérateur SQL : “>=”
  • Filtre les livraisons à partir de cet ID unique

“order_uniqid_to”

  • Nombre uniquement
  • Opérateur SQL : “<=”
  • Filtre les livraisons jusqu’à cet ID unique

“client_number”

  • Nombre uniquement
  • Opérateur SQL : “=”
  • Filtre les livraisons ayant ce numéro de client

“deliverer_email”

  • Opérateur SQL : “LIKE %…%”
  • Filtre les livraisons prises en charge par ce livreur

“pack_ref”

  • Opérateur SQL : “LIKE %…%”
  • Filtre les livraisons ayant cette référence

“limit”

  • Nombre uniquement
  • Nombre de résultat maximum à recevoir en JSON

“sort”

  • “desc” ou “asc” uniquement
  • “desc”, du plus récent au plus vieux (valeur par défaut)
  • “asc”, du plus vieux au plus récent

erreurs importantes à éviter !

Dans tous vos JSON passés en POST ou PUT, assurez-vous de bien vérifier que les dernières virgules séparant les variables ou les objets JSON à l’intérieur du tableau soient retirées. Si une telle virgule est détectée, le JSON ne sera pas correctement interprété et entraînera une erreur “Access denied”.

[
  {
    "date_from": "2023-06-01",
    "date_to": "2023-06-30",
    "client_number": "C-102011",
    "deliverer_email": "livreur@gmail.com",
  },
]