Primeiros passos

AliExpress Open Platform

AliExpress Open Platform é uma plataforma de desenvolvimento de aplicativos para o AliExpress. A plataforma fornece uma série de APIs e serviços para ajudar os desenvolvedores a criar aplicativos para o AliExpress. A plataforma também fornece uma série de ferramentas para ajudar os desenvolvedores a gerenciar seus aplicativos.

Sobre este documento

Este documento fornece uma visão geral da plataforma para desenvolvedores brasileiros. Para obter mais informações sobre as APIs e serviços, consulte a documentação da API.

Cadastro de conta de desenvolvedor

Você pode se registrar como ISV ou autodesenvolvedor aqui.

Approvação de conta de desenvolvedor

Após o registro, você pode entrar na plataforma e verificar o status da sua conta.

Criação de aplicativo

Após o registro, você pode criar um aplicativo clicando em "Create" na página App Console.

Gerenciamento de aplicativo

Após a criação do aplicativo, você pode gerenciar o aplicativo clicando em "Manage" na página App Console.

• appKey e appSecret são necessários para a autenticação de API. Você pode encontrar essas informações na "App Overview".
• SDKs estão disponíveis na página "SDK Download".
• Configuração do webhook está disponível na página "Notification service(webhook)".
• Para garantir a segurança dos dados, você pode usar a IP whitelist para restringir o acesso às APIs. Você pode encontrar a IP whitelist na página "IP Whitelist".
• Para monitorar a integridade da integração da API, você pode usar a página "API Access Log".

Approvação de aplicativo

Por padrão, o aplicativo criado está no modo de teste. Neste mode, você pode usar a API para testar seu aplicativo. Existem algumas limitações no modo de teste:

1. número limitado de lojas autorizadas.
2. número limitado de chamadas de API.
3. tokens de acesso expiram em 24 horas.

Para usar o aplicativo em produção, você deve enviar uma solicitação de aprovação.

API calls

Ambiente de produção

Sempre siga este padrão ao fazer solicitações de API, api_path deve sempre ser um parâmetro do sistema:

https://api-sg.aliexpress.com/sync?method={api_path}&{query}

Para simplificar, é recomendado sempre fazer solicitações POST com system parameters em URL e business parameters em corpo de solicitação.

Por exemplo:

URL: https://api-sg.aliexpress.com/sync?app_key=123456&format=json&method=aliexpress.logistics.redefining.getonlinelogisticsservicelistbyorderid&session=50000**********************************&sign=E7E3F**********************&sign_method=sha256&simplify=true&timestamp=1681223300803

Body: order_id=3022167240092096

System parameters

Os parâmetros listados abaixo são comuns a todos os métodos da API. Para maior clareza do documento, eles não são mostrados nos exemplos de solicitação.

Business parameters

Além dos parâmetros do sistema que devem ser incluídos na solicitação de chamada de API, os business parameters específicos do método também devem ser incluídos.

Cálculo de Assinatura

Todas as solicitações de chamada de API devem ser assinadas para garantir a segurança da comunicação. A assinatura é calculada com base nos parâmetros de solicitação e na chave de aplicativo. Solicitações de chamada de API sem assinatura não serão processadas.

Selecionar os parâmetros

{
  "app_key": "33006842",
  "simplify": true,
  "format": "json",
  "timestamp": 1675534526072,
  "sign_method": "sha256",
  "method": "/auth/token/create",
  "code": "3_33006842_SZ1H8Oz9cEDw61nU1eitmABF7383"
}

• Selecionar todos os parâmetros de solicitação, incluindo os System parameters e os Business parameters.
• Excluir o parâmetro sign e parâmetros de tipo de arquivo byte[] por exemplo, imagens do produtos, XML de nota fiscal, etc.).
• Incluir o parâmetro method no método migrado.

Ordenar os parâmetros

Ordene os parâmetros selecionados em ordem alfabética pelo nome do parâmetro.

Concatenar os parâmetros

concatenated_string=app_key33006842code3_33006842_SZ1H8Oz9cEDw61nU1eitmABF7383formatjsonmethod/auth/token/createsign_methodsha256simplifytruetimestamp1675534526072

Concatenar os nome e valor dos parâmetros ordenados sem nenhum separador. Prefixar o valor do method no início no método novo.

Codificar o string concatenado

UTF-8

Calcular a assinatura

assume_that_app_secret=fb750490a63ee2218bf82a4f0c01a25f
sign=73D4F0A06612F6023A62543067466A0D62B5EF9F77DC4F48D083ED21D1E8614A

• Applicar o algoritmo de hash sha256 no string codificado.
• Converter o resultado do hash em hexadecimal e converter para maiúsculo.

Enviar a solicitação

Enviar a solicitação HTTP com o método POST ou GET.

mais detalhes

Usar API com SDK

Você pode baixar o SDK do seu App Console e simplificar o uso da API. O SDK pode lidar com System parameters e a assinatura automaticamente.

Autenticação e Autorização

Você precisa ser autorizado pelo vendedor para que seu app se comunique com as APIs não públicas.

O processo de autorização é dividido em os seguintes passos:

Gerar o link de autorização

Você deve gerar um link de autorização para o vendedor com as seguintes especificações:

https://api-sg.aliexpress.com/oauth/authorize?response_type=code&force_auth=true&redirect_url=${redirect_url}&client_id=${client_id}

Guiar o vendedor a autorizar seu app

Guiar o vendedor abrir o link de autorização gerado no passo anterior. O vendedor será redirecionado para a página de login do AliExpress. O vendedor deve fazer login e autorizar seu app.

Obter o code

Após o vendedor autorizar seu app, o vendedor será redirecionado para a URL redirect_url configurada acima. O code será retornado na URL de redirecionamento. Se o state ou uuid foi configurado, eles serão retornados na URL de redirecionamento.

Obter o token de acesso

Você deve usar o code obtido no passo anterior para obter o token de acesso.

Method

/auth/token/create

Business parameters

{
  "code": "3_33006842_SZ1H8Oz9cEDw61nU1eitmABF7383"
}

Resposta

{
  "refresh_token_valid_time": 1738263120048,
  "havana_id": "id-in-string-format",
  "expire_time": 1706727119024,
  "locale": "zh_CN",
  "user_nick": "br####",
  "access_token": "a-long-access-token",
  "refresh_token": "a-long-refresh-token",
  "user_id": "user-id",
  "account_platform": "seller_center",
  "refresh_expires_in": 63072002,
  "expires_in": 31536001,
  "sp": "ae",
  "seller_id": "seller-id",
  "account": "seller-email",
  "request_id": "2102fd2216751911180912262"
}

Pelo menos os seguintes parâmetros devem ser salvos para uso futuro:

• access_token para autenticação nas APIs.
• refresh_token para obter um novo access_token quando o access_token expirar.
• seller_id, user_nick para identificar o vendedor.

Também é recomendado monitorar o valor de expires_in, refresh_token_valid_time e refresh_expires_in. Esses prazos de expiração podem estar sujeitos a alterações.

Atualizar o token de acesso

Quando o access_token expirar, você deve usar o refresh_token para obter um novo access_token. É recomendado que você atualize o access_token 30 minutos antes de expirar. O processo pode ser feito sem a intervenção do vendedor.

Method

/auth/token/refresh

Business parameters

{
  "refresh_token": "a-long-refresh-token"
}

Resposta

{
  "refresh_token_valid_time": 1738263120048,
  "havana_id": "id-in-string-format",
  "expire_time": 1706727119024,
  "locale": "zh_CN",
  "user_nick": "br####",
  "access_token": "a-long-access-token",
  "refresh_token": "a-long-refresh-token",
  "user_id": "user-id",
  "account_platform": "seller_center",
  "refresh_expires_in": 63072002,
  "expires_in": 31536001,
  "sp": "ae",
  "seller_id": "seller-id",
  "account": "seller-email",
  "request_id": "2102fd2216751911180912262"
}

Guia para produtos

Configurações antes de publicar um produto

As seguintes condições devem ser atendidas para que um produto seja publicado no AliExpress:

1. Aplicado e concedido permisão para categorias e marcas.
2. Configurado templates de serviço.
3. Configurado templates de envio.
4. Configurado templates de medida.

Escolher uma categoria

