In this tutorial, we’ll go through the necessary steps to implement GoToScan application with your web backend.
Note: GoToScan is only available in US. Please contact our support (help@cubicasa.com) if you’d want to use GoToScan in another region.
Before we start, you might wonder what’s the purpose of GoToScan and how it’s different from other CubiCasa scanning solutions. GoToScan is designed to be an invitation based and use case agnostic app that only provides authentication and scanning access to your end users. For example, if your company does kitchen renovations and right now your customers find it hard and time consuming to replica their kitchen into a 3D model online or you need to send out a professional in order to provide a quote, you can dramatically improve your quoting process with GoToScan. Simply send a GoToScan link to your customer, let them scan the kitchen and you’ll receive a digital version of the kitchen within 24 hours (or even faster if you’ve agreed on a faster SLA).
GoToScan is the right solution for you if:
GoToScan is not the right solution for you if:
Prerequisites
You’ll need a few things before you can follow this tutorial. Let’s go through them first.
Using GoToScan consists of these steps:
Generating a GoToScan authentication token is easy. You just need to make a HTTP GET request to our backend.
curl --header "X-API-KEY: 0d128ef7-89d1-4a64-925c-8149cd0ed5bc" https://api.cubi.casa/conversion/gotoscan/token
Note: You need to replace the API key with your own CubiCasa API key.
Your response will look something like this:
{
"id": "bfad08e6-f881-4d42-82d8-7eb144eb7bcf",
"token": "eyJpZDI6ICI0MjM5OzA3AC1jMDdmLTQ2MzAtY2Y3MC1hOPU0ZmJOOGP2ZDgiLCAidXNlcl9pZCI6ICI1AGQa2NGI45Ni01YzhmLTRhOTctYWM2Yi1iN2QxMThkMzWkMTgiLCAiaXNzdWVkX2F0IjogIjIwMjEtMTEtMDQUMTI5Mzc4MjVaIn0sMNf0D-L82MJ9SxrsPsmKlTd1oNtqCdla_m650OvwwQNjNoCeZn-oclJdtN_XOs2Z_8uB41PF4KKU0cwyYLoL",
"valid_until": "2021-11-11T12:37:25.947127Z"
}
Creating a GoToScan requires you to combine a base url and an array of URL parameters. One of the parameters is the token you created in step one. The others are related to scan address, your own scan ID and scanning settings. Full documentation is available on our GoToScan documentation page.
Important: Remember to URL encode your URL attributes before distributing them to your clients. The link should be opened on your mobile device..
Example link:
https://gotoscan.io/scan/?token=eyJpZCI6I&conversion_type=t3&external_id=external-ID-123&webhook_url=https%3A%2F%2Furl.com%2Flisten&priority=fast&suite=A1&street_address=1%20Fake%20Street&city=Mountain%20View&state=CA&postcode=94043&country=USA&client_name=Test%20Client
The default expiry of a token is 7 days. You can extend the token validity up to 28 days from token creation. Please read more from GoToScan documentation.
Once your link is created, you can open it on your mobile device. If you do not have GoToScan installed yet, your phone will open a webpage that asks user to download the app from App Store or Google Play Store. Once the app is installed, the app will open up and show the address of the scan. Below you can see each step in the scanning progress.
In the real world, your server would set up to listen to the webhook calls from our server. There are multiple tutorials available on the internet on how to deploy a webhook listener to your server. You can check some tutorials at the end of this document. In this documentation we’ll go through what you’ll receive from our Conversion API. The POST request to your webhook (which was defined in the GoToScan link), will include following body:
{
"ticket_id": "341449cf-f258-4d8c-83c2-75c4561391a9",
"event": "delivered",
"model_id": "63691682-d524-4709-b3c1-ca950990a2eb",
"external_id": "External-ID-1"
}
The “ticket_id” is generated by CubiCasa. You should store it to your database, because the “ticket_id” is needed to create Fix Requests. The “model_id” is used with Exporter API to render the floor plans. The “event” will be always “delivered” at this point of the scan life cycle. The “external_id” is define by you and it will be the same as in the GoToScan link that you created. If we are unable to create a floor plan, you will receive “deleted” event through the webhook. You can check more details from CubiCasa Conversion API
You can fake a delivery e.g. by using Postman. The model ID in the example payload is an actual floor plan that you can use to test. If you’ve done any other scans through CubiCasa, you can use those scans to test as well.
Your floor plans are rendered using the Exporter API. Exporter API let’s you to define the style of a floor plan including wall colors, floor colors, logos, strokes, opacity, units and language. Visit the full Exporter API documentation to get to know all its capabilities.
Below is an example of an Exporter API call that you can use to create necessary floor plan listing images and GLA images as well as GLA calculations.
POST https://api.cubi.casa/exporter/floorplan/<MODEL_ID>?api_key=<YOUR_API_KEY>
Body:
See different configs from our Exporter API documentation examples
Exporter API will respond a JSON that will include direct links to your files:
{
"single": {
"png": [
"https://s3-us-west-2.amazonaws.com/cubi.casa.exporter.output/6862c90645f64084a0113b6eed66c1c6/single_1-aurinkotuulenkatu-cctestopt-helsinki-uusimaa-finland_1.png",
"https://s3-us-west-2.amazonaws.com/cubi.casa.exporter.output/6862c90645f64084a0113b6eed66c1c6/single_1-aurinkotuulenkatu-cctestopt-helsinki-uusimaa-finland_0.png"
]
},
"compose": {
"png": [
"https://s3-us-west-2.amazonaws.com/cubi.casa.exporter.output/6862c90645f64084a0113b6eed66c1c6/compose_1-aurinkotuulenkatu-cctestopt-helsinki-uusimaa-finland_0.png"
]
}
}
Fill out the contact form and our experts will setup a meeting with you and get you started with GoToScan!
Here are some tutorials to easily setup some webhook listeners: