README

Selling Partner API for PHP

一个用于连接 Amazon Selling Partner API 的 PHP 库。

注意

如果您在寻找此包 v5 版本的文档，可以在这里找到。

由 Tesmo 赞助。

功能

支持所有 Selling Partner API 操作（针对卖家和供应商），截至 2024 年 6 月 19 日
自动为所有需要它们的调用生成受限制数据令牌 - 无需额外调用 Tokens API
包括用于上传和下载数据包/报告文档的 Document 辅助类
可以处理 OAuth 完整流程，从构建授权 URL 到将授权代码转换为刷新令牌

安装

composer require jlevers/selling-partner-api

贡献

有关详细信息，请参阅CONTRIBUTING.md。

入门

先决条件

要开始，您需要一个已批准的卖家API开发者账户和SP API应用程序凭据，您可以在卖家中心创建新的SP API应用程序来获取。

设置

SellingPartnerApi 类充当工厂，用于生成卖家和供应商API连接器实例。它的 seller() 和 vendor() 方法各自接受一组相同（可选地，命名）的参数。其基本用法如下

use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;

$connector = SellingPartnerApi::seller(
    clientId: 'amzn1.application-oa2-client.asdfqwertyuiop...',
    clientSecret: 'amzn1.oa2-cs.v1.1234567890asdfghjkl...',
    refreshToken: 'Atzr|IwEBIA...',
    endpoint: Endpoint::NA,  // Or Endpoint::EU, Endpoint::FE, Endpoint::NA_SANDBOX, etc.
);

注意

旧版本的卖家API使用AWS IAM凭据进行身份验证，因此该库有额外的AWS配置选项。如果您正在从旧版本的此库升级并且对您的AWS凭据不知如何处理，请忽略它们。SP API不再通过AWS IAM角色或用户进行身份验证。

现在您有一个卖家API连接器实例，您可以开始调用API。连接器实例具有针对每个API段的（例如，sellers、orders、fba-inbound）方法，并且您可以像这样访问它们

$ordersApi = $connector->ordersV0();
$response = $ordersApi->getOrders(
    createdAfter: new DateTime('2024-01-01'),
    marketplaceIds: ['ATVPDKIKX0DER'],
);

一旦您获得响应，您可以通过 $response->json() 访问原始JSON响应，或者通过调用 $response->dto() 自动将响应解析为DTO。一旦响应转换为DTO，您可以通过DTO的属性访问数据。例如，您可以获取第一笔订单的购买日期如下

$dto = $response->dto();
$purchaseDate = $dto->payload->orders[0]->purchaseDate;

有关如何处理响应的更多详细信息，请参阅处理响应部分，有关如何使用DTO的更多详细信息，请参阅处理DTOs部分。

配置选项

SellingPartnerApi::seller() 和 SellingPartnerApi::vendor() 构建方法接受以下参数

clientId (string)：必需。用于执行API请求的SP API应用程序的LWA客户端ID。
clientSecret (string)：必需。用于执行API请求的SP API应用程序的LWA客户端密钥。
refreshToken (string)：用于执行API请求的SP API应用程序的LWA刷新令牌。必需，除非您仅使用无授权操作。
endpoint：必需。一个SellingPartnerApi\Enums\Endpoint枚举实例。主要端点是 Endpoint::NA、Endpoint::EU 和 Endpoint::FE。沙盒端点是 Endpoint::NA_SANDBOX、Endpoint::EU_SANDBOX 和 Endpoint::FE_SANDBOX。
dataElements (array)：可选。传递给受限操作的数组中的数据元素。有关更多详细信息，请参阅受限操作部分。
delegatee (string)：可选。代表其生成RDT的应用程序ID。
authenticationClient (GuzzleHttp\Client)：用于从刷新令牌生成访问令牌的Guzzle客户端实例。如果不提供，将使用默认的Saloon Guzzle客户端。
缓存（SellingPartnerApi\Contracts\TokenCache）：一个缓存接口实例，用于缓存访问令牌。如果未提供，将使用基本内存缓存。如果设置为null，则禁用缓存。

调试

要获取详细的调试输出，您可以利用Saloon的调试钩子。此包是在Saloon之上构建的，因此任何在Saloon中工作的事物在这里也将工作。例如，要调试请求