Os categorias do AliExpress são organizados em uma hierarquia. Você deve escolher uma categoria que seja apropriada para o seu produto. Você pode baixar a lista de categorias usando o seguinte endpoint recursivamente:

aliexpress.category.redefining.getchildrenpostcategorybyid

O ID da raiz da categoria é 0.

Uma categoria de leaf é uma categoria que não tem subcategorias. Produtos só podem ser publicados em categorias de leaf.

Propriedades para produtos

Com categorias selecionadas, você pode obter as propriedades para produtos usando o seguinte endpoint:

aliexpress.category.redefining.getchildattributesresultbypostcateidandpath

Uma lista de propriedades para produtos é retornada. Cada propriedade vem com uma especificacão:

{
  "spec": 2,
  "required": false,
  "keyAttribute": false,
  "sku": false,
  "id": 196,
  "values": [
    {
      "id": 134,
      "names": {
        "zh": "交流",
        "en": "AC"
      }
    }
  ],
  "names": {
    "zh": "输出类型",
    "en": "Output Type"
  },
  "inputType": "STRING",
  "attributeShowTypeValue": "list_box"
}

• required: Se a propriedade é obrigatória.
• sku: Se a propriedade é usada para gerar SKU.
  • Propriedade de SKU é usada para gerar SKU.
  • Propriedade commum é usada para informar o comprador.

Propriedade de SKU

Cada produto pode ter múltiplas variações(SKU). Cada variação é uma combinação de valores de propriedades de SKU. Por exemplo, uma camisa pode ter as seguintes propriedades de SKU:

1. Cor: Vermelho, Azul, Amarelo
2. Tamanho: M, L, XL, XXL

Então, a camisa terá 3x4 = 12 variações.

Para cade variação, a ordem dos valores de propriedades de SKU deve siguir a ordem das spec de propriedades de SKU. Por example, para categoria de id 348, a ordem das propriedades de SKU é 14, 5, 200007763.

[
  {
    "id": 5,
    "names": {
      "zh": "尺寸",
      "en": "Size"
    },
    "sku": true,
    "spec": 2
  },
  {
    "id": 14,
    "names": {
      "zh": "颜色",
      "en": "Color"
    },
    "sku": true,
    "spec": 1
  },
  {
    "id": 200007763,
    "names": {
      "zh": "发货地",
      "en": "Ships From"
    },
    "sku": true,
    "spec": 3
  }
]

Cada propriedade de SKU tem 4 campos

Propriedades comuns

Propriedades comuns são usadas para informar o comprador. Há duas tipos de propriedades comuns:

1. Propriedades definidas pela categoria.
2. Propriedades definidas pelo vendedor.

Para propriedades definidas pela categoria, o seguinte tabela mostra os campos:

Para propriedades definidas pelo vendedor, o seguinte tabela mostra os campos:

Fotos do produto

Você pode enviar imagens para o produto usando o seguinte endpoint:

aliexpress.image.redefining.uploadtempimageforsdk

Descricao PC e Mobile

Você pode enviar a descrição do produto de versão PC e Mobile.

A descrição é um moduleList e você pode seguir o Original data format of detail para mais detalhes.

Modelo de frete

Você pode obter o modelos de frete usando o seguinte endpoint:

aliexpress.freight.redefining.listfreighttemplate

Parâmetros

Sem parâmetros.

Retorno

{
  "result_success": true,
  "aeop_freight_template_d_t_o_list": [
    {
      "template_name": "Alpha-Nomeado pelo vendedor",
      "template_id": 12345678901,
      "is_default": false
    },
    {
      "template_name": "Prod-Nomeado pelo vendedor",
      "template_id": 12345678902,
      "is_default": false
    }
  ]
}

Os modelos de frete são usados para relacionar os produtos com os métodos de frete. Eles também definem descontos de frete e regras de frete grátis.

Os modelos de frete devem ser configurados no painel do AliExpress antes de serem usados. Se a lista de modelos de frete estiver vazia, você deve informar o vendendor para configurar os modelos de frete. guia para configurar modelos de frete

Se mais de um modelo de frete estiver disponível, você deve dexar o vendedor escolher o modelo de frete quando publicar o produto.

Certificado ANATEL

