Proxy-Based Embedded CPQ Guide

Introduction

This guide covers the proxy/hub embedded CPQ mode. This mode uses api.decoloop.com as a centralized proxy/gateway to handle connections to multiple CPQ applications, suppliers, or instances through a single API connection.

The base URL for the Embedded API is:

https://api.decoloop.com/api/embedded

When to use this guide

Use this proxy-based mode when:

• The host application needs to connect to multiple different CPQ applications or suppliers dynamically.
• A partner or supplier integration requires a centralized hub instead of individual integration setups.
• You want to avoid hardcoding individual, supplier-specific CPQ instance URLs.

Use the direct Embedded CPQ Developer Guide instead when:

• The integration targets one known, direct CPQ instance.
• The iframe URL and gateway API calls are made directly against that instance's unique URL.

Integration Flow

The complete flow consists of the following steps:

1. Authenticate against api.decoloop.com to receive a token.
2. Retrieve the list of available applications.
3. Choose an applicationId to load.
4. Request the embedded iframe URL for that specific application.
5. Open and display the iframe to the user.
6. Proxy CPQ API requests through the proxy URL using the application ID.

Authentication

Authentication is token-based. You will need to obtain a Bearer token by POSTing to the /token endpoint with your credentials.

Security Warning To keep your credentials secure, do not expose the apiKey, password, or long-lived credentials in client-side code. Always obtain the token via a secure backend and pass only the temporary token or iframe URL to the frontend.

Step 1: Create a token

Generate a short-lived token using your integration credentials.

Endpoint

POST /token

Request Body

{
  "emailAddress": "user@example.com",
  "password": "example-password",
  "apiKey": "example-api-key"
}

Response

{
  "token": "eyJ...",
  "expiresIn": 3600
}

Example cURL

curl -X POST https://api.decoloop.com/api/embedded/token \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "user@example.com",
    "password": "example-password",
    "apiKey": "example-api-key"
  }'

Step 2: Get available applications

Retrieve a list of CPQ applications/instances configured for your account.

Endpoint

GET /getapplications

Headers

Authorization: Bearer {token}

Response

[
  {
    "id": "application-id",
    "name": "Application name"
  }
]

Step 3: Get the embedded iframe URL

Obtain the unique embed URL for the selected application.

Endpoint

GET /geturl?applicationId={id}

Headers

Authorization: Bearer {token}

Response

{
  "url": "https://..."
}

Usage in frontend

Use the returned URL inside an iframe in your application:

<iframe
  src="EMBEDDED_URL_FROM_GETURL"
  width="100%"
  height="800"
  title="Decoloop CPQ"
></iframe>

Proxying CPQ API Requests

Instead of calling separate CPQ endpoints directly, all Gateway API requests should be routed through the centralized api.decoloop.com proxy URL.

Proxy Base URL

https://api.decoloop.com/cpq-proxy/{applicationId}/...

The proxy supports GET, POST, PUT, and DELETE requests. All request headers (including Authorization and Content-Type) are forwarded to the underlying CPQ application as-is.

URL Mapping Example

For a direct CPQ endpoint:

/gateway/embedded/browsematerials

Your proxied endpoint becomes:

https://api.decoloop.com/cpq-proxy/{applicationId}/gateway/embedded/browsematerials

Example Proxy Request

POST https://api.decoloop.com/cpq-proxy/{applicationId}/gateway/embedded/browsematerials
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Error Handling

When interacting with the proxy API or the embedded endpoint, expect the following standard HTTP status codes:

• 401 Unauthorized: Missing, invalid, or expired Bearer token.
• 403 Forbidden: Authenticated user does not have permission for the specified applicationId.
• 404 Not Found: The specified application or proxied API endpoint could not be found.
• 5xx: Upstream CPQ instance or proxy gateway issue.

Ensure you check and log the response status code and any returned message safely. Never log passwords, API keys, or raw bearer tokens.

Comparison with Direct Embedded Mode

Troubleshooting

• Token expired: Acquire a new token via POST /token.
• Empty application list: Verify that your API key and account are properly configured with permissions.
• Iframe fails to load: Verify the applicationId and ensure the URL was not modified.
• Proxy returns authorization error: Check if the bearer token is valid and belongs to the account authorized to access that application ID.