API de Pacotes para Desenvolvedores

1. Identificar transportadoras pelo número de rastreamento (Pesquisa)

Uma solicitação GET pode obter uma lista completa de todas as transportadoras suportadas pela API de rastreamento Pacotes da China. Esse endpoint é útil para determinar quais transportadoras estão associadas a um número de rastreamento específico antes de iniciar uma solicitação de rastreamento.

Exemplo de Solicitação


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

Nota:

  • Substitua {USER_API_SECRET_ACCESS_KEY} pela sua chave de acesso secreta da API, obtida no painel de controle.
  • Substitua {TRACKING_NUMBER} pelo número de rastreamento do seu pacote.

Descrição dos Parâmetros de Resposta

  • error: Código de erro indicando o resultado da solicitação (veja os códigos de erro abaixo).
  • result: Um array de IDs de transportadoras que correspondem ao número de rastreamento.

Exemplo de Resposta


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

Nesta resposta:

  • 2 (USPS) e 4 (Royal Mail) são os IDs das transportadoras que correspondem ao número de rastreamento. Você pode visualizar todos os IDs das transportadoras na seção API de Transportadoras. 

Códigos de Erro

  • -1 - Solicitação bem-sucedida;
  • 0 - Usuário não encontrado;
  • 1 - Saldo insuficiente;

2. Rastrear o Pacote pelo Número de Rastreamento

Oferecemos dois métodos para rastrear o seu pacote: primeiro, determinamos automaticamente a transportadora usando nosso algoritmo. Alternativamente, você pode especificar a transportadora para rastrear o pacote.

2.1 Exemplo de Solicitação com Detecção Automática de Transportadora


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

Nota:

  • Substitua {USER_API_SECRET_ACCESS_KEY} pela sua chave de acesso secreta da API, obtida no painel de controle.
  • Substitua {TRACKING_NUMBER} pelo número de rastreamento do seu pacote.

2.2 Exemplo de Solicitação para ID da Transportadora Atual


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

Nota:

  • Substitua {USER_API_SECRET_ACCESS_KEY} pela sua chave de acesso secreta da API, obtida no painel de controle.
  • Substitua {TRACKING_NUMBER} pelo número de rastreamento do seu pacote.
  • Substitua {CARRIER_ID} pelo ID da transportadora obtido na seção API de Transportadoras ou na Pesquisa (acima).

Descrição dos Parâmetros de Resposta

Objeto Principal da Resposta

  • error: Código de erro indicando o resultado da solicitação (veja os códigos de erro abaixo).
  • result: Objeto contendo dados de rastreamento do pacote e informações sobre a transportadora.

Dados de Rastreamento (carrier_tracking_data)

Um array de eventos de rastreamento:

  • time: Carimbo de data/hora do evento (formato Unix).
  • info: Descrição do evento.
  • location: Local onde o evento ocorreu.
  • date: Data e hora do evento no formato YYYY-MM-DD HH:mm:ss.

Dados do Pacote (parcel_other_data)

Detalhes sobre o pacote:

  • postal_product: Produto ou serviço postal utilizado (por exemplo, "Priority Mail Express International").
  • reference_tracking_numbers: Array adicional de números de rastreamento de referência, se disponíveis.
  • description: Descrição do pacote fornecida pela transportadora.
  • recipient: Informações do destinatário, se disponíveis.
  • sender: Informações do remetente, se disponíveis.
  • scheduled_delivery: Informações sobre a entrega prevista fornecidas pela transportadora.
  • weight: Peso do pacote.
  • dimensions: Dimensões do pacote.

Origem e Destino do Pacote

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

Informações da Transportadora (carrier)

Detalhes sobre a transportadora:

  • carrier_website: Site oficial da transportadora.
  • carrier_email: E-mail de contato da transportadora.
  • carrier_phone: Número de telefone de contato da transportadora.
  • carrier_type: Tipo de transportadora (por exemplo, "postal", "courier").
  • carrier_support: Indica se a transportadora é suportada (1: Sim, 0: Não).
  • carrier_country_name: País onde a transportadora está localizada.
  • carrier_icon: URL do ícone da transportadora.
  • carrier_icon_width: Largura do ícone da transportadora (em pixels).
  • carrier_icon_height: Altura do ícone da transportadora (em pixels).
  • carrier_thumbnail: URL da miniatura da transportadora.
  • carrier_thumbnail_width: Largura da miniatura (em pixels).
  • carrier_thumbnail_height: Altura da miniatura (em pixels).
  • carrier_name: Nome da transportadora.
  • carrier_country_code: Código ISO 3166-1 alpha-2 do país da transportadora.
  • carrier_language_code: Código de idioma usado pela transportadora para os dados de rastreamento (por exemplo, "en").

Estimativas de Entrega

  • estimate_delivery_days: Número estimado de dias para a entrega.
  • estimate_delivery_date: Data estimada de entrega (YYYY-MM-DD) a partir da primeira data de rastreamento.

Status do Pacote

  • status: Status atual do pacote:
    • 1 - Não encontrado;
    • 2 - Em trânsito;
    • 3 - Aguardando retirada; 
    • 4 - Entregue;
    • 5 - Alerta;
    • 6 - Não entregue;
    • 7 - Expirado.

Exemplo de Resposta


{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Desembaraço aduaneiro.",
        "location": "TURQUIA",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Processado através da instalação.",
        "location": "TURQUIA",
        "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": "Descrição do pacote fornecida pela transportadora",
      "recipient": "Informações do destinatário",
      "sender": "Informações do remetente",
      "scheduled_delivery": "Informações de entrega previstas",
      "weight": "Peso do pacote",
      "dimensions": "Dimensões do pacote"
    },
    "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",
      "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 Erro

  • -1 - Solicitação bem-sucedida;
  • 0 - Usuário não encontrado;
  • 1 - Saldo insuficiente;
  • 3 - Transportadora não encontrada com este número (para detecção automática).