De acordo com a regulamentação brasileira, certos produtos eletrônicos devem ter um certificado da ANATEL. A partir de 31 de agosto de 2024, os produtos de certas categorias sem o número do certificado da ANATEL vai ser penalizado.

Categorias que precisam do número do certificado da ANATEL

Os categorias que precisam do número do certificado da ANATEL estão listadas pelo esse artigo: AliExpress announcement regarding products subject to ANATEL certification

Também é possível verificar se um produto precisa do número do certificado da ANATEL usando o seguinte endpoint com category_id:

GET aliexpress.category.qualifications.list

{
  "aliexpress_category_qualifications_list_response": {
    "support": true,
    "qualification_module_list": {
      "qualification_module": [
        {
          "label": "Certificado ANATEL",
          "type": "image",
          "key": "item_anatel_certificate",
          "tips": "Faça o upload do certificado de certificação ANATEL brasileiro ou uma imagem clara da captura de tela do site oficial, o tamanho deve estar dentro de 3M",
          "required": false
        },
        {
          "label": "ANATEL Certificate_Number",
          "type": "text",
          "key": "ANATEL_Certificate_Number",
          "tips": "",
          "required": false
        },
        ...
      ]
    },
    "request_id": "21014bee17223693878538411"
  }
}

Por exemplo, para a categoria de id 5090301(celulares), existe um campo ANATEL_Certificate_Number que é um número de certificado da ANATEL.

Atualizar o número do certificado da ANATEL

Para atulizar o número do certificado da ANATEL, você pode usar os endpoints do produtos pelo campo item_qualifications. Um dos endpoints é aliexpress.solution.product.post

{
  "post_product_request": {
    ...
    "item_qualifications":
    [
      {
        "key": "ANATEL_Certificate_Number",
        "type": "text",
        "value": "1234567890"
      }
    ]
    ...
  }
}

O campo item_qualifications é um lista de objetos com os seguintes campos:

Criar um produto

Você pode criar um produto usando o seguinte endpoint:

aliexpress.solution.product.post

Status do produto

O produto pode ter os seguintes status:

Guia para pedidos

Esta guia tem como objetivo auxiliar na sincronização de pedidos do AliExpress para o seu sistema.

Endpoints para sincronização de pedidos

• aliexpress.trade.redefining.findorderlistsimplequery para obter uma lista de pedidos.
• aliexpress.trade.new.redefining.findorderbyid para obter detalhes de um pedido.

Initializar o processo de sincronização

Para cada novo vendedor autorizado, você deve inicializar o processo de sincronização de pedidos.

Sincronização incremental pelo API

Para sincronizar os pedidos incrementalmente, você deve obtendo a lista de pedidos usando o endpoint aliexpress.trade.redefining.findorderlistsimplequery repentinamente, e então obter detalhes de cada pedido usando o endpoint aliexpress.trade.new.redefining.findorderbyid.

Esta solução não é a ideal para grande volume de pedidos, o seguinte mecanismo de sincronização incremental é recomendado:

Sincronização incremental pelo Webhook

O AliExpress oferece um mecanismo de sincronização incremental por Webhook. Para utilizar este mecanismo, você deve configurar um webhook no painel do AliExpress.

Estrutura do webhook

{
  "havana_id": "123456789012",
  "seller_id": "1234567890",
  "message_type": 12,
  "data": {
    "msg_tag": "OrderConfirmed",
    "login_id": "br1234567890abcd",
    "order_status": "FINISH",
    "status_update_time_millis": 1684842846000,
    "pay_status": "PAID",
    "trade_order_id": "1234567890123456",
    "extraParams": {},
    "status_update_time": "2023-05-23 04:54:06"
  },
  "timestamp": 1684842846,
  "site":"ae_global"
}

O corpo do webhook é um JSON com os seguintes campos:

O message_type indica o tipo de mensagem, você pode encontrar uma lista completa de tipos de mensagem na documentação oficial.

O header do webhook contém o Authorization. Por segurança, você deve verificar se o Authorization é válido.

Status de pedidos

documentação oficial

Motivo do fim do pedido

documentação oficial

endReason é um campo que indica o motivo do fim do child order.

Pedido encerrado com sucesso

Pedido encerrado com falha

