3/3/23, 4:21 PM Primeiros passos – API Reference

I. Primeiros passos
1. AliExpress Open Platform
2. Sobre este documento
3. Cadastro de conta de desenvolvedor
4. Approvação de conta de desenvolvedor
5. Criação de aplicativo
6. Gerenciamento de aplicativo

II. API calls

1. Ambiente de produção
2. System parameters
3. Business parameters
4. Cálculo de Assinatura
5. Enviar a solicitação

III. Usar API com SDK

IV. Autenticação e Autorização

1. Gerar o link de autorização
2. Guiar o vendedor a autorizar seu app
3. Obter o code
4. Obter o token de acesso
5. Atualizar o token de acesso

V. Guia para produtos

1. Configurações antes de publicar um produto
2. Escolher uma categoria
3. Propriedades para produtos
4. Propriedade de SKU
5. Propriedades comuns
6. Fotos do produto
7. Modelo de frete
8. Criar um produto

VI. Guia para pedidos

1. Endpoints para sincronização de pedidos
2. Initializar o processo de sincronização
3. Sincronização incremental pelo API
4. Sincronização incremental pelo Webhook
5. Status de pedidos

VII. Guia para envio (cainiao)

VIII. FAQ
1. Nome do produtos não aparece no Danfe
2. Formato do endereço do pedido
https://ae-br-doc.teeki.com.br/# 1/11
3/3/23, 4:21 PM Primeiros passos – API Reference

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".

https://ae-br-doc.teeki.com.br/# 2/11
3/3/23, 4:21 PM Primeiros passos – API Reference

API calls

Ambiente de produção
MÉTODO MIGRADO

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

MÉTODO NOVO

https://api-sg.aliexpress.com/rest{api_path}?{query}

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.

Parâmetro Tipo Obrigatório Descrição

app_key String Sim Chave de aplicativo.

access_token String Não Token de acesso para acessar os dados do usuário(vendedor).

timestamp String Sim Timestamp. Em formato como 2017-11-11T12:00:00Z ou 1675532891453 .

sign_method String Sim Método de assinatura. sha256

sign String Sim Assinatura.

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",

https://ae-br-doc.teeki.com.br/# 3/11
3/3/23, 4:21 PM Primeiros passos – API Reference
"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.

 Atenção: O token obtido aqui não é o mesmo token utilizado para autenticação nas APIs antigas.

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

https://ae-br-doc.teeki.com.br/# 4/11
3/3/23, 4:21 PM Primeiros passos – API Reference

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_uri=${redirect_uri}&client_id=${client_id}

Parâmetro Tipo Obrigatório Descrição

client_id String Sim Chave de aplicativo.

URL de redirecionamento. Devem com a mesma domain com callback_url

redirect_uri String Sim
configurado no App Console.

response_type String Sim Deve ser code .

force_auth Boolean Não Se true , o vendedor será obrigado a fazer login novamente.

state String Não Parâmetro que vai ser retornado na URL de redirecionamento.

uuid String Não Parâmetro que vai ser retornado na URL de redirecionamento.

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_uri 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.

 Atenção: O code é válido por 30 minutos.

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"
}

https://ae-br-doc.teeki.com.br/# 5/11
3/3/23, 4:21 PM Primeiros passos – API Reference

Parâmetro Tipo Obrigatório Descrição

code String Sim O código obtido no passo anterior.

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.

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.

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:

https://ae-br-doc.teeki.com.br/# 6/11
3/3/23, 4:21 PM Primeiros passos – API Reference

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,

https://ae-br-doc.teeki.com.br/# 7/11
3/3/23, 4:21 PM Primeiros passos – API Reference
"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

Campo Customização Descrição Exemplo

sku_property_id Não ID da propriedade de SKU 200009209

property_value_id Não ID do valor da propriedade de SKU 200660849

property_value_definition_name Sim Nome do valor da propriedade de SKU pink

sku_image Sim Imagem da variação "http://***.jpg"

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:

Condição attr_name_id attr_value_id attr_name attr_value

Com lista de valores, sem "other"

Obrigatório Obrigatório Invalido Invalido
opção

Com lista de valores, com "other" Obrigatório quando "other" é

Obrigatório Obrigatório Invalido
opção selecionado

Sem lista de valores Obrigatório Invalido Invalido Obrigatório

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

https://ae-br-doc.teeki.com.br/# 8/11
3/3/23, 4:21 PM Primeiros passos – API Reference

attr_name_id attr_value_id attr_name attr_value

Invalido Invalido Obrigatório Obrigatório

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

aliexpress.image.redefining.uploadtempimageforsdk

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

aliexpress.freight.redefining.listfreighttemplate

Criar um produto
Você pode criar um produto usando o seguinte endpoint:

aliexpress.offer.product.post

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.seller.orderlist.get 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

https://ae-br-doc.teeki.com.br/# 9/11
3/3/23, 4:21 PM Primeiros passos – API Reference

Para sincronizar os pedidos incrementalmente, você deve obtendo a lista de pedidos usando o endpoint aliexpress.trade.seller.orderl
ist.get 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.

Status de pedidos

Status Descrição

PLACE_ORDER_SUCCESS Pedido criado

IN_CANCEL Comprador solicitou cancelamento

WAIT_SELLER_SEND_GOODS Aguardando envio pelo vendedor

SELLER_PART_SEND_GOODS Vendedor enviou parte dos itens

WAIT_BUYER_ACCEPT_GOODS Aguardando aceitação do comprador

FUND_PROCESSING Processando pagamento

IN_ISSUE Em disputa

IN_FROZEN Em congelamento

WAIT_SELLER_EXAMINE_MONEY Aguardando análise de pagamento pelo vendedor

PAYMENT_PROCESSING Processando pagamento

RISK_CONTROL Controle de risco, aguardando aprovação(24 horas)

Guia para envio (cainiao)

Cainiao é a solução logística preferida da AliExpress. Ele fornece uma maneira econômica para os vendedores entregarem encomendas
rapidamente e com segurança para todo o país. A solução comercial exige que os vendedores carreguem o NFe (Nota Fiscal Eletrônica)
para cada encomenda. Esse seção fornece um guia passo a passo de como integrar a solução logística Cainiao.

FAQ

https://ae-br-doc.teeki.com.br/# 10/11
3/3/23, 4:21 PM Primeiros passos – API Reference

Nome do produtos não aparece no Danfe

Para exibir corretamente o nome do produto no Danfe gerado por Cainiao, é necessário que o nome do produto seja inserido no
campo category_cn_desc quando criar um pedido logistico no Cainiao pelo o 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 .

https://ae-br-doc.teeki.com.br/# 11/11