highsidelabs / amazon-business-api
PHP client for Amazon's Business API
Installs: 8 078
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 0
Forks: 3
Open Issues: 3
Requires
- php: >=7.3
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^6.0|^7.0
Requires (Dev)
README
Amazon Business API for PHP
A PHP library for connecting to Amazon's Business API.
Related packages
jlevers/selling-partner-api
: A PHP library for Amazon's Selling Partner API, with a near-identical interface to this package. Our most popular package.highsidelabs/laravel-spapi
: A Laravel wrapper for the package above, making SP API integration in Laravel projects quick and easy.highsidelabs/walmart-api
: A PHP library for Walmart's seller and supplier APIs, including the Marketplace, Drop Ship Vendor, Content Provider, and Warehouse Supplier APIs.
This package is developed and maintained by Highside Labs. If you need support integrating with Amazon's (or any other e-commerce platform's) APIs, we're happy to help! Shoot us an email at hi@highsidelabs.co. We'd love to hear from you :)
If you've found any of our packages useful, please consider becoming a Sponsor, or making a donation via the button below. We appreciate any and all support you can provide!
(There is a more in-depth guide to using this package on our blog, here.)
Features
- Supports all Amazon Business API operations as of 11/13/2022 (see here for links to documentation for all calls)
- Supports applications made with both IAM user and IAM role ARNs (docs)
Installation
composer require highsidelabs/amazon-business-api
Table of Contents
Check out the Getting Started section below for a quick overview.
This README is divided into several sections:
- Setup
- Examples
- Debug mode
- Supported API segments
- Working with model classes
- Response headers
- Custom request authorization
- Custom request signing
Getting Started
We wrote a blog post with more detailed instructions on connecting to the Amazon Business API here. Check it out if you need more help getting set up.
Prerequisites
You need a few things to get started:
- A Amazon Business API developer account
- An AWS IAM user or role configured for use with the Amazon Business API
- An Amazon Business API application
If you're looking for more information on how to set those things up, check out this blog post. It provides a detailed walkthrough of the whole setup process. That guide refers to the Selling Partner API, but all the setup steps are the same for the Amazon Business API.
Setup
The Configuration
constructor takes a single argument: an associative array with all the configuration information that's needed to connect to the Amazon Business API:
$config = new AmazonBusinessApi\Configuration([ 'lwaClientId' => '<LWA client ID>', 'lwaClientSecret' => '<LWA client secret>', 'lwaRefreshToken' => '<LWA refresh token>', 'awsAccessKeyId' => '<AWS access key ID>', 'awsSecretAccessKey' => '<AWS secret access key>', // If you're not working in the North American marketplace, change // this to another endpoint from lib/Endpoint.php 'endpoint' => AmazonBusinessApi\Endpoint::NA, ]);
If you created your Amazon Business API application using an IAM role ARN instead of a user ARN, pass that role ARN in the configuration array:
$config = new AmazonBusinessApi\Configuration([ 'lwaClientId' => '<LWA client ID>', 'lwaClientSecret' => '<LWA client secret>', 'lwaRefreshToken' => '<LWA refresh token>', 'awsAccessKeyId' => '<AWS access key ID>', 'awsSecretAccessKey' => '<AWS secret access key>', // If you're not working in the North American marketplace, change // this to another endpoint from lib/Endpoint.php 'endpoint' => AmazonBusinessApi\Endpoint::NA, 'roleArn' => '<Role ARN>', ]);
Getter and setter methods exist for the Configuration
class's lwaClientId
, lwaClientSecret
, lwaRefreshToken
, awsAccessKeyId
, awsSecretAccessKey
, and endpoint
properties. The methods are named in accordance with the name of the property they interact with: getLwaClientId
, setLwaClientId
, getLwaClientSecret
, etc.
$config
can then be passed into the constructor of any AmazonBusinessApi\Api\*Api
class. See the Example
section for a complete example.
Configuration options
The array passed to the Configuration
constructor accepts the following keys:
lwaClientId (string)
: Required. The LWA client ID of the SP API application to use to execute API requests.lwaClientSecret (string)
: Required. The LWA client secret of the SP API application to use to execute API requests.lwaRefreshToken (string)
: Required. The LWA refresh token of the SP API application to use to execute API requests.awsAccessKeyId (string)
: Required. AWS IAM user Access Key ID with SP API ExecuteAPI permissions.awsSecretAccessKey (string)
: Required. AWS IAM user Secret Access Key with SP API ExecuteAPI permissions.endpoint (array)
: Required. An array containing aurl
key (the endpoint URL) and aregion
key (the AWS region). There are predefined constants for these arrays inlib/Endpoint.php
: (NA
,EU
, andFE
. See here for more details.accessToken (string)
: An access token generated from the refresh token.accessTokenExpiration (int)
: A Unix timestamp corresponding to the time when theaccessToken
expires. IfaccessToken
is given,accessTokenExpiration
is required (and vice versa).onUpdateCredentials (callable|Closure)
: A callback function to call when a new access token is generated. The function should accept a single argument of typeAmazonBusinessApi\Credentials
.roleArn (string)
: If you set up your Amazon Business API application with an AWS IAM role ARN instead of a user ARN, pass that ARN here.authenticationClient (GuzzleHttp\ClientInterface)
: OptionalGuzzleHttp\ClientInterface
object that will be used to generate the access token from the refresh tokenauthorizationSigner (AmazonBusinessApi\Contract\AuthorizationSignerContract)
: OptionalAmazonBusinessApi\Contract\AuthorizationSignerContract
implementation. See Custom Authorization Signer sectionrequestSigner (AmazonBusinessApi\Contract\RequestSignerContract)
: OptionalAmazonBusinessApi\Contract\RequestSignerContract
implementation. See Custom Request Signer section.
Examples
This example assumes you have access to the Product Search
Amazon Business API role, but the general format applies to any Amazon Business API request.
<?php require_once(__DIR__ . '/vendor/autoload.php'); use AmazonBusinessApi\Api\ProductSearchV20200826Api as ProductSearchApi; use AmazonBusinessApi\Configuration; use AmazonBusinessApi\Endpoint; $config = new Configuration([ 'lwaClientId' => 'amzn1.application-oa2-client.....', 'lwaClientSecret' => 'abcd....', 'lwaRefreshToken' => 'Aztr|IwEBI....', 'awsAccessKeyId' => 'AKIA....', 'awsSecretAccessKey' => 'ABCD....', // If you're not working in the North American marketplace, change // this to another endpoint from lib/Endpoint.php 'endpoint' => Endpoint::NA ]); $api = new ProductSearchApi($config); try { $result = $api->productsRequest('B0B96H7LGX', 'US', 'en_US', 'johndoe@acmecorp.com'); print_r($result); } catch (Exception $e) { echo 'Exception when calling ProductSearchApi->productsRequest: ', $e->getMessage(), PHP_EOL; } ?>
Debug mode
To get debugging output when you make an API request, you can call $config->setDebug(true)
. By default, debug output goes to stdout
via php://output
, but you can redirect it a file with $config->setDebugFile('<path>')
.
<?php require_once(__DIR__ . '/vendor/autoload.php'); use AmazonBusinessApi\Configuration; $config = new Configuration([/* ... */]); $config->setDebug(true); // To redirect debug info to a file: $config->setDebugFile('./debug.log');
Supported API segments
Each API class name contains the API's version. This allows for multiple versions of the same API to be accessible in a single version of this package. It makes the class names a little uglier, but allows for simultaneously using new and old versions of the same API segment, which is often useful. The uglier names can be remedied by formatting use
statements like so:
use AmazonBusinessApi\Api\ProductSearchV20200826Api as ProductSearchApi; use AmazonBusinessApi\Model\ProductSearchV20200826 as ProductSearch;
It also means that if a new version of an existing API is introduced, the library can be updated to include that new version without introducing breaking changes.
- Document API (v2021-09-30) (formerly called the Invoice Download API)
- Ordering API (v1)
- Product Search API (v2021-08-26)
- Reconciliation API (v2021-01-08)
- Reporting API (v2021-01-08)
- User Management API (v2021-08-30)
Working with model classes
Most operations have one or more models associated with it. These models are classes that contain the data needed to make a certain kind of request to the API, or contain the data returned by a given request type. All of the models share the same general interface: you can either specify all the model's attributes during initialization, or set each attribute after the fact. Here's an example using the User Management API's AccountHolder
model (docs), (source).
The AccountHolder
model has three attributes: email
, given_name
, and family_name
. (If you're wondering how to figure out which attributes a model has on your own, check out the docs
link above.) To create an instance of the AccountHolder
model with all those attributes set:
$accountHolder = new AmazonBusinessApi\Model\UserManagementV20210830Api\AccountHolder([ 'email' => 'janedoe@acmecorp.com', 'given_name' => 'Jane', 'family_name' => 'Doe' ]);
Alternatively, you can create an instance of the Buyer
model and then populate its fields:
$accountHolder = new AmazonBusinessApi\Model\UserManagementV20210830Api\AccountHolder(); $accountHolder->email = 'janedoe@acmecorp.com'; $accountHolder->givenName = 'Jane'; $accountHolder->familyName = 'Doe';
Each model also has the property accessors you might expect:
$accountHolder->email; // -> 'janedoe@acmecorp.com' $accountHolder->givenName; // -> 'Jane' $accountHolder->familyName; // -> 'Doe'
Models can (and usually do) have other models as attributes:
$requestBody = new AmazonBusinessApi\Model\UserManagementV20210830Api\CreateBusinessUserAccountRequest([ // ... 'account_holder' => $accountHolder, // ... ]); $requestBody->accountHolder; // -> [AccountHolder instance] $requestBody->requestBody->email; // -> 'janedoe@acmecorp.com'
If a model attribute is supposed to be an array, its type signature will be something like ModelClass[]
(note the trailing []
). For instance, the OrderingV1Api
's placeOrder
method takes a model named PlaceOrderRequest
with an attribute called line_items
. The type for line_items
is RequestLineItem[]
, and the attribute should be set like so:
use AmazonBusinessApi\Model\OrderingV1; $placeOrderRequest = new OrderingV1\PlaceOrderRequest([ // ... 'line_items' => [ new OrderingV1\RequestLineItem([ 'quantity' => 1, // ... ]), new OrderingV1\RequestLineItem([ 'quantity' => 2, // ... ]), ], // ... ]);
Response headers
Amazon includes some useful headers with each SP API response. If you need those for any reason, you can get an associative array of response headers by calling getHeaders()
on the response object. For instance:
<?php require_once(__DIR__ . '/vendor/autoload.php'); use AmazonBusinessApi\Api\ProductSearchV20200826Api as ProductSearchApi; use AmazonBusinessApi\Configuration; use AmazonBusinessApi\Endpoint; $config = new Configuration([...]); $api = new ProductSearchApi($config); try { $result = $api->productsRequest('B0B96H7LGX', 'US', 'en_US', 'johndoe@acmecorp.com'); $headers = $result->headers; print_r($headers); } catch (Exception $e) { echo 'Exception when calling ProductSearchApi->productsRequest: ', $e->getMessage(), PHP_EOL; }
Custom Authorization Signer
You may need to do custom operations while signing the API request. You can create a custom authorization signer by creating an implementation of the AuthorizationSignerContract interface and passing it into the Configuration
constructor array.
// CustomAuthorizationSigner.php use Psr\Http\Message\RequestInterface; use AmazonBusinessApi\Contract\AuthorizationSignerContract; class CustomAuthorizationSigner implements AuthorizationSignerContract { public function sign(RequestInterface $request, Credentials $credentials): RequestInterface { // Calculate request signature and request date. $requestDate = '20220426T202300Z'; $signatureHeaderValue = 'some calculated signature value'; $signedRequest = $request ->withHeader('Authorization', $signatureHeaderValue) ->withHeader('x-amz-date', $requestDate); return $signedRequest; } // ... } // Consumer code <?php require_once(__DIR__ . '/vendor/autoload.php'); use AmazonBusinessApi\Api\ProductSearchV20200826Api as ProductSearchApi; use AmazonBusinessApi\Configuration; use AmazonBusinessApi\Endpoint; use CustomAuthorizationSigner; $config = new Configuration([ ..., 'authorizationSigner' => new CustomAuthorizationSigner(), ]); $api = new ProductSearchApi($config); try { $result = $api->productsRequest('B0B96H7LGX', 'US', 'en_US', 'johndoe@acmecorp.com'); print_r($result); } catch (Exception $e) { echo 'Exception when calling ProductSearchApi->productsRequest: ', $e->getMessage(), PHP_EOL; }
Custom Request Signer
You may also need to customize the entire request signing process – for instance, if you need to call an external service in the process of signing the request. You can do so by creating an implementation of the RequestSignerContract interface, and passing an instance of it into the Configuration
constructor array.
// RemoteRequestSigner.php use Psr\Http\Message\RequestInterface; use AmazonBusinessApi\Contract\RequestSignerContract; class RemoteRequestSigner implements RequestSignerContract { public function signRequest(RequestInterface $request): RequestInterface { // Sign request by sending HTTP call // to external/separate service instance. return $signedRequest; } } // Consumer code <?php require_once(__DIR__ . '/vendor/autoload.php'); use AmazonBusinessApi\Api\ProductSearchV20200826Api as ProductSearchApi; use AmazonBusinessApi\Configuration; use AmazonBusinessApi\Endpoint; use RemoteRequestSigner; $config = new Configuration([ ..., 'requestSigner' => new RemoteRequestSigner(), ]); $api = new ProductSearchApi($config); try { $result = $api->productsRequest('B0B96H7LGX', 'US', 'en_US', 'johndoe@acmecorp.com'); print_r($result); } catch (Exception $e) { echo 'Exception when calling ProductSearchApi->productsRequest: ', $e->getMessage(), PHP_EOL; }