API de Paquetes para Desarrolladores

1. Identificar Transportistas por Número de Seguimiento (Búsqueda)

Una solicitud GET puede obtener una lista completa de todos los transportistas compatibles con la API de seguimiento de Paquetes de China. Este método es útil para determinar qué transportistas están asociados con un número de seguimiento antes de iniciar una solicitud de seguimiento.

Ejemplo de Solicitud


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

Nota:

  • Reemplace {USER_API_SECRET_ACCESS_KEY} con su clave secreta de API desde el panel de control.
  • Reemplace {TRACKING_NUMBER} con el número de seguimiento de su paquete.

Descripción de los Parámetros de Respuesta

  • error: Código de error que indica el resultado de la solicitud (consulte los códigos de error a continuación).
  • result: Una matriz de IDs de transportistas que coinciden con el número de seguimiento.

Ejemplo de Respuesta


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

En esta respuesta:

  • 2 (USPS) y 4 (Royal Mail) son los IDs de transportistas que coinciden con el número de seguimiento. Puede ver todos los IDs de transportistas en la sección API de Transportistas. 

Códigos de Error

  • -1 - Solicitud exitosa;
  • 0 - Usuario no encontrado;
  • 1 - Saldo insuficiente;

2. Rastrear el Paquete por Número de Seguimiento

Para rastrear su paquete, ofrecemos dos métodos: primero, determinamos automáticamente el transportista utilizando nuestro algoritmo. Alternativamente, puede especificar el transportista para rastrear el paquete.

2.1 Ejemplo de Solicitud con Detección Automática de Transportista


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

Nota:

  • Reemplace {USER_API_SECRET_ACCESS_KEY} con su clave secreta de API desde el panel de control.
  • Reemplace {TRACKING_NUMBER} con el número de seguimiento de su paquete.

2.2 Ejemplo de Solicitud para ID de Transportista Actual


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

Nota:

  • Reemplace {USER_API_SECRET_ACCESS_KEY} con su clave secreta de API desde el panel de control.
  • Reemplace {TRACKING_NUMBER} con el número de seguimiento de su paquete.
  • Reemplace {CARRIER_ID} con el ID del transportista desde la sección API de Transportistas o desde la búsqueda (arriba).

Descripción de los Parámetros de Respuesta

Objeto Principal de Respuesta

  • error: Código de error que indica el resultado de la solicitud (consulte los códigos de error a continuación).
  • result: Objeto que contiene datos de seguimiento y datos del transportista.

Datos de Seguimiento (carrier_tracking_data)

Una matriz de eventos de seguimiento:

  • time: Marca de tiempo del evento (formato Unix).
  • info: Descripción del evento.
  • location: Ubicación donde ocurrió el evento.
  • date: Fecha y hora del evento en el formato YYYY-MM-DD HH:mm:ss.

Datos del Paquete (parcel_other_data)

Detalles sobre el paquete:

  • postal_product: El producto postal o servicio utilizado (por ejemplo, "Priority Mail Express International").
  • reference_tracking_numbers: Matriz adicional de números de seguimiento, si está disponible.
  • description: Una descripción del paquete proporcionada por el transportista.
  • recipient: Información del destinatario, si está disponible.
  • sender: Información del remitente, si está disponible.
  • scheduled_delivery: Información estimada de entrega del transportista.
  • weight: Peso del paquete.
  • dimensions: Dimensiones del paquete.

Datos de Origen y Destino del Paquete

  • parcel_origin_country_code: Código ISO 3166-1 alpha-2 del país de origen.
  • parcel_destination_country_code: Código ISO 3166-1 alpha-2 del país de destino.

Datos del Transportista (carrier)

Información sobre el transportista:

  • carrier_website: Sitio web oficial del transportista.
  • carrier_email: Correo electrónico de contacto del transportista.
  • carrier_phone: Número de teléfono del transportista.
  • carrier_type: Tipo de transportista (por ejemplo, "postal", "courier").
  • carrier_support: Indica si el transportista está soportado (1: Sí, 0: No).
  • carrier_country_name: País donde está basado el transportista.
  • carrier_icon: URL al icono del transportista.
  • carrier_icon_width: Ancho del icono del transportista (en píxeles).
  • carrier_icon_height: Altura del icono del transportista (en píxeles).
  • carrier_thumbnail: URL a la miniatura del transportista.
  • carrier_thumbnail_width: Ancho de la miniatura (en píxeles).
  • carrier_thumbnail_height: Altura de la miniatura (en píxeles).
  • carrier_name: Nombre del transportista.
  • carrier_country_code: Código ISO 3166-1 alpha-2 del país del transportista.
  • carrier_language_code: Código del idioma que el transportista usa para datos de seguimiento (por ejemplo, "en").

Estimaciones de Entrega

  • estimate_delivery_days: Número estimado de días hasta la entrega.
  • estimate_delivery_date: Fecha estimada de entrega (YYYY-MM-DD) desde la primera fecha de seguimiento.

Estado del Paquete

  • status: Estado actual del paquete:
    • 1 - No Encontrado;
    • 2 - En Tránsito;
    • 3 - Para Recoger; 
    • 4 - Entregado;
    • 5 - Alerta;
    • 6 - No Entregado;
    • 7 - Expirado.

Ejemplo de Respuesta


{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Despacho de aduanas.",
        "location": "TURQUÍA",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Procesado a través de la instalación.",
        "location": "TURQUÍA",
        "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": "Descripción del paquete del transportista",
      "recipient": "Información del destinatario",
      "sender": "Información del remitente",
      "scheduled_delivery": "Información de entrega programada",
      "weight": "Peso del paquete",
      "dimensions": "Dimensiones del paquete"
    },
    "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": "Estados Unidos de América",
      "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"
  }
}

Códigos de Error

  • -1 - Solicitud exitosa;
  • 0 - Usuario no encontrado;
  • 1 - Saldo insuficiente;
  • 3 - Transportista no encontrado por este número (para Detección Automática de Transportista);