ae_sdk
Version:
A simple SDK for Aliexpress (dropshipping and affiliate) APIs.
281 lines (212 loc) • 8.32 kB
Markdown
# AliExpress SDK 
[](https://www.npmjs.com/package/ae_sdk)
[](https://bundlephobia.com/package/ae_sdk)
[](https://github.com/moh3a/ae_sdk/blob/master/LICENSE)
A simple, lightweight, and fully type-safe SDK for the AliExpress Open Platform APIs. Supports System Authentication, Dropshipping, and Affiliate APIs.
## 📖 Overview
AliExpress has completely migrated their services from the legacy [Taobao Open Platform](https://developers.aliexpress.com) to the new [Open Platform for International Developers](https://openservice.aliexpress.com). While this update brought significant improvements, [they have yet to release an official Node.js SDK](https://openservice.aliexpress.com/doc/doc.htm?nodeId=27493&docId=118729#/?docId=1371) for the new platform.
This unofficial SDK bridges that gap by providing a simple, consistent interface for Node.js developers to interact with AliExpress APIs.
## ✨ Features
This SDK provides several key capabilities:
### 🔐 Authentication & Security
- **Request Signing** - Automatic generation of method signatures required by AliExpress
- **Session Management** - Streamlined token generation and refresh flows
- **Error Handling** - Consistent error responses with detailed messages
### 💻 Developer Experience
- **Type Safety** - Fully typed parameters and responses for all API methods
- **Intuitive API** - Clean, method-based approach to API calls
### 🛍️ Supported APIs
- **System Authentication** - Token generation, refresh, and security token operations
- **Dropshipping API** - Product details, order management, shipping calculations, and more
- **Affiliate API** - Product discovery, link generation, commission tracking, and reporting
## 📦 Installation
```sh
# Using npm
npm install ae_sdk
# Using pnpm
pnpm add ae_sdk
# Using yarn
yarn add ae_sdk
```
## 🚀 Getting Started
### Prerequisites
Before using this SDK, you'll need to complete several steps on the AliExpress Open Platform:
1. **Register as a Developer**
- Create or use an existing AliExpress account
- Register as a developer at [AliExpress Open Platform](https://openservice.aliexpress.com/)
- [Detailed registration guide](https://openservice.aliexpress.com/doc/doc.htm?nodeId=27493&docId=118729#/?docId=1362)
2. **Create an Application**
- Register a new application on the platform
- [Application registration guide](https://openservice.aliexpress.com/doc/doc.htm?nodeId=27493&docId=118729#/?docId=1361)
3. **Get API Credentials**
- Retrieve your `app_key` and `app_secret` from your registered application
- [Credential retrieval guide](https://openservice.aliexpress.com/doc/doc.htm?nodeId=27493&docId=118729#/?docId=1360)
4. **Obtain Access Token**
- Guide users through the authorization flow to get an access token
- [Authorization flow guide](https://openservice.aliexpress.com/doc/doc.htm?nodeId=27493&docId=118729#/?docId=1364)
### Basic Usage
#### 1. Initialize a Client
Choose the appropriate client based on your needs (System, Dropshipper, or Affiliate):
```typescript
import { DropshipperClient } from "ae_sdk";
const client = new DropshipperClient({
app_key: "YOUR_APP_KEY",
app_secret: "YOUR_APP_SECRET",
session: "ACCESS_TOKEN_FROM_AUTH_FLOW",
});
```
#### 2. Make API Calls
Each client provides typed methods for different API operations:
```typescript
// Get product details
const productResponse = await client.productDetails({
product_id: 1005004043442825,
ship_to_country: "US",
target_currency: "USD",
target_language: "en",
});
if (productResponse.ok) {
console.log("Product:", productResponse.data);
}
```
#### 3. Handle Responses
All API methods return a consistent response structure:
```typescript
// Successful response
{
ok: true,
data: {
// API-specific response data
aliexpress_ds_product_get_response: {
result: { /* product data */ },
rsp_code: 200,
rsp_msg: "Call succeeds",
request_id: "1234567890"
}
}
}
// Error response
{
ok: false,
message: "Error message explaining what went wrong",
request_id: "1234567890", // If available
error_response: {}, // Full AliExpress error response if available
error: {} // JavaScript Error object if applicable
}
```
## 📚 API Examples
### System Client
For authentication and token management:
```typescript
import { AESystemClient } from "ae_sdk";
const systemClient = new AESystemClient({
app_key: "YOUR_APP_KEY",
app_secret: "YOUR_APP_SECRET",
session: "EXISTING_ACCESS_TOKEN", // Optional for some operations
});
// Generate a new token from an authorization code
const tokenResponse = await systemClient.generateToken({
code: "AUTH_CODE_FROM_REDIRECT",
uuid: "OPTIONAL_UUID",
});
// Refresh an existing token before it expires
const refreshResponse = await systemClient.refreshToken({
refresh_token: "REFRESH_TOKEN_FROM_PREVIOUS_AUTH",
});
```
### Affiliate Client
For affiliate marketing operations:
```typescript
import { AffiliateClient } from "ae_sdk";
const affiliateClient = new AffiliateClient({
app_key: "YOUR_APP_KEY",
app_secret: "YOUR_APP_SECRET",
session: "ACCESS_TOKEN",
});
// Generate affiliate tracking links
const linksResponse = await affiliateClient.generateAffiliateLinks({
promotion_link_type: 0, // 0 for normal, 2 for hot product link
source_values: "https://www.aliexpress.com/item/1234567890.html",
tracking_id: "YOUR_TRACKING_ID",
app_signature: "YOUR_APP_SIGNATURE",
});
// Find trending products with high commission rates
const hotProductsResponse = await affiliateClient.getHotProducts({
app_signature: "YOUR_APP_SIGNATURE",
keywords: "smartphone",
page_no: 1,
page_size: 20,
platform_product_type: "ALL",
ship_to_country: "US",
sort: "SALE_PRICE_ASC",
target_currency: "USD",
target_language: "EN",
tracking_id: "YOUR_TRACKING_ID",
});
```
### Dropshipper Client
For dropshipping operations:
```typescript
import { DropshipperClient } from "ae_sdk";
const dropshipperClient = new DropshipperClient({
app_key: "YOUR_APP_KEY",
app_secret: "YOUR_APP_SECRET",
session: "ACCESS_TOKEN",
});
// Calculate shipping options and costs
const shippingResponse = await dropshipperClient.shippingInfo({
country_code: "US",
product_id: 1005004043442825,
product_num: 2,
province_code: "CA",
city_code: "Los Angeles",
send_goods_country_code: "CN",
price: "29.99",
});
// Create a dropshipping order
const orderResponse = await dropshipperClient.createOrder({
logistics_address: {
address: "123 Main Street",
city: "Los Angeles",
country: "US",
full_name: "John Doe",
mobile_no: "123-456-7890",
phone_country: "+1",
province: "California",
zip: "90001",
},
product_items: [
{
logistics_service_name: "AliExpress Standard Shipping",
order_memo: "Customer order #12345",
product_count: 2,
product_id: 1005004043442825,
sku_attr: "14:350853#Black;5:361386", // SKU specification attributes
},
],
});
```
## 🔍 Advanced Usage
### Direct API Calls
For APIs not yet included in the SDK:
```typescript
const response = await client.callAPIDirectly(
"aliexpress.custom.api.endpoint",
{
param1: "value1",
param2: "value2",
// Additional parameters as required by the API
},
);
```
## 🤝 Contributing
Contributions are welcome! Feel free to open issues or submit pull requests for:
- Bug fixes
- New API endpoint support
- Documentation improvements
- Performance optimizations
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/moh3a/ae_sdk/blob/master/LICENSE) file for details.