# Quable application - API flow

## 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:

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

---

```mermaid
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:

```http
GET {app-url}/permission
```

**Expected Response:**
```json
["read_access"]
```
or
```json
["full_access"]
```

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

---

## 2. Installation

If the user confirms, the PIM calls:

```http
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:

```http
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:

```http
POST {app-url}?slot=x
```

**Payload example:**
```json
{
  "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**
1. Go to **Administration > Quable App**.
2. Click **New Quable App**.
3. Fill in the form (including app URL).
4. Enable and activate the app.

**API Installation**
- Same process via API.
- See [Postman collection](https://quable-support.postman.co/workspace/PIM-Quable-App-Management~42a0f974-0e22-4e6f-9825-250757f93832/request/237314-2c2f9def-44e6-4087-93ec-f21c55644ff7).

---

## 📌 Annex – 'Slot' Example

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

#### Example flow

```mermaid
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

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

**Body:**
```json
{
    "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.