# Bundles

Mit der Bundles-API lassen sich mehrere Listings zu einer kaufbaren Einheit mit Bundle-Preis zusammenfassen.

## Bundle-Typen

### Festes Bundle
Eine vom Administrator oder Verkäufer zusammengestellte Auswahl mit genau festgelegten Artikeln und Mengen. Käufer erwerben das Bundle wie angeboten.

**Beispiel:** „Starter-Kit“ — 1 Notizbuch + 2 Stifte + 1 Tasche für 49,99 $.

### „Mix & Match“-Bundle
Käufer wählen Artikel aus einem festgelegten Pool. Das Bundle legt eine Mindest- und optional eine Höchstmenge fest.

**Beispiel:** „Wähle 3“ — 3 Produkte aus einem Katalog mit 20 Optionen für 29,99 $.

## Bundle erstellen

1. Erstellen Sie ein Listing mit `POST /v1/listings` und `type: "bundle"`.
2. Fügen Sie bei einem festen Bundle Komponenten mit `POST /v1/bundles/:listing_id/items` hinzu.
3. Legen Sie bei „Mix & Match“ `metadata.bundle_type: "mix_and_match"`, `metadata.min_quantity` und `metadata.max_quantity` fest und befüllen Sie den Pool mit `POST /v1/bundles/:listing_id/pool`.

## Kaufablauf

Kauft ein Käufer ein Bundle über den Standard-Checkout, erstellt das System automatisch je Komponente eine Bestellposition (jeweils pro Filiale/Konto), reduziert den Komponentenbestand und ermöglicht die Abwicklung durch einzelne Verkäufer über den bestehenden Mehrfachversand.

## Authentifizierung

Authentifizieren Sie Client-Anfragen ausschließlich mit dem Bearer-Token. Tenant und Benutzer werden von der API-Gateway anhand des Tokens ermittelt. Fügen Sie die Header `tenant_id`, `user_id`, `admin` oder `X-Auth-Key` nicht hinzu.

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

## cURL-Beispiele

Erstellen Sie zuerst das Listing über die Listings-API und verwenden Sie die zurückgegebene ID für die Bundle-Endpunkte. Die Beispiele setzen die neue Listing-ID `729379` voraus.

```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 }
    }
  }'
```

### Komponenten eines festen Bundles

`GET /v1/bundles/729379/items` listet Komponenten auf. Fügen Sie eine mit `POST /v1/bundles/729379/items` und dem Body `{"component_listing_id":370,"quantity":1,"order_by":1}` hinzu. Ändern Sie sie mit `PUT /v1/bundles/729379/items/1` (Body `{"quantity":1,"order_by":1}`) oder löschen Sie sie mit `DELETE /v1/bundles/729379/items/1`. Alle Anfragen benötigen `Authorization: Bearer $TOKEN`.

### „Mix & Match“-Pool

Listen Sie den Pool mit `GET /v1/bundles/729379/pool` auf. Fügen Sie jedes Listing mit `POST /v1/bundles/729379/pool` und dem Body `{"component_listing_id":370,"order_by":1}` hinzu.

### Artikel auswählen

Übermitteln Sie die Auswahl, bevor Sie das Bundle zum Warenkorb hinzufügen. Speichern Sie die zurückgegebene `selection_id` für Warenkorb und Checkout.

```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}'
```

Das folgende Beispiel setzt voraus, dass der Endpunkt `selection_id: 6` zurückgegeben hat.

### Bestand prüfen

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

### Bundle zum Warenkorb hinzufügen

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

Senden Sie diesen Body an `POST /v1/cart`.

### Checkout

Senden Sie `{"order":{"payment_method_id":7175,"type":"bundle","selection_id":6}}` an `POST /v1/cart/checkout`.

### Ausgewählte Komponenten zur Abwicklung abrufen

Ersetzen Sie `6563` durch die beim Checkout zurückgegebene Bestell-ID und rufen Sie `GET /v1/bundles/729379/orders/6563/components` auf.

Verkäufer dürfen nur eigene Listings als feste Komponenten oder Pool-Elemente hinzufügen.