Self-Service Mapping

Send a list of listings to get the supplier to map them themselves

To use this capability add octo/mappings to your Octo-Capabilities header.

This capability allows you to send a "mapping sheet" of products that you need to map. This is then given to the supplier in a user-friendly form they can select which product each item maps to in their Ventrata system. Once the mapping has been set a webhook URL is called to notify your system of the change.

Update Mappings

PUT https://api.ventrata.com/octo/mappings

Send to us a list of all your product listings and what mapping fields you need in response. We'll then call the provided webhookUrl when the data is updated.

200

[
  {
    "resellerReference": "5526",
    "title": "The Original DUCKtours Singapore",
    "url": "https://www.klook.com/en-US/activity/5526-the-original-ducktours-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": false,
  },
  {
    "resellerReference": "119",
    "title": "S.E.A. Aquarium™ One-Day Adult Ticket",
    "url": "https://www.klook.com/en-US/activity/119-sea-aquarium-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": true,
  },
  //...etc
]

[
  {
    "resellerReference": "5526",
    "title": "The Original DUCKtours Singapore",
    "url": "https://www.klook.com/en-US/activity/5526-the-original-ducktours-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": false,
  },
  {
    "resellerReference": "119",
    "title": "S.E.A. Aquarium™ One-Day Adult Ticket",
    "url": "https://www.klook.com/en-US/activity/119-sea-aquarium-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": true,
  },
  //...etc
]

Whenever a product in your system for this supplier has been changed, updated or deleted, you should repeat the request with ALL mappings. The PUT method is used to indicate that whenever you make this request the list you send will merge with all mappings already in the suppliers Ventrata system.

Field	Description
resellerReference	This is a string ID which identifies this listing in your system. It's required and is used to uniquely identify each listing so when you make subsequent requests we only create/update/delete listings that have been added, changed or deleted.
title	The supplier will use this to identify the product for mapping.
url	This is the listing URL which can help the supplier identify what product this is in your system.
webhookUrl	The URL we call when the supplier updates the mapping.
optionRequired	Whether your system requires a specific option for this product (if false, you'll dynamically show the guest an interface to select the option before checkout).
unitRequired	Whether your system requires a specific unit for this product (if false, you'll dynamically show all unit available to the guest).

After you've made the request and new mappings have been added, we'll send a notification to the supplier to complete them. The interface they're given will look a little like this:

Reseller Product	Ventrata Product	Ventrata Option	Ventrata Unit
The Original DUCKtours Singapore	Please select	Please select	N/A
S.E.A. Aquarium™ One-Day Ticket	Please select	Please select	Please select

The above is just illustrative. But once the supplier has chosen a product an option that's associated to a mapping, Ventrata will perform a POST request to the URL provided in webhookUrl for that mapping item. The webhook body will be like:

POST /octo/mapping-callback HTTP/1
Host: api.klook.com
Content-Type: application/json

{
  "resellerReference": "119",
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "optionId": "47fbfde3-97bb-4478-b71f-ba7c2380c06a",
  "unitId":  "adult"
}

The unitId and optionId will be null in the webhook request body if we set unitRequired and optionId to false respectively on the original mappings request.

Your response to this request must be 2XX e.g. 200 OK otherwise we'll repeat the request until we receive a 2XX response.

Get Mappings

GET https://api.ventrata.com/octo/mappings

Gets the current state of all the mappings in the system.

200

[
  {
    "resellerReference": "5526",
    "title": "The Original DUCKtours Singapore",
    "url": "https://www.klook.com/en-US/activity/5526-the-original-ducktours-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": false,
    "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "optionId": "DEFAULT",
    "unitId":  null
  },
  {
    "resellerReference": "119",
    "title": "S.E.A. Aquarium™ One-Day Adult Ticket",
    "url": "https://www.klook.com/en-US/activity/119-sea-aquarium-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": true,
    "productId": "84ea621d-b3c3-4cee-be5f-8cfdf00666cc",
    "optionId": "47fbfde3-97bb-4478-b71f-ba7c2380c06a",
    "unitId":  "adult"
  },
  //...etc
]

The response sample will be like:

[
  {
    "resellerReference": "5526",
    "title": "The Original DUCKtours Singapore",
    "url": "https://www.klook.com/en-US/activity/5526-the-original-ducktours-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": false,
    "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "optionId": "DEFAULT",
    "unitId":  null
  },
  {
    "resellerReference": "119",
    "title": "S.E.A. Aquarium™ One-Day Adult Ticket",
    "url": "https://www.klook.com/en-US/activity/119-sea-aquarium-singapore",
    "webhookUrl": "https://api.klook.com/octo/mapping-callback",
    "optionRequired": true,
    "unitRequired": true,
    "productId": "84ea621d-b3c3-4cee-be5f-8cfdf00666cc",
    "optionId": "47fbfde3-97bb-4478-b71f-ba7c2380c06a",
    "unitId":  "adult"
  },
  //...etc
]

The addition of productId optionId and unitId are the mapped values. Note that optionId and unitId will be null if optionRequired and unitRequired is false, respectively.