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

认证方式

了解如何使用 HMAC-SHA256 签名进行 API 认证

预计阅读 9 分钟编辑此页

认证方式#

所有 API 请求都需要进行身份认证。我们使用 HMAC-SHA256 签名机制确保请求的安全性和完整性。

获取 API Key#

在使用 API 之前，您需要先创建 API Key：

  1. 登录 eBay AI 广告平台
  2. 进入「设置」→「API 管理」
  3. 点击「创建 API Key」
  4. 保存生成的 Access Key 和 Secret Key
重要提示

Secret Key 只会显示一次，请妥善保管。如果遗失，需要重新创建 API Key。

认证流程#

每个 API 请求需要包含以下 HTTP 头：

| Header | 说明 | 示例 | |--------|------|------| | X-API-Key | 您的 Access Key | ak_abc123def456 | | X-Timestamp | 请求时间戳（秒） | 1704844800 | | X-Signature | HMAC-SHA256 签名 | a1b2c3d4... |

HMAC 签名#

签名字符串格式：

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_MD5}

签名步骤#

  1. 构造待签名字符串

    • METHOD: 请求方法（大写），如 POST
    • PATH: 请求路径，如 /api/v1/open/campaigns
    • TIMESTAMP: 当前 Unix 时间戳（秒）
    • BODY_MD5: 请求体的 MD5 值（无请求体时为空字符串的 MD5）

  2. 计算签名

    • 使用 Secret Key 对待签名字符串进行 HMAC-SHA256 运算
    • 将结果转换为十六进制小写字符串

请求示例#

Python#

import hmac
import hashlib
import time
import json
import requests

# 您的密钥
access_key = "ak_your_access_key"
secret_key = "sk_your_secret_key"

# 请求参数
method = "POST"
path = "/api/v1/open/campaigns"
timestamp = str(int(time.time()))
body = json.dumps({
    "name": "测试广告活动",
    "budget_daily": 50.00,
    "ebay_account_id": 123
})

# 计算 Body MD5
body_md5 = hashlib.md5(body.encode()).hexdigest()

# 构造待签名字符串
string_to_sign = f"{method}\n{path}\n{timestamp}\n{body_md5}"

# 计算 HMAC-SHA256 签名
signature = hmac.new(
    secret_key.encode(),
    string_to_sign.encode(),
    hashlib.sha256
).hexdigest()

# 发送请求
response = requests.post(
    f"https://api.eaby-ads.com{path}",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": access_key,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    },
    data=body
)

print(response.json())

JavaScript / Node.js#

const crypto = require('crypto');
const fetch = require('node-fetch');

// 您的密钥
const accessKey = 'ak_your_access_key';
const secretKey = 'sk_your_secret_key';

// 请求参数
const method = 'POST';
const path = '/api/v1/open/campaigns';
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({
  name: '测试广告活动',
  budget_daily: 50.00,
  ebay_account_id: 123
});

// 计算 Body MD5
const bodyMd5 = crypto.createHash('md5').update(body).digest('hex');

// 构造待签名字符串
const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyMd5}`;

// 计算 HMAC-SHA256 签名
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(stringToSign)
  .digest('hex');

// 发送请求
const response = await fetch(`https://api.eaby-ads.com${path}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': accessKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: body
});

console.log(await response.json());

cURL#

#!/bin/bash

ACCESS_KEY="ak_your_access_key"
SECRET_KEY="sk_your_secret_key"

METHOD="POST"
PATH="/api/v1/open/campaigns"
TIMESTAMP=$(date +%s)
BODY='{"name":"测试广告活动","budget_daily":50.00,"ebay_account_id":123}'

# 计算 Body MD5
BODY_MD5=$(echo -n "$BODY" | md5sum | cut -d' ' -f1)

# 构造待签名字符串
STRING_TO_SIGN="${METHOD}\n${PATH}\n${TIMESTAMP}\n${BODY_MD5}"

# 计算签名
SIGNATURE=$(echo -en "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

# 发送请求
curl -X POST "https://api.eaby-ads.com${PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${ACCESS_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Signature: ${SIGNATURE}" \
  -d "$BODY"

时间戳验证#

为防止重放攻击，服务器会验证时间戳：

  • 时间戳与服务器时间相差不能超过 5 分钟
  • 请确保您的服务器时间与 NTP 服务器同步
常见错误

如果收到 TIMESTAMP_EXPIRED 错误，请检查：

  1. 服务器时间是否准确
  2. 时间戳是否为 秒 而非毫秒

错误处理#

认证相关错误码：

| 错误码 | HTTP 状态 | 说明 | |--------|----------|------| | UNAUTHORIZED | 401 | API Key 无效或未提供 | | SIGNATURE_INVALID | 401 | 签名验证失败 | | TIMESTAMP_EXPIRED | 401 | 时间戳过期 | | API_KEY_DISABLED | 403 | API Key 已被禁用 |

下一步#

认证配置完成后，您可以：