use SellingPartnerApi\SellingPartnerApi;

$connector = SellingPartnerApi::seller(
    clientId: 'amzn1.application-oa2-client.asdfqwertyuiop...',
    clientSecret: 'amzn1.oa2-cs.v1.1234567890asdfghjkl...',
    refreshToken: 'Atzr|IwEBIA...',
    endpoint: Endpoint::NA,
);

$connector->debugRequest(
    function (PendingRequest $pendingRequest, RequestInterface $psrRequest) {
        dd($pendingRequest->headers()->all(), $psrRequest);
    }
);

然后像平常一样使用连接器发起请求，每次发起请求时都会调用上面的闭包。您也可以以类似的方式调试响应 - 查看有关Saloon文档以获取更多详细信息。

如果您想将调试数据输出到文件，可以使用SellingPartnerApi::debugRequestToFile()、SellingPartnerApi::debugResponseToFile()和SellingPartnerApi::debugToFile()方法。这些方法都接受一个$outputPath参数和一个可选的$die参数。

处理响应

如前所述，所有端点方法都返回一个Saloon\Response实例。您可以通过$response->json()访问原始JSON响应，或者通过调用$response->dto()自动将响应解析为DTO。一旦响应转换为DTO，您就可以通过DTO的属性（如下所述）访问数据。Saloon的响应文档提供了使用Saloon响应的综合指南，包括检索头、状态等。

处理DTOs

一些方法接受DTO作为参数。例如，订单API中的confirmShipment方法接受一个ConfirmShipmentRequest DTO作为参数。您可以像这样调用confirmShipment

<?php

use SellingPartnerApi\Seller\OrdersV0\Dto;
use SellingPartnerApi\SellingPartnerApi;

$confirmShipmentRequest = new Dto\ConfirmShipmentRequest(
    packageDetail: new Dto\PackageDetail(
        packageReferenceId: 'PKG123',
        carrierCode: 'USPS',
        trackingNumber: 'ASDF1234567890',
        shipDate: new DateTime('2024-01-01 12:00:00'),
        orderItems: [
            new Dto\ConfirmShipmentOrderItem(
                orderItemId: '1234567890',
                quantity: 1,
            ),
            new Dto\ConfirmShipmentOrderItem(
                orderItemId: '0987654321',
                quantity: 2,
            )
        ],
    ),
    marketplaceId: 'ATVPDKIKX0DER',
);

$response = $ordersApi->confirmShipment(
    orderId: '123-4567890-1234567',
    confirmShipmentRequest: $confirmShipmentRequest,
);

支持的API段

每个API访问方法都包含API的版本。这允许在单个包版本中访问同一API的多个版本。这使得方法名称稍微有些丑陋，但允许同时使用同一API段的旧版和新版，这通常很有用。这也意味着如果引入了现有API的新版本，库可以更新以包含该新版本，而不会引入破坏性更改。

卖家API

卖家API通过SellingPartnerApi::seller()类访问

<?php
use SellingPartnerApi\SellingPartnerApi;

$sellerConnector = SellingPartnerApi::seller(/* ... */);

亚马逊仓储和配送API（v2024-05-09）（文档）

$amazonWarehousingAndDistributionApi = $sellerConnector->amazonWarehousingAndDistributionV20240509();

应用管理API（v2023-11-30）（文档）

$applicationManagementApi = $sellerConnector->applicationManagementV20231130();

A+内容API（v2020-11-01）（文档）

$aPlusContentApi = $sellerConnector->aPlusContentV20201101();

目录项API（v2022-04-01）（文档）

$catalogItemsApi = $sellerConnector->catalogItemsV20220401();

目录项API（v2021-12-01）（文档）

$catalogItemsApi = $sellerConnector->catalogItemsV20211201();

目录项API（v0）（文档）

$catalogItemsApi = $sellerConnector->catalogItemsV0();

数据亭API（v2023-11-15）（文档）

$dataKioskApi = $sellerConnector->dataKioskV20231115();

EasyShip API（v2022-03-23）（文档）

$easyShipApi = $sellerConnector->easyShipV20220323();

FBA入站API（v2024-03-20）（文档）

$fbaInboundApi = $sellerConnector->fbaInboundV20240320();

FBA入站API（v0）（文档）