Os seguintes são alguns dos motivos de falha de um pedido, para uma lista mais completa, consulte a documentação oficial.

Códigos de serviço logístico

Guia para logística

A AliExpress Brasil oferece soluções logísticas integradas para vendedores locais, com tarifa fixa pré-paga (Flat-Rate Strategic) e diferentes coberturas geográficas. As opções disponíveis atualmente via API são:

• J&T (BR local Standard Delivery — J&T-Commercial) — somente para vendedores com origem no Estado de São Paulo.
• Sislogica Correios (BR local Standard Delivery — Sislogica-Correios) — cobertura Brasil todo.

Ambas são soluções de modelo pré-pago: para imprimir etiquetas o vendedor precisa recarregar saldo no portal do provedor logístico (J&T VIP ou Sislogica). Nas duas soluções, a emissão da NF-e para o pedido / parcela é obrigatória.

Os vendedores associam cada produto a uma solução logística através do modelo de envio. Ao criar uma ordem de envio, a solução logística é selecionada automaticamente conforme o modelo de envio configurado.

Pré-requisito de logística para lojas

Para utilizar a API de logística, a loja deve cumprir os seguintes requisitos:

1. Possuir um endereço de remetente válido cadastrado no painel.
2. Aderir ao serviço logístico desejado (J&T ou Sislogica Correios) no painel do AliExpress, em Logística → Logistics Service / Serviços de Logística, clicando em Join Now / Participe imediatamente no card correspondente e aceitando o termo de adesão.
   • Vendedores que já possuem conta no provedor logístico podem usar a opção Número conta existente para vincular a conta diretamente.
