2. Integration Points

What you’ll learn

In this section of the Connected Integration Blueprint (CIB) you’ll learn about:

• What integration points you have available to build your Connected Integration
• Which specific integration points you can use to facilitate the data flows identified in the last section

How can I integrate

We offer both of the following integration points that allow you to build out a Connected Integration:

1. The Operator API
2. Webhooks

Connected Integration Context

Before discussing each of these methods further, it’s worth revisiting the Connected Integration Context we are discussing:

Boiling it down, we are looking at the following:

So in the rest of this section, we’re really focused now on how we can employ both the Operator API and Webhooks in the context of the Provider and Consumer roles, specifically in relation to the Data Flows we’ve already identified.

The Operator API

The Operator API is a GraphQL based API that provides everything you’d need to build out a fully Connected Integration, including but not limited to the following contexts:

• Products
• Orders (& Refunds)
• Shipments
• Sellers
• Categorization

Again it’s worth emphasizing the point that this API covers much more that just these contexts, so we encourage you to explore the full API schema here.

Provider or Consumer?

The Operator API can act as both a provider of data and consumer of data, observe the following 2 data flows:

• Product Creation
• Order Creation

Product Creation - (Operator API is the Provider)

• Use-case: A Seller has created a new product in Marketplacer using the Seller Portal, this new Product needs to propagate to the Connected Integration.

When using the Operator API in this scenario, you could use the advertsWhere query to pull data from Marketplacer (the Provider) to the Connected Integration (the Consumer). This can be illustrated as follows:

Order Creation - (Operator API is the Consumer)

• Use Case: A customer has placed an order on the eCommerce front end for a 3rd party marketplace product, this order needs to propagate to Marketplacer so that the Seller can fullfil the order.

When using the Operator API in this scenario, you would use the orderCreate mutation to push data from the CI (the Provider) to Marketplacer (the Consumer). This can be illustrated as follows:

Points to note

• The Operator API is still a Request / Response API, (it runs over HTTPs) therefore all requests (whether consuming data or providing data) originate from the CI. Or to put it in other words:
  • The CI is still always the Active Participant in all interactions - it initiates all requests to the API.
  • MP is the Passive Participant in all interactions - it waits for all requests from the CI.
• Rule of thumb:
  • When using a query, (e.g. advertsWhere) the Operator API will always be acting as the Provider
  • When using a mutation, (e.g. orderCreate) the Operator API will typically be acting as the Consumer. Be aware though, that mutations always have a query component for the response leg of the mutation request, so it’s conceivable that the Operator API would be acting as a Provider as well, e.g. Providing back the Order ID of a newly created order.

Webhooks

Webhooks are HTTP POST requests from Marketplacer to a HTTP endpoint resident in the Connected Integration, they enable event-based notifications. Create, Update and Delete events are available for a range of entities including but not limited to:

• Adverts
• Variants
• Invoices
• Shipments

Webhooks can be used to compliment the Operator API in building an Connected Integration, but you could not use webhooks alone to build a full end to end solution. This is because at present, webhooks send data only 1 way - from Marketplacer to the Connected Integration. Aside from the webhook response, there is no path back from the Connected Integration to Marketplacer to send data.

Provider or Consumer?

As mentioned above, Webhooks can act only as a data provider, (and not a consumer), observe the following 2 data flows:

• Product Creation
• Order Creation

Product Creation - (Webhooks are the Provider)

• Use-case: A Seller has created a new product in Marketplacer using the Seller Portal, this new Product needs to propagate to the Connected Integration.

When using Webhooks in this scenario, you could use the Advert Create webhook to have data pushed from Marketplacer (the Provider) to the Connected Integration (the Consumer) every time a new Product is created. This can be illustrated as follows:

Order Creation

• Use Case: A customer has placed an order on the eCommerce front end for a 3rd party marketplace product, this order needs to propagate to Marketplacer so that the Seller can fullfil the order.

As mentioned, Webhooks can only be used to send data from Marketplacer, so this use-case cannot be fulfilled using webhooks.

API or Webhooks?

As you can see there are scenarios, e.g. flowing Product data from Marketplacer to the Connected Integration, where you could use either (or in fact both):

• The Operator API
• Webhooks

In the Integration Point section below, we provide both the API and Webhook option for each data flow (where applicable), but in terms if which one you should use - tha really comes down to your requirements and design. We cover some patterns in the 3rd part of this blueprint.

Integration Point Mapping

Product Flows Integration Points

Let’s remind ourselves of the product entities:

And these are the high-level contexts that we are focused on:

Further Reading

• The Webhook Event Matrix is a good source of the webhook events that fire for a range of scenarios
• How to Manage Adverts explains how to use the advertUpsert mutation to create adverts
• How to Update Adverts explains how to reference and update existing adverts

Order Flows

Let’s remind ourselves of the order entities:

And these are the high-level contexts that we are focused on:

We have chosen to include Refunds as part of the Order context, and as such we’ll cover the data flows here. It’s worth noting 2 points however:

1. Refunds are usually tackled later in the development cycle
2. You could arguably split out Refunds into a separate context - feel free to do so if this fits your use-case.

Further Reading

• How to Create Orders explains the use of the orderCreate mutation
• The Webhook Event Matrix is a good source of the webhook events that fire for a range of scenarios
• How to Refund explains how to use the original refunds flow in Marketplacer. This is the default flow.
• How to Advanced Refund explains how to use the advanced refunds workflow in Marketplacer. This flow can be enabled on request
• Invoice Status Flags describes how state is manged for Invoices

Shipment Flows

Let’s remind ourselves of the shipment entities, (note we have included the relationship to the Invoice as it’s such a key relationship in the context of Shipments):

And these are the high-level contexts that we are focused on:

Seller Flows

Let’s remind ourselves of the seller entities:

And these are the high-level contexts that we are focused on:

We have bundled the Remittances in to the Seller context as they are closely related, however you may wish to split these out into separate contexts.

Categorization Flows

Let’s remind ourselves of the categorization entities:

And these are the high-level contexts that we are focused on:

What’s Next

Next Up we look at some common connected approaches to building your Connected Integration.