API dei Pacchi per Sviluppatori

1. Identificare i corrieri tramite numero di tracciamento (Ricerca)

Una richiesta GET può ottenere un elenco completo di tutti i corrieri supportati dall'API di tracciamento Pacchi dalla Cina. Questo endpoint è utile per determinare quali corrieri sono associati a un numero di tracciamento specifico prima di avviare una richiesta di tracciamento.

Esempio di richiesta


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

Nota:

  • Sostituire {USER_API_SECRET_ACCESS_KEY} con la chiave segreta API unica ottenuta dal cruscotto.
  • Sostituire {TRACKING_NUMBER} con il numero di tracciamento del pacco.

Descrizione dei parametri di risposta

  • error: Codice di errore che indica il risultato della richiesta (vedere i codici di errore di seguito).
  • result: Un array di ID corrieri che corrispondono al numero di tracciamento.

Esempio di risposta


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

In questa risposta:

  • 2 (USPS) e 4 (Royal Mail) sono gli ID corrieri che corrispondono al numero di tracciamento. È possibile visualizzare tutti gli ID corrieri nella sezione API Corrieri. 

Codici di errore

  • -1 - Richiesta riuscita;
  • 0 - Utente non trovato;
  • 1 - Credito insufficiente;

2. Tracciare un pacco tramite numero di tracciamento

Offriamo due metodi per tracciare il pacco: il primo determina automaticamente il corriere utilizzando il nostro algoritmo. In alternativa, è possibile specificare il corriere per tracciare il pacco.

2.1 Esempio di richiesta con rilevamento automatico del corriere


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

Nota:

  • Sostituire {USER_API_SECRET_ACCESS_KEY} con la chiave segreta API unica ottenuta dal cruscotto.
  • Sostituire {TRACKING_NUMBER} con il numero di tracciamento del pacco.

2.2 Esempio di richiesta per ID corriere corrente


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

Nota:

  • Sostituire {USER_API_SECRET_ACCESS_KEY} con la chiave segreta API unica ottenuta dal cruscotto.
  • Sostituire {TRACKING_NUMBER} con il numero di tracciamento del pacco.
  • Sostituire {CARRIER_ID} con l'ID corriere ottenuto dalla sezione API Corrieri o dalla ricerca (sopra).

Descrizione dei parametri di risposta

Oggetto principale della risposta

  • error: Codice di errore che indica il risultato della richiesta (vedere i codici di errore di seguito).
  • result: Oggetto contenente i dati di tracciamento del pacco e le informazioni sul corriere.

Dati di tracciamento (carrier_tracking_data)

Un array di eventi di tracciamento:

  • time: Timestamp dell'evento (formato Unix).
  • info: Descrizione dell'evento.
  • location: Posizione in cui si è verificato l'evento.
  • date: Data e ora dell'evento nel formato YYYY-MM-DD HH:mm:ss.

Dati sul pacco (parcel_other_data)

Dettagli sul pacco:

  • postal_product: Prodotto postale o servizio utilizzato (ad esempio, "Priority Mail Express International").
  • reference_tracking_numbers: Array aggiuntivo di numeri di tracciamento di riferimento, se disponibili.
  • description: Descrizione del pacco fornita dal corriere.
  • recipient: Informazioni sul destinatario, se disponibili.
  • sender: Informazioni sul mittente, se disponibili.
  • scheduled_delivery: Informazioni sulla consegna prevista fornite dal corriere.
  • weight: Peso del pacco.
  • dimensions: Dimensioni del pacco.

Origine e destinazione del pacco

  • parcel_origin_country_code: Codice ISO 3166-1 alpha-2 del paese di origine.
  • parcel_destination_country_code: Codice ISO 3166-1 alpha-2 del paese di destinazione.

Dati del corriere (carrier)

Informazioni sul corriere:

  • carrier_website: Sito ufficiale del corriere.
  • carrier_email: Indirizzo email di contatto del corriere.
  • carrier_phone: Numero di telefono del corriere.
  • carrier_type: Tipo di corriere (ad esempio, "postal", "courier").
  • carrier_support: Indica se il corriere è supportato (1: Sì, 0: No).
  • carrier_country_name: Paese in cui ha sede il corriere.
  • carrier_icon: URL dell'icona del corriere.
  • carrier_icon_width: Larghezza dell'icona del corriere (in pixel).
  • carrier_icon_height: Altezza dell'icona del corriere (in pixel).
  • carrier_thumbnail: URL della miniatura del corriere.
  • carrier_thumbnail_width: Larghezza della miniatura (in pixel).
  • carrier_thumbnail_height: Altezza della miniatura (in pixel).
  • carrier_name: Nome del corriere.
  • carrier_country_code: Codice ISO 3166-1 alpha-2 del paese del corriere.
  • carrier_language_code: Codice lingua utilizzato dal corriere per i dati di tracciamento (ad esempio, "en").

Stime di consegna

  • estimate_delivery_days: Numero stimato di giorni per la consegna.
  • estimate_delivery_date: Data stimata di consegna (YYYY-MM-DD) a partire dalla prima data di tracciamento.

Stato del pacco

  • status: Stato attuale del pacco:
    • 1 - Non trovato;
    • 2 - In transito;
    • 3 - In attesa di ritiro; 
    • 4 - Consegnato;
    • 5 - Avviso;
    • 6 - Non consegnato;
    • 7 - Scaduto.

Esempio di risposta


{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Sdoganamento.",
        "location": "TURCHIA",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Elaborato attraverso l'impianto.",
        "location": "TURCHIA",
        "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": "Descrizione del pacco fornita dal corriere",
      "recipient": "Informazioni sul destinatario",
      "sender": "Informazioni sul mittente",
      "scheduled_delivery": "Informazioni sulla consegna prevista",
      "weight": "Peso del pacco",
      "dimensions": "Dimensioni del pacco"
    },
    "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": "postale",
      "carrier_country_name": "Stati Uniti d'America",
      "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"
  }
}

Codici di errore

  • -1 - Richiesta riuscita;
  • 0 - Utente non trovato;
  • 1 - Credito insufficiente;
  • 3 - Corriere non trovato con questo numero (per rilevamento automatico).