# Lots de produits

L'API Bundles permet de regrouper plusieurs annonces en une seule unité achetable avec un prix de lot.

## Types de lots

### Lot fixe
Ensemble défini par l'administrateur ou le vendeur, avec les articles et quantités exacts. L'acheteur achète le lot tel quel.

**Exemple :** « Kit de démarrage » — 1 carnet + 2 stylos + 1 sac pour 49,99 $.

### Lot « mix & match »
L'acheteur choisit des articles dans un groupe défini. Le lot impose une quantité minimale et, éventuellement, maximale.

**Exemple :** « Choisissez-en 3 » — sélectionnez 3 produits parmi 20 pour 29,99 $.

## Créer un lot

1. Créez une annonce avec `POST /v1/listings` et `type: "bundle"`.
2. Pour un lot fixe, ajoutez ses composants avec `POST /v1/bundles/:listing_id/items`.
3. Pour « mix & match », définissez `metadata.bundle_type: "mix_and_match"`, `metadata.min_quantity` et `metadata.max_quantity`, puis remplissez le groupe avec `POST /v1/bundles/:listing_id/pool`.

## Déroulement d'un achat

Lorsqu'un acheteur passe commande pour un lot via le paiement standard, le système crée automatiquement une ligne de commande par composant (une par branche/compte), décrémente le stock des composants et permet à chaque vendeur d'assurer l'exécution via le flux multi-expédition existant.

## Authentification

Authentifiez les requêtes client uniquement avec le jeton Bearer. Le tenant et l'utilisateur sont identifiés à partir du jeton par la passerelle API. N'ajoutez pas les en-têtes `tenant_id`, `user_id`, `admin` ou `X-Auth-Key`.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Exemples cURL

Créez d'abord l'annonce avec l'API Listings, puis utilisez son ID dans les points de terminaison des lots. Les exemples supposent que l'ID obtenu est `729379`.

```bash
curl -X POST "$API/v1/listings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "listing": {
      "title": "Aurelia Bridal Set - Pick 2",
      "description": "Choose any two items from the bridal collection.",
      "type": "bundle",
      "list_price": 120000,
      "currency_id": 13,
      "metadata": { "bundle_type": "mix_and_match", "min_quantity": 2, "max_quantity": 2 }
    }
  }'
```

### Composants d'un lot fixe

`GET /v1/bundles/729379/items` liste les composants. Ajoutez un composant avec `POST /v1/bundles/729379/items` et le corps `{"component_listing_id":370,"quantity":1,"order_by":1}`. Modifiez-le avec `PUT /v1/bundles/729379/items/1` (corps `{"quantity":1,"order_by":1}`) ou supprimez-le avec `DELETE /v1/bundles/729379/items/1`. Toutes les requêtes nécessitent `Authorization: Bearer $TOKEN`.

### Groupe d'un lot « mix & match »

Listez le groupe avec `GET /v1/bundles/729379/pool`. Ajoutez chaque annonce avec `POST /v1/bundles/729379/pool` et le corps `{"component_listing_id":370,"order_by":1}`.

### Choisir les articles

Envoyez la sélection avant d'ajouter le lot au panier. Conservez le `selection_id` renvoyé pour créer le panier et payer.

```bash
curl -X POST "$API/v1/bundles/729379/select" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  --data-raw '{"selected_listing_ids":[370,371],"quantity":1}'
```

L'exemple suivant suppose que le point de terminaison a renvoyé `selection_id: 6`.

### Vérifier le stock

`GET /v1/bundles/729379/stock?quantity=1`

### Ajouter le lot au panier

```json
{"listing_id":729379,"quantity":1,"type":"bundle","selection_id":6}
```

Envoyez ce corps à `POST /v1/cart`.

### Paiement

Envoyez `{"order":{"payment_method_id":7175,"type":"bundle","selection_id":6}}` à `POST /v1/cart/checkout`.

### Récupérer les composants sélectionnés pour l'exécution

Remplacez `6563` par l'ID de commande renvoyé par le paiement, puis appelez `GET /v1/bundles/729379/orders/6563/components`.

Les vendeurs ne peuvent ajouter que leurs propres annonces comme composants fixes ou articles de groupe.