3. Aguardar o e-mail com login, senha e instruções enviado pelo provedor logístico após a adesão (ex.: J&T.AEsellers@jtexpress.com.br para J&T). Para a J&T é obrigatório responder ao primeiro e-mail informando nome da empresa, Inscrição Estadual (IE) e telefone de contato para liberar o pré-pagamento.
4. Criar um modelo de envio em Logística → Modelos de Envio → Criar um novo modelo de envio, selecionando a opção correspondente (J&T-Commercial ou Sislogica-Correios — All Brazil* Flat-Rate Strategic).
5. Recarregar o saldo pré-pago no portal do provedor antes de gerar etiquetas (J&T VIP: https://vip.jtjms-br.com/; Sislogica via canal de suporte do provedor).

Canais de suporte:

• Abrir chamado (Help Center)
• FAQ — Perguntas Frequentes
• Canal oficial do YouTube
• E-mail de suporte: vendas@aliexpress.com

Fluxo de envio (visão geral)

O fluxo recomendado usa os endpoints ASF na ordem abaixo. Aplica-se à logística da plataforma (J&T / Sislogica, com coleta pelo 4PL da Cainiao):

1. Consultar endereço de coleta — aliexpress.asf.seller.address.get
2. (Quando necessário) Obter endereço do comprador — aliexpress.trade.new.redefining.findorderbyid (campo receipt_address)
3. Carregar a NF-e (obrigatório, antes de empacotar) — /brazil/local/invoice/upload
4. (Opcional) Consultar serviços disponíveis — aliexpress.asf.package.shipping.service.get / aliexpress.asf.order.shipping.service.get
5. Empacotar e obter o fulfillmentPackageId — aliexpress.asf.local2local.split.quantity.rts.pack
6. Consultar o pacote / número de rastreamento — aliexpress.asf.fulfillment.package.query
7. Declarar o envio (RTS) — aliexpress.asf.platform.logistics.rts
8. Imprimir a etiqueta — aliexpress.asf.platform.logistics.document.query
9. Cancelar / reempacotar, se necessário — aliexpress.asf.platform.logistics.repack

Obter endereços de vendedores — aliexpress.asf.seller.address.get

Esta etapa obtém os addressId dos vendedores. No empacotamento (rts.pack), o addressId do endereço de coleta (pickup) é usado no campo addressId, e o addressId do endereço de devolução (refund) é usado no campo refundAddressId.

aliexpress.asf.seller.address.get

{
  "addressType": "pickup,refund",
  "locale": "pt_BR"
}

Os endereços vêm em listas separadas por tipo (senderSellerAddressList, pickupSellerAddressList, refundSellerAddressList):

{
  "result": {
    "data": {
      "pickupSellerAddressList": [
        {
          "addressId": 3000000000001,
          "memberType": "pickup",
          "name": "test",
          "street": "Rua Exemplo",
          "streetAddress": "Sala 100",
          "area": "Bairro Exemplo",
          "city": "Sao Paulo",
          "province": "Sao Paulo",
          "postCode": "00000-000",
          "country": "Brazil",
          "defaultAddress": true
        }
      ],
      "refundSellerAddressList": [
        {
          "addressId": 3000000000002,
          "memberType": "refund",
          "name": "teste",
          "streetAddress": "Rua Exemplo, 100, Sala 100",
          "city": "Sao Paulo",
          "province": "Sao Paulo",
          "postCode": "00000-000",
          "country": "Brazil",
          "defaultAddress": true
        }
      ]
    },
    "success": true
  }
}

Obter o endereço do comprador

Por política de privacidade, o endereço do comprador pode vir mascarado. O endereço completo, com o CPF do destinatário (necessário para a NF-e), está no campo receipt_address da resposta do endpoint de detalhe do pedido aliexpress.trade.new.redefining.findorderbyid.

aliexpress.trade.new.redefining.findorderbyid

{
  "param1": {
    "order_id": "1234567890654321"
  }
}

Resposta, no campo receipt_address:

{
  "receipt_address": {
    "contact_person": "Nome do Comprador",
    "cpf_no": "00000000000",
    "detail_address": "Bairro;Rua Exemplo;123",
    "address2": "Apto 100",
    "city": "Cidade Exemplo",
    "province": "Estado Exemplo",
    "zip": "00000-000",
    "country": "BR",
    "mobile_no": "11999998888",
    "phone_country": "+55"
  }
}

Carregar NF-e para pedidos

Esta etapa é obrigatória para as soluções logísticas atuais (J&T e Sislogica Correios) — a NF-e do pedido / parcela deve ser carregada antes de empacotar o pedido. A plataforma valida o conteúdo da NF-e (é necessário o CPF do destinatário e o valor declarado deve ser compatível com o pedido).

/brazil/local/invoice/upload (multipart/form-data)

{
  "file_name": "invoice.xml",
  "trade_order_id": "1234567890654321",
  "file_content": "conteúdo do arquivo em multipart/form-data — não entra no cálculo da assinatura"
}

Consultar serviços de logística disponíveis (opcional)

Esta consulta é opcional no fluxo online. A solução logística já vem selecionada pelo modelo de envio, e o detalhe do pedido (aliexpress.trade.new.redefining.findorderbyid) já traz o serviço atribuído nos campos logistics_type e logistics_service_name de cada suborder. Nenhuma das etapas seguintes (empacotar, declarar envio, imprimir) consome o retorno desta consulta. Use-a apenas se quiser confirmar o shipmentProviderCode exato. Há dois endpoints, por escopo:

Por pacote / pedido — aliexpress.asf.package.shipping.service.get

aliexpress.asf.package.shipping.service.get

{
  "locale": "pt_BR",
  "tradeOrderId": 8210000000000000,
  "tradeOrderItemIdList": [8210000000000001]
}

{
  "result": {
    "data": {
      "shipmentProviderList": [
        {
          "shipmentProviderName": "Entrega Padrão 3PL(Sislogica-Correios)",
          "deliveryMode": "ONLINE",
          "shipmentProviderCode": "BR_L2L_SISLOGICA_CORREIOS"
        }
      ]
    },
    "success": true
  }
}

Por suborder — aliexpress.asf.order.shipping.service.get

Retorna o serviço de logística por suborder (tradeOrderItemId).

{
  "tradeOrderId": 8210000000000000,
  "tradeOrderItemIdList": [8210000000000001],
  "locale": "pt_BR"
}

Empacotar o pedido — aliexpress.asf.local2local.split.quantity.rts.pack

Empacota o pedido (linha online, logística da plataforma) e retorna o fulfillmentPackageId, usado na declaração de envio e na impressão da etiqueta. Requer a NF-e carregada previamente.

aliexpress.asf.local2local.split.quantity.rts.pack

{
  "sellerId": "6400000000",
  "tradeOrderId": 8210000000000000,
  "addressId": 3000000000001,
  "refundAddressId": "3000000000002",
  "locale": "pt_BR",
  "sendOption": "SELF_SEND",
  "tradeOrderItemSupportItemDTOS": [
    { "quantity": 1, "tradeOrderItemId": 8210000000000001 }
  ]
}

{
  "data": { "fulfillmentPackageId": "FP0000000000000001" },
  "success": true
}

Consultar pacote e número de rastreamento — aliexpress.asf.fulfillment.package.query

Consulta os pacotes do pedido, com o número de rastreamento (trackingNumber), o status e — em caso de falha na atribuição do número — o motivo (waybillAssignFailedReason). Substitui o antigo aliexpress.logistics.redefining.getonlinelogisticsinfo.

aliexpress.asf.fulfillment.package.query

{
  "tradeOrderId": 8210000000000000,
  "locale": "pt_BR"
}

{
  "result": {
    "data": {
      "dataSource": [
        {
          "tradeOrderId": "8210000000000000",
          "packageId": "FP0000000000000001",
          "trackingNumber": "AD000000000BR",
          "deliveryServiceProvider": "SISLOG",
          "subStatus": "待预约交货",
          "status": "待揽收"
        }
      ]
    },
    "success": true
  }
}

Campos da resposta (dataSource[]):

Evolução de status / subStatus ao longo do fluxo (valores observados):

Declaração de envio (RTS) — aliexpress.asf.platform.logistics.rts

Declara o envio do pacote na logística da plataforma. Substitui o antigo aliexpress.logistics.sellershipmentfortop. Só é aceito depois que o pacote já possui número de rastreamento.

aliexpress.asf.platform.logistics.rts

{
  "tradeOrderId": 8210000000000000,
  "locale": "pt_BR",
  "packageId": "FP0000000000000001",
  "trackingNumber": "AD000000000BR"
}

{
  "result": {
    "data": { "tradeOrderId": 8210000000000000 },
    "success": true
  }
}

Após o RTS, o status do pacote passa de a expedir para 待揽收 (aguardando coleta). A coleta passa a ser responsabilidade da transportadora.

Imprimir etiqueta (PDF) — aliexpress.asf.platform.logistics.document.query

Retorna a etiqueta de envio em PDF (campo bytes em base64, mais um link fileUrl temporário). Substitui o antigo aliexpress.logistics.local.getwaybillbypdf.

aliexpress.asf.platform.logistics.document.query

{
  "documentType": "WAY_BILL",
  "locale": "pt_BR",
  "queryDocumentRequestList": [
    {
      "tradeOrderId": "8210000000000000",
      "packageId": "FP0000000000000001",
      "trackingNumber": "AD000000000BR"
    }
  ]
}

Valores de documentType:

queryDocumentRequestList[]:

Cancelar / reempacotar — aliexpress.asf.platform.logistics.repack

Cancela um pacote já empacotado da logística da plataforma. Após o cancelamento, o pedido pode ser empacotado novamente. É útil para refazer a atribuição do número de rastreamento quando ela falhou (cancela o pacote antigo e gera um novo, reiniciando o processo de atribuição).

aliexpress.asf.platform.logistics.repack

{
  "tradeOrderId": 8210000000000000,
  "locale": "pt_BR",
  "packageId": "FP0000000000000002"
}

{
  "result": {
    "data": { "tradeOrderId": 8210000000000000 },
    "success": true
  }
}

Depois do cancelamento, empacote novamente com aliexpress.asf.local2local.split.quantity.rts.pack para gerar um novo pacote e reiniciar a atribuição do número de rastreamento.

Endpoints antigos (descontinuados)

Mapa de substituição:

Guia para migração

Esta guia tem como objetivo auxiliar na migração da versão antiga para a versão atual da API do AliExpress.

A nova versão oferece recursos mais completos e melhor experiência de uso. Ao mesmo tempo, o caminho para a migração é simples e direto com poucas mudanças.

A plataforma legada está sendo desativada, com limite de tráfego em breve. Portanto, é importante que você migrar para a nova versão o quanto antes.

Qual versão da API estou usando?

Para saber qual versão da API você está usando, basta verificar o host da requisição.

Se o host não for api-sg.aliexpress.com, você está usando a versão antiga da API e deve migrar para a nova.

O que mudou?

A versão atual da API do AliExpress possui algumas mudanças em relação a versão antiga.

Mudaças na Autenticação

• access_token não é compatível com a versão antiga. Para cada loja, é necessário gerar um novo access_token na versão atual da API. É vital solicitar a autorização dos sellers assim que a atualização for feita.
• refresh_token pode ser usado para gerar um novo access_token na versão atual da API. Com esta atualização, sellers não precisam mais autorizar a cada 30 dias.

Mudanças nos API calls

Há algumas mudanças nos API calls da versão atual da API. Você pode seguir a seção API calls para mais detalhes. Alternativamente, você pode seguir a seção Usar API com SDK para utilizar o SDK.

Mudanças nos Endpoints

• Para endpoints que já existiam na versão antiga, os parâmetros permanecem os mesmos, os retornos também permanecem os mesmos.
• Novos endpoints foram adicionados na versão atual da API. Principalmente endpoints relacionados a logística, que foi listado na seção Guia para logística.

FAQ

Nome do produtos não aparece no Danfe

Para exibir corretamente o nome do produto no Danfe gerado pelo provedor logístico, é necessário que o nome do produto seja inserido no campo category_cn_desc ao criar o pedido logístico pelo seguinte endpoint:

aliexpress.logistics.local.createwarehouseorder

Formato do endereço do pedido

Houve uma alteração no formulário de endereço do pedido no AliExpress. Atualmente, existem duas versões coexistentes de endereços. No novo formato, o street_address é concatenado de 3 campos:

rua|numero|complemento.

Erro B-071-0203-01-16-002

Este erro ocorre quando a loja não assinou o contrato de logística ou termos de serviço. Para resolver, acessar o panel do AliExpress e assinar os documentos necessários.

Erro “null#package_height” is not valid

A dimensão do produto precisa ser números inteiros positivos em centímetros.

Personalizar propriedades de SKU

Cada categoria define um esquema para seus produtos. O esquema inclui como as variantes podem ser definidas e quais propriedades podem variar entre os SKUs. Por exemplo, muitas categorias suportam variantes de cores diferentes. Uma lista de cores padrão é fornecida para os vendedores escolherem e deve ser suficiente na maioria dos casos.

{
  "customized_name": true,
  "visible": true,
  "customized_pic": true,
  "key_attribute": false,
  "values": [
    {
      "names": "{\"en\":\"Army Green\",\"zh\":\"军绿色\"}",
      "id": 200004889,
      "has_sub_attr": false,
      "value_tags": "{}"
    },
    {
      "names": "{\"en\":\"Dark Grey\",\"zh\":\"深灰色\"}",
      "id": 200004890,
      "has_sub_attr": false,
      "value_tags": "{}"
    },
    ...
  ],
  "input_type": "STRING",
  "attribute_show_type_value": "check_box",
  "required": true,
  "spec": 1,
  "features": "{\"AE_FEATURE_PUserDefineStrategy\":\"ES,BR\",\"AE_FEATURE_PDisplayStrategy\":\"ES,BR\"}",
  "names": "{\"en\":\"Color\",\"zh\":\"颜色\"}",
  "support_enum_input": false,
  "id": 14,
  "sku": true
}

Mas certos produtos podem ter cores que não estão presentes na lista fornecida. Neste caso é necessário verificar o campo customized_name e customized_pic.

{
  "sku_property_id": "14",
  "property_value_id": "29",
  "property_value_definition_name": "Wine Red",
  "sku_image": "https://ae01.alicdn.com/kf/Sebc6e4fda11f45a7997******.jpg"
}

Se algum dos campos customized_name ou customized_pic estiverem marcados como true, você pode definir o texto ou a imagem da variante.

Isto significa que além de definir sku_property_id e property_value_id em aeop_s_k_u_property, você também deve definir property_value_definition_name e sku_image em aeop_s_k_u_property_value.

Erro TPL_NOT_EXIT

Este erro ocorre quando o produto não tem um modelo de frete ou o id fornecido não existe.

Para resolver, verificar seção Modelo de frete.