快速开始#

本指南将帮助您在 5 分钟内完成第一个 API 调用。

前置条件#

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

• ✅ 拥有 eBay AI 广告平台账户
• ✅ 创建了 API Key（参考 认证方式）
• ✅ 安装了 Python 3.8+ 或 Node.js 16+

步骤 1：安装 SDK（可选）#

我们提供官方 SDK 简化 API 调用：

# Python
pip install eaby-ads-sdk

# Node.js
npm install @eaby/ads-sdk

步骤 2：配置密钥#

创建配置文件或设置环境变量：

# 设置环境变量
export EABY_ACCESS_KEY="ak_your_access_key"
export EABY_SECRET_KEY="sk_your_secret_key"

步骤 3：发送第一个请求#

让我们获取广告活动列表：

from eaby_ads import Client

# 初始化客户端
client = Client()

# 获取广告活动列表
campaigns = client.campaigns.list()

for campaign in campaigns.data:
    print(f"📋 {campaign.name} - 状态: {campaign.status}")

或者使用原生 HTTP 请求：

import os
import hmac
import hashlib
import time
import requests

access_key = os.environ["EABY_ACCESS_KEY"]
secret_key = os.environ["EABY_SECRET_KEY"]

method = "GET"
path = "/api/v1/open/campaigns"
timestamp = str(int(time.time()))

# GET 请求无 body，使用空字符串的 MD5
body_md5 = hashlib.md5(b"").hexdigest()

string_to_sign = f"{method}\n{path}\n{timestamp}\n{body_md5}"
signature = hmac.new(
    secret_key.encode(),
    string_to_sign.encode(),
    hashlib.sha256
).hexdigest()

response = requests.get(
    f"https://api.eaby-ads.com{path}",
    headers={
        "X-API-Key": access_key,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    }
)

print(response.json())

步骤 4：验证结果#

成功响应示例：

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "春季促销活动",
        "status": "active",
        "budget_daily": 50.00,
        "created_at": "2026-01-01T00:00:00Z"
      },
      {
        "id": 2,
        "name": "新品推广",
        "status": "paused",
        "budget_daily": 30.00,
        "created_at": "2026-01-05T00:00:00Z"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

常见操作示例#

创建广告活动#

campaign = client.campaigns.create(
    name="2026 夏季促销",
    budget_daily=100.00,
    ebay_account_id=123,
)
print(f"✅ 创建成功：ID = {campaign.id}")

添加关键词#

keywords = client.keywords.batch_create(
    ad_group_id=456,
    keywords=[
        {"keyword": "wireless earbuds", "bid": 0.50},
        {"keyword": "bluetooth headphones", "bid": 0.45},
    ]
)
print(f"✅ 添加了 {len(keywords)} 个关键词")

获取报表数据#

report = client.reports.campaigns(
    campaign_id=1,
    start_date="2026-01-01",
    end_date="2026-01-10",
)
print(f"📊 展示: {report.impressions}, 点击: {report.clicks}, ROAS: {report.roas}")

错误处理#

建议在生产环境中添加错误处理：

from eaby_ads import Client, ApiError, AuthenticationError

client = Client()

try:
    campaigns = client.campaigns.list()
except AuthenticationError as e:
    print(f"❌ 认证失败: {e.message}")
    # 检查 API Key 是否正确
except ApiError as e:
    print(f"❌ API 错误: {e.code} - {e.message}")
    # 根据错误码处理
except Exception as e:
    print(f"❌ 未知错误: {e}")

下一步#

• 📖 查看完整的 API 参考 文档
• 🔔 配置 Webhook 接收实时通知
• 💡 阅读 最佳实践 优化您的集成

需要帮助？#

如果您在集成过程中遇到问题：

• 📧 发送邮件至 developer@eaby-ads.com
• 💬 加入开发者微信群
• 🐛 在 GitHub 提交 Issue