2. Integration Points
9 minute read
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:
Documentation
Both the Operator API and Webhooks are fully discussed in the Documentation section of this site. For the most part the CIB will point you to resources in that section. You can also watch the Introduction to Marketplacer APIs video that can be found here to gain more insight. We will however cover the key characteristics of each below.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.
- When using a query, (e.g.
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:
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.
Order Created Event?
If you use the Operator API to create an order, (which you would need to do this for this use-case), you could use webhooks to emit an event based on that creation activity. In this case the webhook object type that you’d want to use would beInvoice
and the event Created
. For more information on webhook events, refer to the Webhook Event Matrix.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:
Source | Target | Use Case | Operator API | Webhooks |
---|---|---|---|---|
MP | CI | Product Created | advertsWhere or allAdverts queries | Advert -> Create or Variant -> Create |
MP | CI | Product Updated (Ad Hoc) | advertsWhere or allAdverts queries | Advert -> Update or Variant -> Update |
MP | CI | Product Deleted | allAdverts query | Advert -> Delete or Variant -> Delete |
MP | CI | Product Off-lined | advertsWhere or allAdverts queries | Advert -> Update or Variant -> Update |
MP | CI | Inventory Updated | advertsWhere or allAdverts or variantsWhere queries | Variant -> Update |
MP | CI | Pricing Updated | advertsWhere or allAdverts queries | Advert -> Update or Variant -> Update |
MP | CI | Advert Vetted | advertsWhere or allAdverts queries | Advert -> Update or Variant -> Update |
CI | MP | Advert Vetted | advertUpsert mutation | N/a |
CI | MP | Product Enriched | advertUpsert mutation | N/a |
Further Reading
- The Webhook Event Matrix is a good source of the webhook events that fire for a range of scenarios
- How to Update Adverts explains how to use the
advertUpsert
mutation
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:
- Refunds are usually tackled later in the development cycle
- You could arguably split out Refunds into a separate context - feel free to do so if this fits your use-case.
Source | Target | Use Case | Operator API | Webhooks |
---|---|---|---|---|
CI | MP | Order Created | orderCreate mutation | N/a |
CI | MP | Order Updated | orderCreate mutation | N/a |
CI | MP | Refund Request Created | refundRequestCreate mutation | N/a |
CI | MP | Refund Request Updated | refundRequestReturn or refundRequestLineItemAccept or refundRequestLineItemReturn mutations | N/a |
CI | MP | Refund Request Approved | refundRequestRefund | N/a |
CI | MP | Refund Request Denied | refundRequestDeny or refundRequestLineItemDeny mutations | N/a |
MP | CI | Refund Request Created | refundRequests or updatedRefundRequests or Invoices queries | Invoice -> Update or Refund -> Create |
MP | CI | Refund Request Updated | refundRequests or updatedRefundRequests or Invoices queries | Invoice -> Update or Refund -> Update or Refund -> Returned |
MP | CI | Refund Request Approved | refundRequests or updatedRefundRequests or Invoices queries | Invoice -> Update or Refund -> Update or Refund -> Refunded |
MP | CI | Refund Request Denied | refundRequests or updatedRefundRequests or Invoices queries | Invoice -> Update or Refund -> Update |
MP | CI | Invoice Updated | Invoices query | Invoice -> Update |
Further Reading
- 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:
Source | Target | Use Case | Operator API | Webhooks |
---|---|---|---|---|
MP | CI | Shipment Created | Invoices query | Invoice -> Update or Shipment -> Create |
MP | CI | Shipment Updated | Invoices query | Invoice -> Update or Shipment -> Update |
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.
Source | Target | Use Case | Operator API | Webhooks |
---|---|---|---|---|
CI | MP | Seller Created | sellerCreate mutation | N/a |
CI | MP | Seller Updated | sellerUpdate mutation | N/a |
MP | CI | Seller Created | sellerSearch query | Seller -> Create |
MP | CI | Seller Updated | sellerSearch query | Seller -> Update |
CI | MP | Remittances Updated | remittanceRelease and remittanceAdviceUpdate | N/a |
MP | CI | Remittances Created | remittances or remittanceAdvices queries | Remittance Advice -> Create |
MP | CI | Remittances Updated | remittances or remittanceAdvices queries | Remittance Advice -> Update |
Categorization Flows
Let’s remind ourselves of the categorization entities:
And these are the high-level contexts that we are focused on:
Note
While categorization data can flow in both directions (MP to CI and CI to MP) the flow of this data is less commonly implemented than the other flows (if at all).Source | Target | Use Case | Operator API | Webhooks |
---|---|---|---|---|
MP | CI | Taxon Created | taxons query | N/a |
MP | CI | Taxons Updated | taxons query | N/a |
MP | CI | Prototype Created | prototypes query | N/a |
MP | CI | Prototype Updated | prototypes query | N/a |
MP | CI | Option Type Created | prototypes query | Option Type -> Create |
MP | CI | Option Type Updated | prototypes query | Option Type -> Update |
MP | CI | Option Value Created | prototypes query | Option Value -> Create |
MP | CI | Option Value Updated | prototypes query | Option Value -> Update |
CI | MP | Taxon Created | taxonCreateOrUpdate mutation | N/a |
CI | MP | Taxons Updated | taxonCreateOrUpdate mutation | N/a |
CI | MP | Prototype Created | prototypeCreateOrUpdate mutation | N/a |
CI | MP | Prototype Updated | prototypeCreateOrUpdate mutation | N/a |
CI | MP | Option Type Created | optionTypeCreateOrUpdate mutation | N/a |
CI | MP | Option Type Updated | optionTypeCreateOrUpdate mutation | N/a |
CI | MP | Option Value Created | optionValueCreateOrUpdate mutation | N/a |
CI | MP | Option Value Updated | optionValueCreateOrUpdate mutation | N/a |
What’s Next
Next Up we look at some common connected approaches to building your Connected Integration.