> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Recette — créer un plan

> Créer un plan de réassort et ajouter un article, avec enveloppe de réponse et gestion d'erreurs.

C'est le flux canonical d'**écriture** : créer un [plan de réassort](/fr/inventory-plans/restock),
puis ajouter un article. La même forme s'applique aux autres types de plans (réassort, etc.) — seuls les
chemins et champs diffèrent.

<Warning>
  Cela crée des données réelles dans votre organisation. Utilisez un token avec la bonne permission d'écriture
  et testez d'abord contre une organisation non-production si vous le pouvez.
</Warning>

## 1. Créer le plan

`POST /api/restock-plans` avec `name` (et optionnellement `brandId`, `collectionId`,
`description`). Il retourne l'`id` du nouveau plan et le `status` (`DRAFT`).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://app.solya.app/api/restock-plans \
      -H "Authorization: Bearer solya_sa_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Adidas FW25 Restock Wave 1",
        "brandId": "brand-uuid-adidas",
        "collectionId": "coll-uuid-fw25",
        "description": "First restock order for Adidas FW25"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    BASE, TOKEN = "https://app.solya.app", "solya_sa_xxx"
    headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

    plan = requests.post(f"{BASE}/api/restock-plans", headers=headers, json={
        "name": "Adidas FW25 Restock Wave 1",
        "brandId": "brand-uuid-adidas",
        "collectionId": "coll-uuid-fw25",
    }).json()
    plan_id = plan["id"]   # e.g. "rop-uuid-001"; status == "DRAFT"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const BASE = "https://app.solya.app", TOKEN = "solya_sa_xxx"
    const headers = { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" }

    const plan = await (await fetch(`${BASE}/api/restock-plans`, {
      method: "POST", headers,
      body: JSON.stringify({
        name: "Adidas FW25 Restock Wave 1",
        brandId: "brand-uuid-adidas",
        collectionId: "coll-uuid-fw25",
      }),
    })).json()
    const planId = plan.id // status: "DRAFT"
    ```
  </Tab>
</Tabs>

Réponse :

```json theme={null}
{ "id": "rop-uuid-001", "brandId": "brand-uuid-adidas", "collectionId": "coll-uuid-fw25", "status": "DRAFT" }
```

## 2. Ajouter un article

`POST /api/restock-plans/{planId}/items` avec `variantId`, `sizeId`, `shopId`, `quantity`.
Il retourne `{ "success": true, "itemId": "…" }`.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://app.solya.app/api/restock-plans/rop-uuid-001/items \
      -H "Authorization: Bearer solya_sa_xxx" \
      -H "Content-Type: application/json" \
      -d '{ "variantId": "var-uuid-adidas-stan", "sizeId": "sz-uuid-43", "shopId": "shop-uuid-paris-opera", "quantity": 12 }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    res = requests.post(
        f"{BASE}/api/restock-plans/{plan_id}/items",
        headers=headers,
        json={"variantId": "var-uuid-adidas-stan", "sizeId": "sz-uuid-43",
              "shopId": "shop-uuid-paris-opera", "quantity": 12},
    ).json()

    if not res.get("success"):
        raise RuntimeError(f"add item failed: {res.get('errorCode')}")
    print("added item", res["itemId"])
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const res = await (await fetch(`${BASE}/api/restock-plans/${planId}/items`, {
      method: "POST", headers,
      body: JSON.stringify({
        variantId: "var-uuid-adidas-stan", sizeId: "sz-uuid-43",
        shopId: "shop-uuid-paris-opera", quantity: 12,
      }),
    })).json()
    if (!res.success) throw new Error(`add item failed: ${res.errorCode}`)
    console.log("added item", res.itemId)
    ```
  </Tab>
</Tabs>

## Gérer la réponse

Ajouter des articles passe par des [règles métier](/fr/intelligence-layer/rules-and-rulesets), alors
préparez-vous à ces résultats :

* **Succès** — `{ "success": true, "itemId": "…" }`.
* **Bloqué par une règle** — `success: false` avec `errorCode: "BUSINESS_RULE_VIOLATION"`;
  lisez le message et ajustez.
* **Validation** — `errorCode: "VARIANT_REQUIRED"`, `"QUANTITY_INVALID"`, etc. Corrigez la
  charge utile.
* **Authentification** — `401 UNAUTHORIZED` (token mauvais/expiré) ou `403 FORBIDDEN` (permission manquante).

Voir [Codes d'erreur](/fr/developers/error-codes) pour le mapping complet.

<Note>
  Les autres types de plans suivent le même motif — par ex. réassort est `POST /api/rebalance-plans`
  puis `POST /api/rebalance-plans/{id}/items`. Consultez les champs exacts par endpoint dans l'onglet
  **Référence API**.
</Note>