7.4 KiB

Raw Permalink Blame History

Selling Partner API JavaScript client library for Node.js (v18 or later)

About this library

This library is to help SP-API developers to create an app in JavaScript on Node.js easier than calling HTTP endpoints directly. This library comes with the following features.

Login with Amazon (LWA) helper that does OAuth token refresh flow.
This library takes care of HTTP communication with SP-API endpoints with a help of superagent, so you can call SP-API by just calling a right method of library that corresponds to SP-API operation.
Calling SP-API requires non-standard x-amz-access-token HTTP request header in request. The SDK generated by this library supports to include this header with token value you specify.
SP-API operaitons to handle restricted data are categorized as "Restricted Operations", which requires "Restricted Data Token" (RDT) instead of access token for tighter security. Calling restricted operation involves two seprate steps, one of wihch is calling Tokens API to retrieve RDT and the other of which is calling protected operation with RDT. This library helps to compbine these two steps into single library call.

Installation and Generating SDK

Please note this library doesn't include SDK. You need to generate SDK with the template and script files included in this library.

Prerequisites for SDK Generation

Java version 7 or higher
swagger-codegen-cli (swagger-codegen-cli-2.4.29) is recommended.
- Download swagger-codegen-cli JAR file and store it. You will need its path later when generating SDK.
Node.js v18 or higher.

CAUTION: Please be aware that there are two major known issues with the latest JavaScript client library.

If you use swagger-codegen-cli newer than 2.4.29 (such as 2.4.30 or 3.x), there is a known compatibility issue with SP-API models that makes generating SDK fail. We recommend that you use swagger-codegen-cli-2.4.29 specifically.
Swagger codegen tool fails to generate SDK for "Merchant Fulfillment V0 API." For workaround, you need to modify a part of the API model file "merchantFulfillmentV0.json"

Download swagger-codegen-cli JAR file

We use swagger-codegen-cli executable JAR file. You can download it by the following command.

$ wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.29/swagger-codegen-cli-2.4.29.jar

Installing dependencies

Change the directory to <package root>/src. Run the following command to install dependencies in Node.js environment.

$ npm install

Download API models and Generate SDK

Go to <package root>/src directory which is under the package root. In this directory you should be able to find generate-js-sdk.sh shell script file. Run this script as the command line below.

$ ./generate-js-sdk.sh -j <your path to swagger-codegen-cli-2.4.X.jar>

You will find models directory and sdk directory under the package root.

models: directory contains API models cloned from SP-API GitHub.
sdk: directory contains generated JavaScript SDK.

Modify Merchant Fulfillment API model file to avoid error during SDK generation

If you want to call Merchant Fulfillment API with the generated SDK, you need to follow this instruction. There is an fatal known issue in generating Merchant Fulfillment API library. If downloading API models is successful, you should be able to find merchantFulfillmentV0.json file In <package root>/models/merchant-fulfillment-api-model directory. Open this file with an editor and find the following part.

"AvailableFormatOptionsForLabel": {
      "$ref": "#/definitions/AvailableFormatOptionsForLabelList"
},

Since this part causes a fatal error in SDK generation for JavaScript, please replace this part with the following snipet.

"AvailableFormatOptionsForLabel": {
    "type": "array",
    "description": "The available label formats.",
    "items": {
        "$ref": "#/definitions/LabelFormatOption"
    }
},

After modification, please run the shell script (generate-js-sdk.sh) again but you should type 'n' to the prompt that asks whether to download models again.

$ ./generate-js-sdk.sh -j ~/devbin/swagger-codegen-cli-2.4.29.jar
Found <package root>/models already exists. Would you like to delete all the files under '<package root>/models' and clone again? [y/n]: n # answer 'n' otherwise modification will be overwritten.

With the correct modification in merchantFulfillmentV0.json, you should be able to find generated SDK for Merchant Fulfillment API.

How to run tests

This library contains a sample programs in sample_node_app directory under the packagte root.
In order to run the program, you need to have LWA credential information saved in the file and name it app.config.mjs and put it <package root>/src directory. Because client secret and refresh token shouldn't be exposed, you must make sure that you don't commit this file to the repository.

export const AppConfig = {
    lwaClientId: "< LWA client ID >",
    lwaClientSecret: "< LWA client secret >",
    lwaRefreshToken: "< LWA refresh token >",
    endpoint: "https://sandbox.sellingpartnerapi-na.amazon.com",
}

After you save app.config.mjs file, you can run the sample program`.

$ npm run test

How to use SDK

Calling SP-API operation with LWA credentials

import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js';

const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-na.amazon.com");
const sellerApi = new SellersApi(sellerApiClient);
sellerApiClient.enableAutoRetrievalAccessToken("<client ID>", "<client secret>", "<refresh token>");
const participations = await sellerApi.getMarketplaceParticipations();

Calling RDT-required SP-API operation with LWA credentials

import { OrdersV0Api, ApiClient as OrdersApiClient } from '../../sdk/src/ordersV0/index.js';

const ordersApiClient = new OrdersApiClient("https://sellingpartnerapi-fe.amazon.com");
ordersApiClient.enableAutoRetrievalRestrictedDataToken("<client ID>",
    "<client secret>", "<refresh token>", ["buyerInfo", "shippingAddress"]);
const ordersApi = new OrdersV0Api(ordersApiClient);
const order = await ordersApi.getOrder("<order ID to retrieve>");

Calling SP-API with access token

In case you manage LWA token refresh flow, you can explicitly use the access token you got yourself for your SP-API call as follows.

import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js';

const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-fe.amazon.com");
const sellerApi = new SellersApi(sellerApiClient);
sellerApiClient.applyXAmzAccessTokenToRequest("<access token you retrieve yourself>");
const participations = await sellerApi.getMarketplaceParticipations();

LWA Token refresh helper

The following code shows how to use LwaAuthClient to execute token refresh flow.

import { LwaAuthClient } from "<path to helper/LwaAuthClient.mjs>";

const lwaClient = new LwaAuthClient("<client ID>", "<client secret>", "<refresh token>");
const accessToken = await lwaClient.getAccessToken();

7.4 KiB Raw Permalink Blame History