**Versions de l’API** · [V2 (Latest)](/integrations/v2/docs?lang=fr) · **V1**

> **Cette version de l’API est obsolète.** Utilisez la dernière version pour toute nouvelle intégration. [Voir la documentation actuelle](/integrations/v2/docs?lang=fr)

# Menu

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Menu de navigation du site — arborescence par site (parent/position) de liens libres et de liens vers des entités (PAGE/FORM/CAGNOTTE). Le contenu et la structure sont gérés séparément (utilisez /menu/reorder pour l’arborescence). Autorisations : `web_menu:read`/`web_menu:write`.

## Opérations

## GET /menu

Lister les éléments de menu (arborescence d’un site)

`list_menu`

Autorisation requise : `web_menu:read`. Renvoie les éléments du site (à plat, triés par position ; reconstruisez l’arborescence avec parent/position). Transmettez `?virtualId` pour cibler un site (omettre = site principal).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "web_menu:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "virtualId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Identifiant du site ; omettre pour le site principal."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuItem"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /menu

Créer un élément de menu

`create_menu_item`

Autorisation requise : `web_menu:write`. Crée un élément à la fin du niveau racine. Utilisez `targetId` pour les éléments PAGE/FORM/CAGNOTTE.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuItemInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/MenuItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ERREUR_DE_VALIDATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /menu/reorder

Réorganiser/déplacer les éléments du menu

`reorder_menu`

Autorisation requise : `web_menu:write`. Définit le parent et la position des éléments en une seule opération (arborescence/glisser-déposer). Envoyez la disposition complète souhaitée.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuReorderInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "reorder",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /menu/{id}

Modifier un élément de menu

`update_menu_item`

Autorisation requise : `web_menu:write`. Modifie uniquement le contenu (pas le parent/la position). Transmettez le `virtualId` de l’élément dans le corps.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MenuItemInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/MenuItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ERREUR_DE_VALIDATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /menu/{id}

Supprimer un élément de menu

`delete_menu_item`

Autorisation requise : `web_menu:write`. Transmettez `?virtualId` pour limiter l’opération au site.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "web_menu:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "virtualId",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "web_menu:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## Schémas

```json
{
  "components": {
    "schemas": {
      "MenuItem": {
        "type": "object",
        "description": "Élément de menu du site, nœud d’une arborescence par site (parent/position). Lien libre (nom+url) ou lien vers une entité (type + targetId).",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Périmètre du site : null = site principal, sinon identifiant d’un site virtuel."
          },
          "type": {
            "type": "string",
            "enum": [
              "LINK",
              "PAGE",
              "FORM",
              "CAGNOTTE",
              "ACCOUNT",
              "DYNAMIC_ARTICLES"
            ],
            "description": "Type d’élément. LINK = lien libre (name+url). PAGE/FORM/CAGNOTTE = lien vers une entité (définir targetId ; le libellé est résolu à partir de la cible). ACCOUNT = lien fixe vers l’espace de compte membre (url \"/account\", nom modifiable). DYNAMIC_ARTICLES = liste d’articles (url \"\")."
          },
          "name": {
            "type": "string",
            "description": "Libellé affiché (vide pour les liens FORM/CAGNOTTE, qui reprennent le nom de leur cible)."
          },
          "url": {
            "type": "string",
            "description": "URL cible d’un lien libre (vide pour les liens vers une entité ; \"/account\" pour ACCOUNT)."
          },
          "targetId": {
            "type": "string",
            "description": "Identifiant de l’entité associée (obligatoire si type est PAGE/FORM/CAGNOTTE)."
          },
          "parent": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant de l’élément parent (null = racine)."
          },
          "position": {
            "type": "integer",
            "description": "Ordre de tri parmi les éléments frères."
          },
          "platform": {
            "type": "string",
            "enum": [
              "ALL",
              "ONLY_DESKTOP",
              "ONLY_APPMOBILE"
            ],
            "description": "Surface d’affichage : ALL = site web sur ordinateur et application mobile native ; ONLY_DESKTOP = site web sur ordinateur uniquement ; ONLY_APPMOBILE = application mobile native uniquement. ALL par défaut."
          }
        }
      },
      "MenuItemInput": {
        "type": "object",
        "description": "Données pour créer ou modifier le CONTENU d’un élément de menu. Sa structure (parent/position) n’est PAS définie ici — utilisez POST /menu/reorder. À la création, l’élément est ajouté à la fin du niveau racine.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "LINK",
              "PAGE",
              "FORM",
              "CAGNOTTE",
              "ACCOUNT",
              "DYNAMIC_ARTICLES"
            ],
            "description": "Type d’élément. LINK = lien libre (name+url). PAGE/FORM/CAGNOTTE = lien vers une entité (définir targetId). ACCOUNT = espace de compte membre — définir url à \"/account\". DYNAMIC_ARTICLES = liste d’articles — définir url à \"\"."
          },
          "name": {
            "type": "string",
            "description": "Libellé affiché (utilisez \"\" pour les liens FORM/CAGNOTTE)."
          },
          "url": {
            "type": "string",
            "description": "URL cible d’un lien libre (utilisez \"\" pour les liens vers une entité ; \"/account\" pour ACCOUNT)."
          },
          "targetId": {
            "type": "string",
            "description": "Identifiant de l’entité associée — obligatoire si type est PAGE/FORM/CAGNOTTE."
          },
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Site auquel rattacher l’élément (null/omis = site principal)."
          },
          "platform": {
            "type": "string",
            "enum": [
              "ALL",
              "ONLY_DESKTOP",
              "ONLY_APPMOBILE"
            ],
            "description": "Surface d’affichage de cet élément. ALL = site web sur ordinateur + application mobile native ; ONLY_DESKTOP = site web sur ordinateur uniquement ; ONLY_APPMOBILE = application mobile native uniquement. Valeur omise/invalide → ALL. À envoyer uniquement pour la modifier (omise lors d’une édition, la valeur actuelle est conservée)."
          }
        }
      },
      "MenuReorderInput": {
        "type": "object",
        "description": "Définir le parent et la position des éléments de menu en une seule opération atomique (glisser-déposer / arborescence). Envoyez la disposition complète souhaitée.",
        "required": [
          "items"
        ],
        "properties": {
          "virtualId": {
            "type": "string",
            "nullable": true,
            "description": "Périmètre du site (null/omis = site principal)."
          },
          "items": {
            "type": "array",
            "description": "Disposition souhaitée.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "parent": {
                  "type": "string",
                  "nullable": true,
                  "description": "Identifiant de l’élément parent (null = racine)."
                },
                "position": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
      }
    }
  }
}
```
