PHP小码农

Appearance

Amazon SP-API PHP 开发完全指南 ​

概述 ​

Amazon Selling Partner API (SP-API) 是亚马逊官方提供的 RESTful API，用于卖家和供应商与亚马逊商城进行程序化交互。本教程将带你从零开始，使用 PHP 完成所有 SP-API 接口的对接开发。

为什么学习 SP-API？ ​

  • 官方支持：亚马逊官方维护，稳定可靠
  • 功能全面：覆盖订单、库存、物流、财务等所有业务场景
  • 安全合规：OAuth 2.0 + AWS Signature V4 双重认证
  • 替代 MWS：MWS 已逐步弃用，SP-API 是未来方向

适用人群 ​

  • 亚马逊卖家/供应商的技术团队
  • ERP/WMS 系统开发者
  • 跨境电商工具开发者
  • 需要自动化运营的卖家

学习路径 ​

本教程采用六阶段渐进式学习路径，帮助你从入门到精通：

第一阶段：基础准备 ​

📚 基础准备
├── SP-API 入门
│   ├── SP-API 概览
│   ├── 架构设计
│   └── 前置要求
├── 环境搭建
│   ├── 开发者账号注册
│   ├── IAM 配置
│   └── PHP 环境搭建
└── 核心概念
    ├── 认证机制
    ├── 授权流程
    └── 限流机制

学习目标：理解 SP-API 架构，完成开发环境配置

第二阶段：核心认证 ​

🔐 核心认证
├── LWA 认证
│   ├── OAuth 2.0 流程
│   ├── 令牌管理
│   └── 刷新令牌
├── AWS 签名
│   ├── Signature V4 算法
│   ├── PHP 实现
│   └── 常见问题
└── HTTP 客户端
    ├── Guzzle 配置
    ├── 请求构建
    └── 错误处理

学习目标：掌握 SP-API 认证授权机制，实现安全调用

第三阶段：核心 API ​

⚡ 核心 API
├── 订单管理 API (12个操作)
├── 库存管理 API (5个操作)
├── 商品目录 API (3个操作)
├── 定价 API (11个操作)
├── 财务 API (4个操作)
├── 报告 API (9个操作)
├── Feeds API (6个操作)
├── 商品刊登 API (6个操作)
├── 物流发货 API (22个操作)
├── 入库管理 API (23个操作)
└── 商品费用 API (3个操作)

学习目标：掌握日常运营核心 API，实现基础业务自动化

第四阶段：高级功能 ​

🚀 高级功能
├── 通知订阅
├── 受限数据访问
├── 沙箱测试
├── 消息管理 API
├── A+ 内容管理 API
├── 供应商功能 API
└── 更多高级 API...

学习目标：掌握高级功能，实现复杂业务场景

第五阶段：实战项目 ​

💼 实战项目
├── 订单同步系统
├── 库存管理系统
├── 商品刊登系统
├── 物流发货系统
├── 报表自动化系统
├── 财务对账系统
├── 价格监控系统
└── 客户服务系统

学习目标：独立完成企业级项目开发

第六阶段：生产部署 ​

🎯 生产部署
├── 性能优化
│   ├── 限流处理
│   ├── 缓存策略
│   └── 并发处理
├── 安全加固
│   ├── 数据加密
│   ├── 访问控制
│   └── 审计日志
└── 监控与告警
    ├── API 监控
    ├── 告警系统
    └── 性能指标

学习目标：掌握生产环境部署与运维

常见应用场景 ​

场景一：订单自动同步 ​

场景描述：定时拉取亚马逊订单，同步到本地 ERP 系统

使用 API：Orders API

php
<?php
$orders = $spApi->orders()->getOrders([
    'LastUpdatedAfter' => date('Y-m-d\TH:i:s\Z', strtotime('-24 hours')),
    'MarketplaceIds' => ['ATVPDKIKX0DER'],
]);

foreach ($orders['Orders'] as $order) {
    $this->syncOrderToLocal($order);
    $orderItems = $spApi->orders()->getOrderItems($order['AmazonOrderId']);
    $this->syncOrderItems($order['AmazonOrderId'], $orderItems);
}

场景二：库存自动更新 ​

场景描述：本地库存变化时，自动更新亚马逊库存

