Proxy-Based Embedded CPQ Guide

# Decoloop CPQ Embedded Guide ## Introduction Decoloop CPQ can be embedded in a website using an iframe. This enables other websites or applications to display the Decoloop CPQ order page. ## Integration Flow The typical integration flow works as follows: 1. **User initiates**: A user on a third-party website wants to add products from Decoloop CPQ 2. **Third-party embeds**: The third-party application starts the iframe with Decoloop CPQ (see Getting Started below) 3. **User configures**: The user configures products in Decoloop CPQ and saves the order 4. **Event notification**: Decoloop CPQ sends a message to the parent window with the project ID 5. **Retrieve project data**: The third-party application retrieves the complete project information using the project ID and the Decoloop CPQ Gateway API ## Getting Started #### Prerequisites To connect to a Decoloop CPQ instance, third-party applications need an API key provided by Decoloop. This API key is specific to the third-party application and can be re-used across multiple CPQ instances. #### Step 1: Create A Token Create a token for Decoloop CPQ using the Decoloop CPQ Gateway. ##### Generating a Token **URL:** `/token` **Method:** POST This endpoint can be called to generate a token, which in turn can be used for authentication in the Decoloop CPQ Gateway API. An example request: ``` POST http://127.0.0.1:50750/token Content-Type: application/json { "domainName": "test", "username": "test", "password": "test", "apiKey": "test-123-test" } ``` The response will contain the following data: ```json { "access_token": "aaabbbccc", "token_type": "bearer", ".issued": "8-10-2018 15:39:41", ".expires": "2018-10-22T15:39:41.1959628+02:00", "refresh_token": "dddeeefff" } ``` ##### Creating an Authorized Request With the received `access_token`, an authorized request can be made. Set the `Authorization` header like so: ```json "Authorization": "{token_type} {access_token}" ``` Using the above response as an example, the header would be: ```json "Authorization": "bearer aaabbbccc" ``` #### Step 2: Create An Iframe Now, create an iframe with a Decoloop CPQ url and the following parameters `token=ACCESS_TOKEN&isEmbedded=true`. With the `ACCESS_TOKEN` here being the token we have created in step 1. Your url should look something like this: `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true`. Set this url as the source of your iframe. ```html <iframe src="http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true"></iframe> ``` The Decoloop CPQ order page should now be displayed. :tada: :tada: :tada: #### Step 3: Listen To Event When an order is saved or closed, Decoloop CPQ will emit an event to its parent window. This event will contain the id of the saved project. The parent window can listen to this event using the following code: ```typescript window.addEventListener('message', event => { const data = event.data; const projectId = data.payload; switch (data.type) { case 'CLOSE_PROJECT': this.onCloseProject(projectId); break; case 'SAVE_PROJECT': this.onSaveProject(projectId); break; } }); ``` #### Step 4: Retrieve and Send Project Data The saved project can now be loaded or sent using the project ID received in step 3. Use the Decoloop CPQ Gateway API to load the project data (`Project/Load`) and send the project (`Project/Send`) ## Optional URL Parameters The iframe URL can be customized with various optional parameters to control the initial state of Decoloop CPQ. #### Loading An Existing Project If an existing project needs to be loaded, pass the project's id as a query parameter: `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true&projectId=1` This will load the saved project into Decoloop CPQ. #### Start With Material Starting a new project with a material can be done using either the material id or the material (EAN)code. When starting Decoloop CPQ with a material, Decoloop CPQ will select the first product from the menu for the first polygon. The `Material/Export` API method can be used to retrieve all available materials of the user in this CPQ instance. **Material Id:** `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true&materialId=1` **Material Code:** `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true&materialCode=EXAMPLE123` **Invalid Materials:** When an invalid material id or material code is passed in the query parameter, Decoloop CPQ will show an error message. #### Copy Project To copy an existing project, use the `copy` parameter along with the `projectId`: `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true&copy=true&projectId=1` #### Copy Polygon To copy a specific polygon from a project, use the `copyPolygonId` parameter along with the `projectId`: `http://127.0.0.1:50750?token=ACCESS_TOKEN&isEmbedded=true&projectId=1&copyPolygonId=5`