Implement Platform Connector APIs

In order to successfully connect an unsupported platform to the Bold APIs, you must implement a server that exposes the resources defined in the Platform Connector Server Requirements. By following these requirements in the creation of your server, Bold applications can access and create resources on the store's platform.

The following diagram shows a simplified example of how your platform and Bold may interact via the Platform Connector API when creating an order:

The following sections provide some recommendations and high-level steps for implementing the Platform Connector APIs.

note

This page does not go into detail about the specifics of connecting the server to your existing solution, because each solution requires a high level of customization. This page provides recommendations for generating the initial template code for your server.

Prerequisites

Before you get started, complete the steps outlined in Getting Started with a Platform Connector.

Server implementation

The server implementation must follow the Bold APIs, which comply with the OpenAPI Specification. There are 3 APIs that you must implement, and they are grouped around the resources required by Bold:

• Customers
• Orders
• Products

note

While some Bold applications may not require all three APIs, Bold recommends implementing all of the resources to take advantage of the full Checkout Experience Suite.

General server requirements

The server you implement must meet the following requirements:

• Must have a hosting server that is publicly accessible.
• Must accept requests from api.boldcommerce.com.
• Must support HTTPS and must have a signed SSL/TLS certificate for the server.
• Must handle JSON requests and return JSON responses.
• All requests sent to the server require the shop_identifier as a path parameter.
  • After obtaining your API access token, you can call the Get Info endpoint to get the shop_identifier. For more information, refer to Making API Calls.

Configure the server

You can choose one of several configurations to configure your server. The way you configure the server impacts the platform connector destinations that your project has and must register.

Single-domain configuration

The server you use for the platform connector can be hosted entirely on a single domain to support each API. The following table shows how a platform connector hosted at https://www.my-platform-connector.com could be organized:

API	Base Path	Example Route
Customers	https://www.my-platform-connector.com	https://www.my-platform-connector.com/v1/shops/{shop_identifier}/customers
Orders	https://www.my-platform-connector.com	https://www.my-platform-connector.com/v1/shops/{shop_identifier}/orders
Products	https://www.my-platform-connector.com	https://www.my-platform-connector.com/v1/shops/{shop_identifier}/products

Multi-domain configuration

Alternatively, you could host the platform connector on separate domains for each API:

API	Base Path	Example Route
Customers	https://www.my-customer-platform-connector.com	https://www.my-customer-platform-connector.com/v1/shops/{shop_identifier}/customers
Orders	https://www.my-order-platform-connector.com	https://www.my-order-platform-connector.com/v1/shops/{shop_identifier}/orders
Products	https://www.my-product-platform-connector.com	https://www.my-product-platform-connector.com/v1/shops/{shop_identifier}/products

Create the API server

You must set up the API server code to handle requests and interact with your own solutions. Create the code manually or use an OpenAPI generator.

Either method begins with retrieving the Platform Connector API Specifications. To download the raw version of the OpenAPI specification file, click the Download button at the top of the page.

OpenAPI Generator

Bold recommends using an OpenAPI generator to create a server stub for the platform connector. Using an OpenAPI generator can speed up the process by automatically generating boilerplate code to handle incoming requests.

There are a few open source options for API generators available:

• Swagger Codegen
• OpenAPI Generator

note

Bold does not officially support or endorse a particular OpenAPI generator. Use your best judgment when choosing and implementing a solution.

Manual

Creating the API server code manually is a larger effort, but this method can help ensure your server is constructed to meet your unique needs. It also requires a stronger knowledge of the OpenAPI Specification standard. Ensure all paths are handled as outlined in the specification.

Extend the server stub

The Platform Connector API Specifications outline the expected behavior of the server. Ensure the request handlers are responding in accordance to this behavior. The specific implementation is unique to your environment, but here are some general guidelines:

• Fields prefixed with platform_ must have unique values that are generated by your implementation. platform_id fields are expected to be unique within the given resource. For example, no two customers can have the same platform_id.
• All timestamps are in accordance with RFC 3339. (e.g., 2021-03-11T17:16:51Z).

Provide platform connector destinations to Bold

Each of the locations on your server where you make the platform connector accessible to Bold is called a platform connector destination.

Register each destination with Bold using the Create Destination endpoint. You must make a separate call for each of the customers, orders, and products resources, even if you chose a single-domain server configuration.

note

Calls to the Create Destination or Update Destination endpoints trigger a subsequent call to the Verify Platform Connector Destination endpoint on your platform connector. This endpoint confirms that you own the given URL that you are attempting to register.

You must implement the Verify Platform Connector Destination endpoint on your server before attempting to register the destination itself.

The following code snippet shows an example of creating the customers destination for a single-domain configuration:

curl --request POST 'https://api.boldcommerce.com/integrations/v1/shops/{shop_identifier}/platform_connector_destinations' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "data": {
             "destination": {
                 "shop_identifier": "abc123xyz",
                 "topic": "customers",
                 "destination": "https://www.my_platform_connector.com",
                 "version": "v1",
                 "timeout_ms": 10000
             }
         }
     }'

Ensure the security of your platform connector

Bold provides several mechanisms for you to be sure that calls to your platform connector are valid and coming from Bold, including an HMAC signature and a User-Agent header.

Filter on User Agent header

Each call from Bold to your platform connector is accompanied by a User-Agent header with a value of Bold-API. This header enables you to filter traffic from Bold through your firewall system, if applicable.

Verify the signature

Each call from Bold to your platform connector is accompanied by an HMAC (hash-based message authentication code) signature. Bold constructs the signature by computing the SHA256 hash of the X-HMAC-Timestamp header value using your shared secret as the hash secret key, and then encoding the hash result into a string using Base64 standard encoding.

Upon receiving a call to your platform connector, confirm that the request came from Bold by verifying the signature. The following code sample includes an example of creating an HMAC signature, which you can verify against the signature in the request.

const crypto = require("crypto");

const hmac = crypto.createHmac("sha256", "{shared_secret}").update("{x-hmac-timestamp}").digest("base64");

Next steps

• Implement Platform Event Notifications
• Verify the Platform Connector