# Working with SP API credentials

This project provides a [Laravel-native interface](https://github.com/highsidelabs/laravel-spapi?tab=readme-ov-file#usage-1) for interacting with the Selling Partner API via the `highsidelabs/laravel-spapi` package. It includes `Seller` and `Credentials` models for managing and storing SP API credentials.

{% hint style="info" %}
Note that whenever the `Credentials` and/or `Seller` models are referenced, I'm talking about the `App\Models\Credentials` and `App\Models\Seller` classes, respectively.
{% endhint %}

This section will refer to two different types of credentials:

1. **Master credentials.** These are credentials specified in your `.env`, which are used as the basis for OAuth, notifications setup, and all other SP API operations unless another set of credentials is explicitly specified.
2. **Child credentials.** These are dynamic credentials that are stored in the database, either as a result of manually creating them via the `Credentials` model, or from a seller authorizing your app via the OAuth flow.

### Master credentials

You can specify a set of master SP API credentials by filling in the `SPAPI_LWA_*` environment variables. Master credentials have a few different use cases with slightly varying setups:

* If you're only working with a single seller account in a single region, you only need to fill in the refresh token for that region, and specify which region you want to use in the `SPAPI_LWA_DEFAULT_REGION` environment variable. You can then retrieve your credentials with `Credentials::master()`.
* If you have a single seller with credentials for multiple regions, you can pass the region code for the credentials you want to retrieve to `Credentials::master()`, like `Credentials::master('EU')`.
* In multi-seller setups, master credentials are used for certain operations that need to be done with your own internal SP API credentials, rather than a set of credentials from a seller who has authorized your app via OAuth. Examples include OAuth and subscribing to notifications.

Master credentials are required for this system to work. After you specify a set of master credentials, or update your existing master credentials, run `php artisan update-master-credentials` to fetch the merchant IDs for the credentials and store them in the database.

### Child credentials

{% hint style="warning" %}
If you're only working with a single seller account, you can skip this section. Master credentials are all you need.
{% endhint %}

As mentioned above, the `Credentials`and `Seller` models make it possible to store credentials in the database, and to associate multiple sets of Selling Partner API credentials with a particular seller. The reason a given `Seller` can have multiple sets of credentials is because Selling Partner API credentials are different across regions (and across marketplaces within the Far East region), so a single seller could in theory have up to 5 sets of Selling Partner API credentials (one set each for the North America, Europe, Australia, Japan, and Singapore regions/marketplaces). This package further expands on that setup by associating the `Seller` model with a `User` model, so a single user in the Laravel app can have custody of multiple sellers.

You can either manually create sellers and credentials by using the model classes, or you can authorize external sellers on your app using OAuth.

### Interacting with the Selling Partner API

Once you have a set of credentials set up in your application, you can use them to interact with the SP API by using the `Credentials` model. If you're working with master credentials, that's as simple as this:

```php
$credentials = Credentials::master();
```

In a more complex, multi-seller setting, retrieving the North America credentials for a particular seller looks like this:

```php
$seller = Auth::user()->sellers()->first();
$credentials = $seller->credentials->where('region', 'NA')->first();
```

The `Credentials::sellerConnector()` and `Credentials::vendorConnector()` methods produce `SellingPartnerApi\Seller\SellerConnector` and `SellingPartnerApi\Vendor\VendorConnector` instances from the [jlevers/selling-partner-api](https://github.com/jlevers/selling-partner-api) library, which you can use to make requests to the SP API on behalf of the seller or vendor. For instance:

```php
/** @var SellingPartnerApi\Seller\SellersV1\Api $api */
$api = $credentials->sellerConnector()->sellersV1();

try {
    $result = $api->getMarketplaceParticipations();
    $dto = $result->dto();
} catch (RequestException $e) {
    $responseBody = $e->getResponse()->json();
}
```

More info on this behavior in the `highsidelabs/laravel-spapi` documentation, [here](https://github.com/highsidelabs/laravel-spapi?tab=readme-ov-file#usage-1).