Receiving Messages from SyncHive

In this guide, we'll show you how to set up your Connector to receive messages from SyncHive. We'll use an example where we receive a Product Message from SyncHive and save it to Shopify.

1. Creating your API

To receive Messages from SyncHive, create an API endpoint for your Connector as follows:

POSThttps://{my_connector_url}/v1/data

2. Receiving data

SyncHive will call your Connector's data endpoint with a Message in the payload. This Message contains the data that we'll be saving to Shopify.

3. Data transformation

Next, transform the Message into Shopify Product data. Here’s an example of the transformation:

Example Message:

{
    "dataAction": "UPDATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "label": "632910392"
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel fource slice toaster",
        "externalIdentity": [
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "price": {
            "@type": "Monetary",
            "decimalValue": 100.00,
            "currency": {
                "@type": "DataReference",
                "schemaName": "limber",
                "shapeName": "CurrencyUnit",
                "iri": "https://schema.limbergraph.com/limber/CurrencyUnit#NZD",
                "keys": [
                    {
                        "code": "NZD"
                    }
                ],
                "label": "NZD"
            }
        }
    }
}

Example transformed data:

{
    "title": "Toaster",
    "body_html": "<p>Four slice toaster.</p>",
    "status": "active",
    "variants": [
        {
            "product_id": 632910392,
            "title": "Stainless Steel",
            "price": "100.00",
            "sku": "8082STAINLESS"
        }
    ]
}

4. Sending data to Shopify

Once you've transformed the data, the next step is to send it to Shopify. But before we can do that, we need to get the details of the specific Shopify store where the product will be sent. To do this, we'll extract the required information from the Message:

• integrationKey
• integrationVersion
• integrationBuildNumber

Then, use this information to request the Shopify integration details from SyncHive:

POSThttps://{synchive_url}/v1/integration/{integrationKey}/{integrationVersion}/{integrationBuildNumber}

Headers

"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"

This will return the following information about the Shopify NZ instance:

• httpUrl: https://www.my_shopify_url.com
• httpApiKeyHeader: X-Shopify-Access-Token
• httpApiKeyValue: 3tuCsUi3zopbxWmuqFDe

Use this information to send your Shopify product data to the Shopify NZ instance:

POSThttps://www.my_shopify_url.com/admin/api/2024-1/products.json

Headers

"X-Shopify-Access-Token": "3tuCsUi3zopbxWmuqFDe",
"Content-Type": "application/json"

Body

Your Shopify Product

5. Responding to SyncHive

After sending the product data to Shopify, we need to respond to SyncHive for two reasons: to inform SyncHive of our success or failure, and to determine if we need to link the Shopify NZ instance to this data in SyncHive.

Linking identities

First, let's discuss linking data in SyncHive.

When you link instances to data in SyncHive, you're telling SyncHive which data is used by which external systems.

When to link identities

If the Message you received from SyncHive has an empty externalIdentities array, this means that Shopify NZ does not have this product data. In this case, we need to link the Shopify NZ instance to this data in SyncHive.

Example payload:

{
    "dataAction": "CREATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [], <--- Empty
        "label": "632910392"
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel fource slice toaster",
        "externalIdentity": [], <--- Also empty
        "price": {
           ... 
        }
    }
}

Conversely, if the Message you received from SyncHive has values in the externalIdentities array, this means that Shopify NZ does have this product data, and you can skip this step.

Example payload:

{
    "dataAction": "UPDATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [ <--- Not empty
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "label": "632910392"
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel fource slice toaster",
        "externalIdentity": [ <--- Also not empty
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "price": {
            ...
        }
    }
}

How to link an identity

To link the data contained in this Message to the Shopify NZ instance, use the following payload when responding to SyncHive:

{
  "externalIdentity": {
    "integrationKey": "shopify_nz_integration",
    "externalId": "632910392" <--- The Shopify product ID
  },
  "linkIdentities": {
    "integrationKey": "shopify_nz_integration",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#632910392",
        "externalId": "632910392" 
      }
    ]
  },
  "publishStatus": "SUCCESS"
}

If you do not need to link the data contained in this Message to the Shopify NZ instance, simply respond with an empty body.

Providing a response code

After deciding whether to link this data to the Shopify NZ instance, we also need to inform SyncHive of our success or failure. Provide a 200 HTTP response code to indicate success, or any non-200 code along with a reason for the failure in the message body.

Congratulations, your Connector is now ready to receive messages from SyncHive.

Next steps: Configuring Your Connector in SyncHive

This guide covered the basics of receiving messages from SyncHive. In the next guide, we'll cover configuring your Connector in SyncHive.