Tutorial: Display Actions for Procedures
Consider a trip from Germany to the Dominican Republic with a USA passport. If you search for the requirements of this trip in sherpa's website, you can notice a procedure that reads "Mandatory travel declaration form before arrival" with two call-to-action options, one linking to the government website & one powered by Sherpa. We call these "actions" .
In this tutorial, we will go through the process of creating similar integrations.
Make a request
For this tutorial, you can make a POST request to the v3/trips endpoint with the following body:
{
"type": "TRIP",
"attributes": {
"traveller": {
"passports": [
"USA"
]
},
"locale": "en-US",
"travelNodes": [
{
"type": "ORIGIN",
"departure": {
"date": "2024-01-15",
"time": "00:00"
},
"locationCode": "DEU"
},
{
"type": "DESTINATION",
"arrival": {
"date": "2024-01-15",
"time": "00:00"
},
"locationCode": "DOM"
}
]
}
}
Receive the Response
You will receive a large response back from the API. The summary of it will be as follows:
{
"meta": {
"copyright": "Sherpa",
"version": "3.0.1"
},
"data": {
"id": "e8ace1d1-6c56-4a3a-acba-7baeb0380428",
"type": "TRIP",
"attributes": {
"traveller": {
"passports": [
"USA"
]
},
"locale": "en-US",
"travelNodes": [
(OBJECT)
],
"headline": "We don't have information for travel from Germany to Dominican Republic. Be sure to check official sources.",
"informationGroups": [
{
"name": "Visa Requirements",
"type": "VISA_REQUIREMENTS",
"tooltip": "Visa requirements are determined by the passport you are travelling with and duration of your trip.",
"groupings": [
{
"name": "Dominican Republic",
"enforcement": "NOT_REQUIRED",
"data": [
{
"type": "PROCEDURE",
"id": "090889cb-62b1-4c12-af6a-7c2ff9ec36ec"
}
]
}
],
"enforcement": "NOT_REQUIRED",
"headline": "You don't need a visa for Dominican Republic if you have a United States passport."
},
{
"name": "Passport and Documents",
"type": "DOCUMENTS_AND_FORMS",
"groupings": [
{
"name": "Dominican Republic",
"enforcement": "MANDATORY",
"data": [
{
"type": "PROCEDURE",
"id": "1696b60b-51ba-4df5-9089-7630f9861363"
},
{
"type": "PROCEDURE",
"id": "260648c2-9eea-48b1-9bb9-3abc0b64fb95"
},
{
"type": "PROCEDURE",
"id": "d5e5cafa-3b9f-475b-9b37-5233e857e4f9"
}
]
}
],
"enforcement": "MANDATORY"
},
{
"name": "Public Health Requirements",
"type": "PUBLIC_HEALTH_REQUIREMENTS",
"enforcement": "UNKNOWN"
},
{
"name": "Travel Restrictions",
"type": "TRAVEL_RESTRICTIONS",
"tooltip": "Travel restrictions often depend on your travel history. Check details for each part of your trip to see if any of them apply to you."
},
{
"name": "Additional Information",
"type": "ADDITIONAL_INFORMATION"
},
{
"name": "Upcoming",
"type": "UPCOMING",
"tooltip": "Some of these changes may not be in effect yet and may change unexpectedly."
}
],
"travelOpenness": "NO_INFORMATION"
},
"relationships": {
(OBJECT)
}
},
"included": [
(OBJECT)
]
}
Similar to visual representation, under the "Passport and Documents" Information grouping (type == "DOCUMENTS_AND_FORMS"), there is a procedure with ID d5e5cafa-3b9f-475b-9b37-5233e857e4f9. This is the procedure that we are interested in.
Under the included option, there is a procedure object with the same ID:
{
"id": "d5e5cafa-3b9f-475b-9b37-5233e857e4f9",
"type": "PROCEDURE",
"attributes": {
"category": "DOC_REQUIREMENT",
"subCategory": "BEFORE_ARRIVAL",
"title": "Mandatory travel declaration form before arrival",
"description": "Travelers arriving on commercial flights must fill out an electronic entry form before arrival, which combines the Traveler’s Health Affidavit, Customs Declaration, and International Embarkation/Disembarkation forms. \n\nOnce completed, this form will provide a QR code that the authorities will scan on arrival. Each traveler must complete the form individually before departure to Dominican Republic. \n\nWhen traveling as a family, it is not necessary for each traveler in the same family to fill out an individual form. Up to 7 travelers in the same family can complete 1 form. After that, travelers must fill out an additional form. \n\nFor more details, please check the source.",
"more": [
"This requirement doesn’t apply to the following travelers:\n-Travelers arriving in Dominican Republic on private flights, non-commercial vessels, ferries, or cruise ships. "
],
"actions": [
{
"type": "LINK",
"title": "Use Migración (Free)",
"url": "https://eticket.migracion.gob.do/"
},
{
"type": "LINK",
"title": "Use sherpa",
"url": "https://sherpa-widget.joinsherpa.io/applications/products/DOM_ETICKET?affiliateId=sherpa",
"provider": "sherpa",
"intent": "apply-product",
"productId": "DOM_ETICKET"
}
],
"sources": [
{
"type": "GOVERNMENT",
"title": "Dominican Republic Tourism",
"url": "https://www.godominicanrepublic.com/travel/entry-requirements/"
}
],
"lastUpdatedAt": "2023-12-28T10:16:00.000Z",
"createdAt": "2020-11-30T11:47:00.000Z",
"startDate": "2020-11-29T00:00:00.000Z",
"endDate": null,
"enforcement": "MANDATORY",
"documentTypes": [
"TRAVEL_AUTHORIZATION"
],
"tags": [...],
"travelPurposes": [
"TOURISM",
"BUSINESS",
"TRANSIT"
],
"included": [...],
"icon": {
"name": "document"
}
},
"relationships": {
"location": {
"data": {
"id": "DOM",
"type": "LOCATION"
}
}
}
}
This procedure has two associated actions. The first one is a link to the official government website that can be used to fulfil this requirement. The alternative is the second action. Because for this action provider == sherpa, The integration can be done in two different formats.
Integration for an Action provided by sherpa, Option 1: Link
This method is similar to the actions provided by government. All that needs to be happen is opening the url passed, in this case "https://sherpa-widget.joinsherpa.io/applications/products/DOM_ETICKET?affiliateId=sherpa" for the user.
Integration for an Action provided by sherpa, Option 2: SDK
This method has two advantages over the previous one:
Modal Experience
The application widget can be displayed as a modal on top of the integrating webpage, and create a more "embedded" look & feel.
Passing data for prefill
Leveraging this method allows the integrating webpage to pass the information it has on the traveller to Sherpa, which can be used for prefilling information in the application flow and, in turn, save time, reduce the error rate and ultimately create a better user experience.
Implementing the SDK launch of an action
This page can be used as a quick start guide for using Sherpa SDK to launch a product offering specified by an action.
Updated 10 months ago