$fbaInboundApi = $sellerConnector->fbaInboundV0();

FBA 入库资格 API (v1) (文档)

$fbaInboundEligibility = $sellerConnector->fbaInboundEligibilityV1();

FBA 库存 API (v1) (文档)

$fbaInventoryApi = $sellerConnector->fbaInventoryV1();

FBA 出库 API (v2020-07-01) (文档)

$fbaOutboundApi = $sellerConnector->fbaOutboundV20200701();

Feeds API (v2021-06-30) (文档)

$feedsApi = $sellerConnector->feedsV20210630();

财务 API (v0) (文档)

$financesApi = $sellerConnector->financesV0();

商品列表 API (v2021-08-01) (文档)

$listingsItemsApi = $sellerConnector->listingsItemsV20210801();

商品列表 API (v2020-09-01) (文档)

$listingsItemsApi = $sellerConnector->listingsItemsV20200901();

商品列表限制 API (v2021-08-01) (文档)

$listingsRestrictionsApi = $sellerConnector->listingsRestrictionsV20210801();

卖家履行 API (v0) (文档)

$merchantFulfillmentApi = $sellerConnector->merchantFulfillmentV0();

消息 API (v1) (文档)

$messagingApi = $sellerConnector->messagingV1();

通知 API (v1) (文档)

$notificationsApi = $sellerConnector->notificationsV1();

订单 API (v0) (文档)

$ordersApi = $sellerConnector->ordersV0();

产品费用 API (v0) (文档)

$productFeesApi = $sellerConnector->productFeesV0();

产品定价 API (v2022-05-01) (文档)

$productPricingApi = $sellerConnector->productPricingV20220501();

产品定价 API (v0) (文档)

$productPricingApi = $sellerConnector->productPricingV0();

产品类型定义 API (v2020-09-01) (文档)

$productTypeDefinitionsApi = $sellerConnector->productTypeDefinitionsV20200901();

补充 API (v2022-11-07) (文档)

$replenishmentApi = $sellerConnector->replenishmentV20221107();

报告 API (v2021-06-30) (文档)

$reportsApi = $sellerConnector->reportsV20210630();

销售 API (v1) (文档)

$salesApi = $sellerConnector->salesV1();

卖家 API (v1) (文档)

$sellersApi = $sellerConnector->sellersV1();

服务 API (v1) (文档)

$servicesApi = $sellerConnector->servicesV1();

货运发票 API (v0) (文档)

$shipmentInvoicingApi = $sellerConnector->shipmentInvoicingV0();

物流 API (v2) (文档)

$shippingApi = $sellerConnector->shippingV2();

物流 API (v1) (文档)

$shippingApi = $sellerConnector->shippingV1();

征求 API (v1) (文档)

$solicitationsApi = $sellerConnector->solicitationsV1();

供应来源 API (v2020-07-01) (文档)

$supplySourcesApi = $sellerConnector->supplySourcesV20200701();

令牌 API (v2021-03-01) (文档)

$tokensApi = $sellerConnector->tokensV20210301();

转移 API (v2024-06-01) (文档)

$transfersApi = $sellerConnector->transfersV20240601();

上传 API (v2020-11-01) (文档)

$uploadsApi = $sellerConnector->uploadsV20201101();

供应商API

供应商 API 通过 SellingPartnerApi::vendor() 方法访问

<?php
use SellingPartnerApi\SellingPartnerApi;

$vendorConnector = SellingPartnerApi::vendor(/* ... */);

直接履约库存API（v1） （文档）

$directFulfillmentInventoryApi = $vendorConnector->directFulfillmentInventoryV1();

直接履约订单API（v2021-12-28） （文档）

$directFulfillmentOrdersApi = $vendorConnector->directFulfillmentOrdersV20211228();

直接履约订单API（v1） （文档）

$directFulfillmentOrdersApi = $vendorConnector->directFulfillmentOrdersV1();

直接履约付款API（v1） （文档）

$directFulfillmentPaymentsApi = $vendorConnector->directFulfillmentPaymentsV1();

直接履约沙盒API（v2021-10-28） （文档）

$directFulfillmentSandboxApi = $vendorConnector->directFulfillmentSandboxV20211028();

直接履约运输API（v2021-12-28） （文档）