使用 API：Inventory API, Feeds API

php
<?php
$feedData = $this->buildInventoryFeed($localInventory);

$feedDocument = $spApi->feeds()->createFeedDocument([
    'contentType' => 'text/tab-separated-values',
    'content' => $feedData,
]);

$feed = $spApi->feeds()->createFeed([
    'feedType' => 'POST_INVENTORY_AVAILABILITY_DATA',
    'marketplaceIds' => ['ATVPDKIKX0DER'],
    'inputFeedDocumentId' => $feedDocument['feedDocumentId'],
]);

场景三：商品自动刊登 ​

场景描述：批量创建商品 Listing

使用 API：Listings Items API

php
<?php
$result = $spApi->listings()->putListingsItem([
    'sellerId' => 'SELLER_ID',
    'sku' => 'SKU123',
    'marketplaceIds' => ['ATVPDKIKX0DER'],
    'body' => [
        'productType' => 'PRODUCT',
        'patches' => [
            [
                'op' => 'replace',
                'path' => '/attributes/title',
                'value' => [
                    'value' => '商品标题',
                    'language_tag' => 'en_US',
                ],
            ],
        ],
    ],
]);

场景四：物流信息回传 ​

场景描述：发货后自动上传物流单号到亚马逊

使用 API：Orders API, Shipping API

php
<?php
$result = $spApi->orders()->confirmShipment([
    'amazonOrderId' => 'ORDER_ID',
    'packageDetails' => [
        'packageReferenceId' => 'PKG001',
        'carrierCode' => 'UPS',
        'trackingNumber' => 'TRACKING_NUMBER',
        'shipDate' => date('Y-m-d\TH:i:s\Z'),
    ],
]);

场景五：财务报表下载 ​

场景描述：定期下载财务报表进行对账

使用 API：Reports API

php
<?php
$report = $spApi->reports()->createReport([
    'reportType' => 'GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE',
    'dataStartTime' => '2024-01-01T00:00:00Z',
    'dataEndTime' => '2024-01-31T23:59:59Z',
    'marketplaceIds' => ['ATVPDKIKX0DER'],
]);

$reportId = $report['reportId'];
while (true) {
    $status = $spApi->reports()->getReport($reportId);
    if ($status['processingStatus'] === 'DONE') {
        $document = $spApi->reports()->getReportDocument($status['reportDocumentId']);
        $this->downloadReport($document['url']);
        break;
    }
    sleep(30);
}

技术要求 ​

前置知识 ​

  • PHP 8.0+ 基础语法
  • HTTP 协议基础
  • RESTful API 概念
  • OAuth 2.0 认证流程
  • JSON 数据格式

开发环境 ​

组件版本要求说明
PHP>= 8.0推荐 8.1+
Composer>= 2.0依赖管理
Guzzle HTTP>= 7.0HTTP 客户端
OpenSSL>= 1.1.1加密支持

亚马逊账号要求 ​

  • 专业卖家账号或供应商账号
  • 已注册开发者账号
  • 已创建 SP-API 应用

知识点总结 ​

核心要点 ​

  1. SP-API 是亚马逊官方 RESTful API，替代旧的 MWS
  2. OAuth 2.0 + AWS Signature V4 双重认证，安全性更高
  3. 50+ API 模块，200+ 接口操作，覆盖所有业务场景
  4. 六阶段学习路径，从入门到生产部署
  5. 沙箱测试环境，支持安全开发测试

易错点回顾 ​

  1. 认证流程复杂：需要正确实现 LWA 和 AWS 双重签名
  2. 限流机制：每个 API 有不同的限流规则，需要实现限流控制
  3. 令牌管理：access token 有效期短，需要及时刷新
  4. 错误处理：需要针对不同错误码实现不同的处理策略
  5. 多市场处理：需要正确处理不同市场的数据差异

拓展参考资料 ​

官方文档 ​

进阶学习路径 ​

  1. 基础阶段：完成认证授权 → 核心 API 调用
  2. 进阶阶段：通知订阅 → 受限数据访问
  3. 高级阶段：沙箱测试 → 生产部署
  4. 实战阶段：独立完成企业级项目

准备好了吗？ 让我们从 SP-API 概览 开始你的学习之旅! 🚀