跳转到主要内容
eBay AI 广告
登录

快速开始

5 分钟完成首个 API 调用，快速上手 eBay AI 广告平台 Open API。

预计阅读 14 分钟编辑此页

快速开始#

本指南将帮助您在 5 分钟内完成首个 API 调用。我们将以获取广告活动列表为例，演示完整的 API 调用流程。

前置条件#

在开始之前，请确保您已经：

  • ✅ 注册并登录 eBay AI 广告平台
  • ✅ 拥有至少一个已授权的 eBay 账户
  • ✅ 熟悉基本的 HTTP 请求概念

第一步：获取 API 凭证#

  1. 登录 eBay AI 广告平台控制台
  2. 点击右上角头像，选择「API 设置」
  3. 在「Open API」页面，点击「创建 API Key」
  4. 安全保存您的 API Key 和 API Secret
警告

API Secret 仅在创建时显示一次，请务必安全保存。如果丢失，需要重新创建。

创建成功后，您将获得类似以下的凭证：

API Key:    ak_1234567890abcdef
API Secret: sk_abcdef1234567890abcdef1234567890

第二步：构造请求签名#

所有 API 请求都需要使用 HMAC-SHA256 进行签名。签名算法如下：

signature = HMAC-SHA256(api_secret, timestamp + method + path + body)

Python 示例#

import hmac
import hashlib
import time
import json
import requests

# 您的 API 凭证
API_KEY = "ak_1234567890abcdef"
API_SECRET = "sk_abcdef1234567890abcdef1234567890"

# API 基础 URL
BASE_URL = "https://api.eaby-ads.com/api/v1/open"

def generate_signature(method: str, path: str, body: str = "") -> tuple[str, str]:
    """生成 API 请求签名"""
    timestamp = str(int(time.time()))
    message = f"{timestamp}{method.upper()}{path}{body}"
    signature = hmac.new(
        API_SECRET.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return signature, timestamp

def make_request(method: str, path: str, data: dict = None):
    """发起 API 请求"""
    body = json.dumps(data) if data else ""
    signature, timestamp = generate_signature(method, path, body)
    
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Signature": signature,
        "X-Timestamp": timestamp,
    }
    
    url = f"{BASE_URL}{path}"
    response = requests.request(method, url, headers=headers, data=body)
    return response.json()

Node.js 示例#

const crypto = require('crypto');
const axios = require('axios');

const API_KEY = 'ak_1234567890abcdef';
const API_SECRET = 'sk_abcdef1234567890abcdef1234567890';
const BASE_URL = 'https://api.eaby-ads.com/api/v1/open';

function generateSignature(method, path, body = '') {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const message = `${timestamp}${method.toUpperCase()}${path}${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');
  return { signature, timestamp };
}

async function makeRequest(method, path, data = null) {
  const body = data ? JSON.stringify(data) : '';
  const { signature, timestamp } = generateSignature(method, path, body);
  
  const response = await axios({
    method,
    url: `${BASE_URL}${path}`,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-Signature': signature,
      'X-Timestamp': timestamp,
    },
    data: body || undefined,
  });
  
  return response.data;
}

cURL 示例#

#!/bin/bash

API_KEY="ak_1234567890abcdef"
API_SECRET="sk_abcdef1234567890abcdef1234567890"
BASE_URL="https://api.eaby-ads.com/api/v1/open"

# 生成签名
TIMESTAMP=$(date +%s)
METHOD="GET"
PATH="/campaigns"
BODY=""

MESSAGE="${TIMESTAMP}${METHOD}${PATH}${BODY}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

# 发起请求
curl -X GET "${BASE_URL}${PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "X-Timestamp: ${TIMESTAMP}"

第三步：获取广告活动列表#

现在让我们发起首个 API 请求，获取您账户下的广告活动列表：

Python#

# 获取广告活动列表
result = make_request("GET", "/campaigns")
print(json.dumps(result, indent=2, ensure_ascii=False))

Node.js#

// 获取广告活动列表
const result = await makeRequest('GET', '/campaigns');
console.log(JSON.stringify(result, null, 2));

成功响应示例#

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 12345,
        "name": "2026春季促销活动",
        "status": "active",
        "budget_daily": 50.00,
        "spend_today": 23.45,
        "impressions_today": 1520,
        "clicks_today": 45,
        "created_at": "2026-01-01T00:00:00Z"
      },
      {
        "id": 12346,
        "name": "清仓特卖",
        "status": "paused",
        "budget_daily": 30.00,
        "spend_today": 0,
        "impressions_today": 0,
        "clicks_today": 0,
        "created_at": "2025-12-15T00:00:00Z"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

第四步：创建广告活动#

让我们再创建一个新的广告活动：

# 创建新的广告活动
new_campaign = make_request("POST", "/campaigns", {
    "name": "新年促销活动",
    "ebay_account_id": 123,
    "campaign_type": "keyword_targeting",
    "budget_daily": 100.00,
    "start_date": "2026-01-15",
    "end_date": "2026-02-15"
})

print(f"创建成功！活动ID: {new_campaign['data']['id']}")

成功响应示例#

{
  "success": true,
  "data": {
    "id": 12347,
    "name": "新年促销活动",
    "status": "draft",
    "campaign_type": "keyword_targeting",
    "budget_daily": 100.00,
    "start_date": "2026-01-15",
    "end_date": "2026-02-15",
    "created_at": "2026-01-10T12:00:00Z"
  }
}
提示

新创建的广告活动默认为 draft（草稿）状态。需要添加广告组和关键词后，才能激活投放。

错误处理#

当 API 请求失败时，会返回包含错误信息的响应：

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "请求签名验证失败",
    "request_id": "req_abc123"
  }
}

常见错误及解决方案：

| 错误码 | 原因 | 解决方案 | |--------|------|----------| | INVALID_SIGNATURE | 签名验证失败 | 检查签名算法和密钥是否正确 | | TIMESTAMP_EXPIRED | 时间戳过期 | 确保服务器时间准确，时间戳在 5 分钟内 | | RATE_LIMITED | 请求过于频繁 | 降低请求频率，实现退避重试 | | UNAUTHORIZED | API Key 无效 | 检查 API Key 是否正确 |

更多错误码请参阅 错误码参考。

使用 SDK（推荐）#

为了简化开发，我们提供了官方 SDK，已封装好签名和请求逻辑：

Python SDK#

pip install eaby-ads-sdk

from eaby_ads import EabyAdsClient

client = EabyAdsClient(
    api_key="ak_1234567890abcdef",
    api_secret="sk_abcdef1234567890abcdef1234567890"
)

# 获取广告活动列表
campaigns = client.campaigns.list()
for campaign in campaigns:
    print(f"{campaign.name}: {campaign.status}")

# 创建广告活动
new_campaign = client.campaigns.create(
    name="新年促销活动",
    ebay_account_id=123,
    budget_daily=100.00
)

Node.js SDK#

npm install @eaby-ads/sdk

import { EabyAdsClient } from '@eaby-ads/sdk';

const client = new EabyAdsClient({
  apiKey: 'ak_1234567890abcdef',
  apiSecret: 'sk_abcdef1234567890abcdef1234567890',
});

// 获取广告活动列表
const campaigns = await client.campaigns.list();
campaigns.forEach(campaign => {
  console.log(`${campaign.name}: ${campaign.status}`);
});

// 创建广告活动
const newCampaign = await client.campaigns.create({
  name: '新年促销活动',
  ebayAccountId: 123,
  budgetDaily: 100.00,
});

下一步#

恭喜您完成了首个 API 调用！接下来您可以：