$directFulfillmentShippingApi = $vendorConnector->directFulfillmentShippingV20211228();

直接履约运输API（v1） （文档）

$directFulfillmentShippingApi = $vendorConnector->directFulfillmentShippingV1();

直接履约交易API（v2021-12-28） （文档）

$directFulfillmentTransactionsApi = $vendorConnector->directFulfillmentTransactionsV20211228();

直接履约交易API（v1） （文档）

$directFulfillmentTransactionsApi = $vendorConnector->directFulfillmentTransactionsV1();

发票API（v1） （文档）

$invoicesApi = $vendorConnector->invoicesV1();

订单API（v1） （文档）

$ordersApi = $vendorConnector->ordersV1();

运输API（v1） （文档）

$shipmentsApi = $vendorConnector->shipmentsV1();

交易状态API（v1） （文档）

$transactionStatusApi = $vendorConnector->transactionStatusV1();

受限操作

当调用一个受限操作时，会自动生成受限数据令牌（RDT）。如果您调用接受dataElements参数的受限操作，请在SellingPartnerApi::make()的dataElements参数中指定您想要检索的受限数据元素。目前，只有getOrder、getOrders和getOrderItems是接受dataElements参数的受限操作。

请注意，如果您想要在沙盒端点（例如，Endpoint::NA_SANDBOX）上调用受限操作，您不应该指定任何dataElements。在沙盒中，受限操作不需要RDT。

如果您想代表受托应用程序进行调用，可以在SellingPartnerApi::make()中指定delegatee参数。这将导致连接器为受托应用程序生成令牌，而不是主应用程序。

上传和下载文档

Feeds和Reports API包括涉及将文档上传到和从Amazon上传和下载的操作。此库已集成了对相关DTO（数据传输对象）上的上传和下载文档的支持：ReportDocument、CreateFeedDocumentResponse和FeedDocument，它们分别是调用getReportDocument、createFeedDocument和getFeedDocument的结果。

下载报告文档

use SellingPartnerApi\SellingPartnerApi;

$reportType = 'GET_MERCHANT_LISTINGS_DATA';
// Assume we already got a report document ID from a previous getReport call
$documentId = '1234567890.asdf';

$connector = SellingPartnerApi::seller(/* ... */);
$response = $connector->reportsV20210630()->getReportDocument($documentId, $reportType);

$reportDocument = $response->dto();

/*
 * - Array of arrays, where each sub array corresponds to a row of the report, if this is a TSV, CSV, or XLSX report
 * - A nested associative array (from json_decode) if this is a JSON report
 * - The raw report data if this is a TXT or PDF report
 * - A SimpleXMLElement object if this is an XML report
 */
$contents = $reportDocument->download($reportType);

download方法有三个参数

documentType（字符串）：报告类型（或正在获取的文档结果的馈送类型）。如果您想让您解析文档数据，则此参数是必需的。
preProcess (布尔值): 是否预处理文档数据。如果为 true，则将文档数据解析并格式化为更易用的格式。如果为 false，则返回原始文档文本。默认为 true。
encoding (字符串): 文档数据的编码。默认为 UTF-8。

如果你正在处理大型文档，可以使用 downloadStream() 函数来最小化内存消耗。downloadStream() 返回一个 Psr\Http\Message\StreamInterface 对象。

$streamContents = $reportDocument->downloadStream();  // The raw report stream

上传数据源文档

use SellingPartnerApi\Seller\FeedsV20210630\Dto\CreateFeedDocumentSpecification;
use SellingPartnerApi\Seller\FeedsV20210630\Dto\CreateFeedSpecification;
use SellingPartnerApi\Seller\FeedsV20210630\Responses\CreateFeedDocumentResponse;

$feedType = 'POST_PRODUCT_PRICING_DATA';

$connector = SellingPartnerApi::seller(/* ... */);
$feedsApi = $connector->feedsV20210630();

// Create feed document
$contentType = CreateFeedDocumentResponse::getContentType($feedType);
$createFeedDoc = new CreateFeedDocumentSpecification($contentType);
$createDocumentResponse = $feedsApi->createFeedDocument($createFeedDoc);
$feedDocument = $createDocumentResponse->dto();

// Upload feed contents to document
$feedContents = file_get_contents('your/feed/file.xml');
$feedDocument->upload($feedType, $feedContents);

