2. Integration Points

Understand the which integration points you can use to facilitate the flow of data.

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:

Connected Context

Boiling it down, we are looking at the following:

Provider Consumer


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:


Operator API as a Provider


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:


Operator API as a Consumer

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 behave as near real-time event 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:


Webhooks API as a Provider


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:

Product Entities


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

Product Flow


SourceTargetUse CaseOperator APIWebhooks
MPCIProduct CreatedadvertsWhere or allAdverts queriesAdvert -> Create or Variant -> Create
MPCIProduct Updated (Ad Hoc)advertsWhere or allAdverts queriesAdvert -> Update or Variant -> Update
MPCIProduct DeletedallAdverts queryAdvert -> Delete or Variant -> Delete
MPCIProduct Off-linedadvertsWhere or allAdverts queriesAdvert -> Update or Variant -> Update
MPCIInventory UpdatedadvertsWhere or allAdverts or variantsWhere queriesVariant -> Update
MPCIPricing UpdatedadvertsWhere or allAdverts queriesAdvert -> Update or Variant -> Update
MPCIAdvert VettedadvertsWhere or allAdverts queriesAdvert -> Update or Variant -> Update
CIMPAdvert VettedadvertUpsert mutationN/a
CIMPProduct EnrichedadvertUpsert mutationN/a

Further Reading


Order Flows

Let’s remind ourselves of the order entities:

Order Entities

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

Order Flow

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.
SourceTargetUse CaseOperator APIWebhooks
CIMPOrder CreatedorderCreate mutationN/a
CIMPOrder UpdatedorderCreate mutationN/a
CIMPRefund Request CreatedrefundRequestCreate mutationN/a
CIMPRefund Request UpdatedrefundRequestReturn or refundRequestLineItemAccept or refundRequestLineItemReturn mutationsN/a
CIMPRefund Request ApprovedrefundRequestRefundN/a
CIMPRefund Request DeniedrefundRequestDeny or refundRequestLineItemDeny mutationsN/a
MPCIRefund Request CreatedrefundRequests or updatedRefundRequests or Invoices queriesInvoice -> Update or Refund -> Create
MPCIRefund Request UpdatedrefundRequests or updatedRefundRequests or Invoices queriesInvoice -> Update or Refund -> Update or Refund -> Returned
MPCIRefund Request ApprovedrefundRequests or updatedRefundRequests or Invoices queriesInvoice -> Update or Refund -> Update or Refund -> Refunded
MPCIRefund Request DeniedrefundRequests or updatedRefundRequests or Invoices queriesInvoice -> Update or Refund -> Update
MPCIInvoice UpdatedInvoices queryInvoice -> Update

Further Reading


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):

Shipment Entities

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

Shipment Flow


SourceTargetUse CaseOperator APIWebhooks
MPCIShipment CreatedInvoices queryInvoice -> Update or Shipment -> Create
MPCIShipment UpdatedInvoices queryInvoice -> Update or Shipment -> Update

Seller Flows

Let’s remind ourselves of the seller entities:

Seller Entities

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

Seller Flow

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.


SourceTargetUse CaseOperator APIWebhooks
CIMPSeller CreatedsellerCreate mutationN/a
CIMPSeller UpdatedsellerUpdate mutationN/a
MPCISeller CreatedsellerSearch querySeller -> Create
MPCISeller UpdatedsellerSearch querySeller -> Update
CIMPRemittances UpdatedremittanceRelease and remittanceAdviceUpdateN/a
MPCIRemittances Createdremittances or remittanceAdvices queriesRemittance Advice -> Create
MPCIRemittances Updatedremittances or remittanceAdvices queriesRemittance Advice -> Update

Categorization Flows

Let’s remind ourselves of the categorization entities:

Categorization Entities

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

Categorization Flow

SourceTargetUse CaseOperator APIWebhooks
MPCITaxon Createdtaxons queryN/a
MPCITaxons Updatedtaxons queryN/a
MPCIPrototype Createdprototypes queryN/a
MPCIPrototype Updatedprototypes queryN/a
MPCIOption Type Createdprototypes queryOption Type -> Create
MPCIOption Type Updatedprototypes queryOption Type -> Update
MPCIOption Value Createdprototypes queryOption Value -> Create
MPCIOption Value Updatedprototypes queryOption Value -> Update
CIMPTaxon CreatedtaxonCreateOrUpdate mutationN/a
CIMPTaxons UpdatedtaxonCreateOrUpdate mutationN/a
CIMPPrototype CreatedprototypeCreateOrUpdate mutationN/a
CIMPPrototype UpdatedprototypeCreateOrUpdate mutationN/a
CIMPOption Type CreatedoptionTypeCreateOrUpdate mutationN/a
CIMPOption Type UpdatedoptionTypeCreateOrUpdate mutationN/a
CIMPOption Value CreatedoptionValueCreateOrUpdate mutationN/a
CIMPOption Value UpdatedoptionValueCreateOrUpdate mutationN/a

What’s Next

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