# Quable application - API flow

The Quable Team

# HTTP Headers

All calls from Quable PIM to QuableApp include these headers:

Client-ID: Quable
Referer: {instanceCode} (contains the instance code referencing the QuableApp)

# Quable App Lifecycle

A Quable App interacts with the PIM through four main endpoints:

{appUrl}/permission – Quable PIM request the access level your app needs.
{appUrl}/install – Quable PIM confirms the installation and run setup logic.
{appUrl} – Quable PIM ask your app about the "configuration" page.
{appUrl}?slot=x – It allows the display of your UI and logic into the PIM via slots.

sequenceDiagram
    participant U as User
    participant Q as Quable PIM
    participant A as Quable App

    rect rgba(130, 167, 255, 0.2)
        Note over Q,A: Installation Phase
        U->>Q: Click "Install"
        Q->>+A: GET {appUrl}/permission
        A-->>-Q: 200 OK (["read_access"] or ["full_access"])
        U->>Q: Confirm installation
        Q->>+A: POST {appUrl}/install?quableInstanceName=xxx
        A-->>-Q: 200 OK (setup complete)
    end

    rect rgba(130, 167, 255, 0.2)
        Note over Q,A: Configuration page
        U->>Q: Open app settings
        Q->>+A: POST {appUrl}
        A-->>-Q: 200 OK (HTML UI for settings page)
    end

    rect rgba(255, 161, 161, 0.2)
        Note over Q,A: Runtime Slot Interaction
        U->>Q: Trigger slot (e.g., click action button)
        Q->>+A: POST {appUrl}?slot=x
        A-->>-Q: 200 OK (HTML or JSON depending on slot type)
    end

# 1. Requesting Permissions

When a user clicks "Install", the PIM sends:

GET {app-url}/permission

Expected Response:

["read_access"]

["full_access"]

This determines whether your app can only read data or also modify it.

# 2. Installation

If the user confirms, the PIM calls:

POST {app-url}/install?quableInstanceName=xxx&interfaceLocale=en-US&dataLocale=fr_FR

Expected Response:

200 OK

What to do here:

Create webhooks
Add custom attributes/entities
Store API credentials
Initialize external services

# 3. Configuration Page

When a user opens your app's configuration in the PIM:

POST {app-url}/

Expected Response:

HTTP: 200 OK
Body: Valid HTML (displayed inside an iframe in the PIM)

You have full control over the HTML: forms, buttons, navigation, etc.

# 4. Slot Integration

A slot is an entry point in the PIM UI where your app can display content or trigger actions.

When a user interacts with a slot:

POST {app-url}?slot=x

Payload example:

{
  "object": {
    "type": "product",
    "ids": ["PROD1", "PROD2"]
  },
  "slot": "document.action.single",
  "instance": "customer-instance-id",
  "user": {
    "email": "john.doe@example.com",
    "admin": true
  },
  "locale": {
    "data": "fr-FR",
    "interface": "en_US"
  }
}

Expected Response:

200 OK
HTML or JSON depending on the slot type

# ✅ Best Practices

Serve all endpoints over HTTPS.
Authenticate incoming requests (HMAC recommended).
Handle errors gracefully with proper HTTP codes.
Log installation events per instance.
Version your endpoints (/v1/install, etc.).

# Installation Methods

Interface Installation

Go to Administration > Quable App.
Click New Quable App.
Fill in the form (including app URL).
Enable and activate the app.

API Installation

Same process via API.
See Postman collection.

# 📌 Annex – 'Slot' Example

Some slots provide richer interactions, like adding a custom tab in a document page.

# Example flow

sequenceDiagram
    participant B as Browser
    participant Q as Quable PIM
    participant A as Quable App

    Note over B,A: Document Page Display Process
    
    B->>+Q: Open document page
    
    B->>+Q: Click on the QuableApp tab
    
    Q->>+A: POST {appUrl}?slot=document.page.tab
    Note right of A: Request contains:<br/>- app code<br/>- object type<br/>- object ids
    
    A-->>-Q: 200 OK<br/>{ "url": "https://your-app/content" }
    
    Q-->>-B: Load content from returned URL

# Example request

POST {appUrl}?slot=document.page.tab HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}
Content-Type: application/json

Body:

{
    "slug": "{{app-code}}",
    "slots": [...],
    "object": {
        "type": "document",
        "ids": ["{{id}}"]
    },
    "documentType": {
        "id": "{{app-document-type-id}}"
    },
    "name": { "en": "My Custom Tab" },
    "description": { "en": "Extra document info" },
    "parameters": {
        "keyValues": [...]
    },
    "icon": { "type": "svg", "value": "<svg>...</svg>" },
    "url": "{{appUrl}}",
    "permissionFeatures": [...],
    "security": {
        "appSecret": "..."
    }
}

Expected Response:

HTTP: 2xx
Body must contain the URL where the tab content can be loaded.