API des Colis pour les Développeurs

1. Identifier les transporteurs par numéro de suivi (Recherche)

Une requête GET peut obtenir une liste complète de tous les transporteurs pris en charge par l’API de suivi Colis de Chine. Ce point de terminaison est utile pour déterminer quels transporteurs sont associés à un numéro de suivi spécifique avant d’initier une requête de suivi.

Exemple de requête


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/lookup"

Remarque :

  • Remplacez {USER_API_SECRET_ACCESS_KEY} par votre clé secrète API unique obtenue dans le tableau de bord.
  • Remplacez {TRACKING_NUMBER} par votre numéro de suivi.

Description des paramètres de réponse

  • error : Code d’erreur indiquant le résultat de la requête (voir les codes d’erreur ci-dessous).
  • result : Un tableau des identifiants des transporteurs correspondant au numéro de suivi.

Exemple de réponse


{
  "error": -1,
  "result": ["2", "4"]
}

Dans cette réponse :

  • 2 (USPS) et 4 (Royal Mail) sont les identifiants des transporteurs correspondant au numéro de suivi. Vous pouvez consulter tous les identifiants des transporteurs dans la section API des transporteurs. 

Codes d’erreur

  • -1 - Requête réussie ;
  • 0 - Utilisateur introuvable ;
  • 1 - Solde insuffisant ;

2. Suivre un colis par numéro de suivi

Nous proposons deux méthodes pour suivre votre colis : d’abord, nous déterminons automatiquement le transporteur à l’aide de notre algorithme. Vous pouvez également spécifier le transporteur pour suivre le colis.

2.1 Exemple de requête avec détection automatique du transporteur


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track"

Remarque :

  • Remplacez {USER_API_SECRET_ACCESS_KEY} par votre clé secrète API unique obtenue dans le tableau de bord.
  • Remplacez {TRACKING_NUMBER} par votre numéro de suivi.

2.2 Exemple de requête pour un identifiant de transporteur spécifique


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track/{CARRIER_ID}"

Remarque :

  • Remplacez {USER_API_SECRET_ACCESS_KEY} par votre clé secrète API unique obtenue dans le tableau de bord.
  • Remplacez {TRACKING_NUMBER} par votre numéro de suivi.
  • Remplacez {CARRIER_ID} par l’identifiant du transporteur obtenu dans la section API des transporteurs ou par la recherche (ci-dessus).

Description des paramètres de réponse

Objet principal de réponse

  • error : Code d’erreur indiquant le résultat de la requête (voir les codes d’erreur ci-dessous).
  • result : Objet contenant les données de suivi et les informations sur le transporteur.

Données de suivi (carrier_tracking_data)

Un tableau des événements de suivi :

  • time : Horodatage de l’événement (format Unix).
  • info : Description de l’événement.
  • location : Lieu où l’événement s’est produit.
  • date : Date et heure de l’événement au format YYYY-MM-DD HH:mm:ss.

Données sur le colis (parcel_other_data)

Détails sur le colis :

  • postal_product : Produit ou service postal utilisé (par exemple, "Priority Mail Express International").
  • reference_tracking_numbers : Tableau supplémentaire des numéros de suivi de référence, si disponible.
  • description : Description du colis fournie par le transporteur.
  • recipient : Informations sur le destinataire, si disponibles.
  • sender : Informations sur l’expéditeur, si disponibles.
  • scheduled_delivery : Informations sur la livraison prévue par le transporteur.
  • weight : Poids du colis.
  • dimensions : Dimensions du colis.

Origine et destination du colis

  • parcel_origin_country_code : Code pays ISO 3166-1 alpha-2 du pays d’origine.
  • parcel_destination_country_code : Code pays ISO 3166-1 alpha-2 du pays de destination.

Informations sur le transporteur (carrier)

Données sur le transporteur :

  • carrier_website : Site officiel du transporteur.
  • carrier_email : Adresse e-mail de contact du transporteur.
  • carrier_phone : Numéro de téléphone du transporteur.
  • carrier_type : Type de transporteur (par exemple, "postal", "courier").
  • carrier_support : Indique si le transporteur est pris en charge (1 : Oui, 0 : Non).
  • carrier_country_name : Pays où le transporteur est basé.
  • carrier_icon : URL de l’icône du transporteur.
  • carrier_icon_width : Largeur de l’icône du transporteur (en pixels).
  • carrier_icon_height : Hauteur de l’icône du transporteur (en pixels).
  • carrier_thumbnail : URL de la miniature du transporteur.
  • carrier_thumbnail_width : Largeur de la miniature (en pixels).
  • carrier_thumbnail_height : Hauteur de la miniature (en pixels).
  • carrier_name : Nom du transporteur.
  • carrier_country_code : Code pays ISO 3166-1 alpha-2 du transporteur.
  • carrier_language_code : Code langue utilisé par le transporteur pour les données de suivi (par exemple, "en").

Estimations de livraison

  • estimate_delivery_days : Nombre estimé de jours avant livraison.
  • estimate_delivery_date : Date estimée de livraison (YYYY-MM-DD) à partir de la première date de suivi.

Statut du colis

  • status : Statut actuel du colis :
    • 1 - Non trouvé ;
    • 2 - En transit ;
    • 3 - À récupérer; 
    • 4 - Livré ;
    • 5 - Alerte ;
    • 6 - Non livré ;
    • 7 - Expiré.

Exemple de réponse


{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Dédouanement.",
        "location": "TURQUIE",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Traitement terminé par l'installation.",
        "location": "TURQUIE",
        "date": "2024-12-04 11:50:00"
      }
    ],


    "parcel_other_data": {
      "postal_product": "Priority Mail Express International",
      "reference_tracking_numbers": [
        "REF_NUMBER_01",
        "REF_NUMBER_02"
      ],
      "description": "Description du colis par le transporteur",
      "recipient": "Informations sur le destinataire",
      "sender": "Informations sur l'expéditeur",
      "scheduled_delivery": "Informations sur la livraison prévue",
      "weight": "Poids du colis",
      "dimensions": "Dimensions du colis"
    },
    "parcel_origin_country_code": "us",
    "parcel_destination_country_code": "tr",
    "status": 2,
    "carrier": {
      "carrier_website": "https://www.usps.com",
      "carrier_email": "support@usps.com",
      "carrier_phone": "1-800-222-1811",
      "carrier_type": "postal",
      "carrier_country_name": "États-Unis",
      "carrier_name": "USPS",


      "carrier_icon": "http://developers.chinaparcels.com/cdn/images/carriers/icons/0002-usps.png",
      "carrier_icon_width": 256,
      "carrier_icon_height": 256,
      "carrier_thumbnail": "http://developers.chinaparcels.com/cdn/images/carriers/thumbnails/0002-usps.png",
      "carrier_thumbnail_width": 640,
      "carrier_thumbnail_height": 256,
      "carrier_country_code": "us",
      "carrier_language_code": "en"
    },
    "estimate_delivery_days": 16,
    "estimate_delivery_date": "2024-12-13"
  }
}

Codes d’erreur

  • -1 - Requête réussie ;
  • 0 - Utilisateur introuvable ;
  • 1 - Solde insuffisant ;
  • 3 - Transporteur introuvable avec ce numéro (pour la détection automatique de transporteur).