$createFeedSpec = new CreateFeedSpecification(
    marketplaceIds: ['ATVPDKIKX0DER'],
    inputFeedDocumentId: $feedDocument->feedDocumentId,
    feedType: $feedType,
);

// Create feed with the feed document we just uploaded
$createFeedResponse = $feedsApi->createFeed($createFeedSpec);
$feedId = $createFeedResponse->dto()->feedId;

如果你正在处理无法完全放入内存的feed文档，可以将Guzzle可以转换为流的内容传递给FeedDocument::upload()，而不是字符串。

下载数据源结果文档

此过程与下载报告文档非常类似

use SellingPartnerApi\SellingPartnerApi;

$feedType = 'POST_PRODUCT_PRICING_DATA';
// Assume we already got a feed result document ID from a previous getFeed call
$documentId = '1234567890.asdf';

$connector = SellingPartnerApi::seller(/* ... */);
$response = $connector->feedsV20210630()->getFeedDocument($documentId);
$feedDocument = $response->dto();

$contents = $feedResultDocument->download($feedType);

OAuth

Selling Partner API OAuth流程在此处有完整文档（链接）。我强烈建议在尝试实现OAuth流程之前阅读该页面。

一旦你的SP API应用程序通过指定登录和重定向URI配置了OAuth，你就可以使用这个库的OAuth连接器来生成所需的授权URI，并将传入的OAuth请求转换为有效的客户端凭据。

构建授权URI

要创建一个特定于销售者的授权URI，你需要

你的应用程序ID，LWA客户端ID和密钥
一个与你在卖家中心应用程序配置中指定的重定向URI相匹配的重定向URI
一个base64编码的状态字符串，该字符串用于验证授权请求没有被修改

然后，你只需做以下操作

use SellingPartnerApi\Enums\Marketplace;
use SellingPartnerApi\OAuth;

$oauth = new OAuth(
    clientId: 'amzn1.application-oa2-client.asdfqwertyuiop...',
    clientSecret: 'amzn1.oa2-cs.v1.1234567890asdfghjkl...',
    redirectUri: 'https://example.com/redirect',
);

$authUrl = $oauth->getAuthorizationUri(
    appId: 'amzn1.sp.solution...',
    state: 'unique-base64-encoded-string',
    // The marketplace that you want to authorize the seller in
    marketplace: Marketplace::US,
    // If your app is published on the Marketplace Appstore, pass this parameter:
    // draftApp: false,
);

// Redirect your user to $authUrl...

从授权码生成刷新令牌

OAuth方程的另一半是接收亚马逊在用户完成授权流程后发送的入站请求，并将该请求中的授权代码转换为有效的SP API凭据。亚马逊将授权代码发送到授权URI中指定的重定向URI，在 spapi_oauth_code 查询参数中。一旦你确认传入的 state 参数与传递给 OAuth::getAuthorizationUri() 的 state 值匹配，你可以生成如下刷新令牌

use SellingPartnerApi\OAuth;

// Parse query parameters from inbound Amazon request...
$authCode = $query['spapi_oauth_code'];

$oauth = new OAuth(
    clientId: 'amzn1.application-oa2-client.asdfqwertyuiop...',
    clientSecret: 'amzn1.oa2-cs.v1.1234567890asdfghjkl...',
    redirectUri: 'https://example.com/redirect',
);

$refreshToken = $oauth->getRefreshToken($authCode);

现在，你可以将 $refreshToken 传递给 SellingPartnerApi::seller()，以便以授权的销售者身份调用SP API！

命名规范

尽可能情况下，此包中类的名称、方法和属性的名称与Selling Partner API文档中使用的名称相同。在某些情况下，这并不成立，例如，SP API文档本身就不一致：例如，在某些情况下，SP API文档使用 UpperCamelCase 而不是 camelCase 来命名属性，在这种情况下，此包中的属性名称使用 camelCase。方法名称使用 camelCase，DTO名称使用 UpperCamelCase。

我们尽量避免维护冗余的文档集，而是尽可能链接到官方SP API文档。如果对某个特定方法或DTO的使用方式不确定，请查看官方SP API文档的相关部分。

jlevers / selling-partner-api

维护者

详细信息