Getting Started with the Ecommerce APIs¶
Use these steps to get quickly started in the Sandbox test environment. For an overview of the Ecommerce APIs, click here.
1. Sign up or log in¶
Sign up for a free Pitney Bowes developer account at the Developer Hub Signup page. Use a regularly monitored email for signup, such as a distribution list. The email address you choose cannot be changed.
If you already have an account, log into your account at Developer Hub.
2. Get your API key and secret¶
Your developer account comes with a key and secret that give you access to the APIs on the Sandbox test environment. The key and secret are unique to your account.
In your developer account, click API Keys. Copy the Sandbox key and secret.
3. Get your Developer ID¶
Your Developer ID is required by certain API calls.
In your developer account, in the upper right corner, click your name or company name, then click Your Account. Copy your Developer ID.
4. Get your default merchant’s Shipper ID¶
Note
For the Fulfillment APIs, skip this step.
To get you started quickly, your developer account comes with a default merchant. You can use the default merchant for all your development and testing. As with all merchants, the default merchant is identified by its unique Shipper ID.
In your developer account, in the left pane navigation, click Onboarding Merchants. Then in the content area, copy the Shipper ID.
5. Ensure your system meets the TLS requirement¶
The minimum supported security protocol for connection to the Ecommerce APIs is TLS v1.2. To test whether your environment supports TLS v1.2, issue the following GET operation:
curl -X GET https://api-test.pitneybowes.com/tlstestA response of
TLS_Connection_Successindicates your system meets the requirement.
6. Generate an OAuth token¶
To make a request to the Ecommerce APIs, you must have an OAuth token. The token identifies and authenticates the developer account making the request.
To generate a token, first encode your API key and secret in the following format using a Base64 encoder. Be sure to include the colon between the key and secret.
<API_key>:<API_secret>Generate the OAuth token using the following API call, replacing <base64_value> with the Base64-encoded value:
curl -X POST https://shipping-api-sandbox.pitneybowes.com/oauth/token \ -H "Authorization: Basic <base64_value>" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials"The API returns an OAuth token in the access_token field, as shown in the example response below:
{ "access_token": "mL3Ec6yp67uYGm0DnLiqPjux0AFY", "tokenType": "BearerToken", "issuedAt": "1498168771002", "expiresIn": "35999", "clientID": "a3cDEFghI1jK2LMnOP3qRstU4vWX5Yz", "org": "pitneybowes" }Note
The token is valid for 10 hours.
7. Test the APIs in Sandbox¶
Test the APIs using the Sandbox environment. Sandbox uses the following base URLs:
For the Shipping APIs, a good place to start is with the Create Shipment API. Try printing a Priority Mail label using PB Expedited as the carrier. Use your default merchant’s Shipper ID. See this example.
Next, try printing a Parcel Select label using PB Delivery as the carrier. See this example.
For details on carriers, see Carriers. For the sequence of operations to ship a parcel, see the Shipping Workflow.
For the Fulfillment APIs, a good place to start testing is with the Create a Product API. For more information on the Fulfillment APIs, see Fulfillment APIs Overview.
8. Upgrade to Production¶
To upgrade to a Production account, contact Pitney Bowes at ShippingAPIBusinessDevelopment@pb.com.
Printing Your First Production Label: When printing your first production label, you must ensure your postage account has sufficient funds to cover the cost of the label. In case of insufficient funds, you might encounter an error while your account is being funded.