Custom integration

Custom integrations allows you to add custom data and actions to your customer profiles using an external url.

There are 2 custom integration types.

Custom Frame
This loads a an HTML page on your website in a frame and gives you maximum flexibility.

Custom orders
Use an order API on your website to load orders into Belco using the JSON format.

1. Enabling a custom integration

1.1 Goto: Settings -> Integrations -> Other -> (Custom frame or Custom orders)
1.2 In the url field enter the url that points to the page that's hosted on your servers.
For example:
https://yourwebsite.com/api/v1.0/orders

The customer email address and phonenumber, when present, are always appended at the end of the url.

For example:
https://yourwebsite.com/api/v1.0/[email protected]&phoneNumber=

Note: Belco appends the email parameter on it's own, therefore it is not necessary to add this to the custom integration url field.

1.3 To improve security you should include a token in the url to verify that the request is coming from Belco. This token has to be added to the url to make it check for the token. This token will not be appended automatically by Belco. You can define this token yourself, since you have to program this token into your webshop yourself.

Note Make sure to first check for the token parameter in the url and then the email or phone-number parameter, since there are many cases where the integrations fails when those checks have been turned around.

For example:
https://yourwebsite.com/api/v1.0/orders?token=my-secret-token&[email protected]&phoneNumber=

2. Iframe API

Your iframe page can interact with Belco using the postMessage API. There are two options. The first option is to add an user specific iframe. If you would like to use this function, you can check for the 'email' parameter in the url. Belco automatically appends this when visiting the iframe url.

If you do not want your iframe content to be user specific, you can just ignore the email parameter in the url. By doing so you can add certain company specific forms etc to you customer-card.

2.1 Resizing the frame

To improve UX you should make sure to resize the iframe to the page height.

// Resize the parent iframe
window.parent.postMessage({
  action: 'resize',
  height: document.body.scrollHeight
}, 'https://app.belco.io')

// Automatically resize on window load
window.addEventListener('load', function() {
  window.parent.postMessage({
    action: 'resize',
    height: document.body.scrollHeight
  }, 'https://app.belco.io')
})

3. JSON response

The custom integration expects the following JSON API response:

{
  "orders": [{
    "id": "1234",
    "note": "Note",
    "number": "1234",
    "date": "2020-01-01T00:00Z",
    "createdAt": "2020-01-01T00:00Z",
    "updatedAt": "2020-01-01T00:00Z",
    "status": "processing",
    "currency": "EUR",
    "products": [{
      "name": "Product X",
      "quantity": 1,
      "price": 10.00
    }],
    "total": 10.00,
    "url": "https://shop.nl/order/1234"
  }]
}

You can add an email field or phone-number field to the end of the response. This way you don't have to filter these fields from the JSON response in your API.

4. Shop settings

When the integration has been finished, the shop has to be configured so it will use the custom integration api.

You can configure this by heading to the 'shop' section in the Belco settings. After that you select the shop and then you configure the 'platform' to be 'custom integration'

Note: When using the Iframe API, the settings above won't have to applied.