# Paquetes

La API Bundles permite agrupar varios anuncios en una única unidad de compra con un precio de paquete.

## Tipos de paquete

### Paquete fijo
Conjunto definido por el administrador o vendedor con artículos y cantidades exactos. El comprador adquiere el paquete tal como está.

**Ejemplo:** «Kit inicial» — 1 cuaderno + 2 bolígrafos + 1 bolsa por 49,99 $.

### Paquete «mix & match»
El comprador elige artículos de un grupo definido. El paquete establece una cantidad mínima y, opcionalmente, máxima.

**Ejemplo:** «Elige 3» — selecciona 3 productos de un catálogo de 20 por 29,99 $.

## Crear un paquete

1. Crea un anuncio con `POST /v1/listings` y `type: "bundle"`.
2. Para un paquete fijo, añade los componentes con `POST /v1/bundles/:listing_id/items`.
3. Para «mix & match», define `metadata.bundle_type: "mix_and_match"`, `metadata.min_quantity` y `metadata.max_quantity`, y completa el grupo con `POST /v1/bundles/:listing_id/pool`.

## Flujo de compra

Cuando el comprador adquiere un paquete mediante el flujo de pago estándar, el sistema crea automáticamente una línea de pedido por componente (una por sucursal/cuenta), reduce las existencias de los componentes y habilita el cumplimiento por vendedor mediante el flujo de envíos múltiples existente.

## Autenticación

Autentica las solicitudes del cliente únicamente con el token Bearer. La pasarela de API obtiene el tenant y el usuario del token. No añadas los encabezados `tenant_id`, `user_id`, `admin` ni `X-Auth-Key`.

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

## Ejemplos cURL

Crea primero el anuncio con Listings y usa el ID devuelto en los puntos de conexión de paquetes. Los ejemplos suponen que el nuevo ID es `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 }
    }
  }'
```

### Componentes de paquetes fijos

`GET /v1/bundles/729379/items` lista los componentes. Añade uno con `POST /v1/bundles/729379/items` y el cuerpo `{"component_listing_id":370,"quantity":1,"order_by":1}`. Actualízalo con `PUT /v1/bundles/729379/items/1` (cuerpo `{"quantity":1,"order_by":1}`) o elimínalo con `DELETE /v1/bundles/729379/items/1`. Todas las solicitudes requieren `Authorization: Bearer $TOKEN`.

### Grupo de opciones «mix & match»

Lista el grupo con `GET /v1/bundles/729379/pool`. Añade cada anuncio con `POST /v1/bundles/729379/pool` y el cuerpo `{"component_listing_id":370,"order_by":1}`.

### Elegir artículos

Envía la selección antes de añadir el paquete al carrito. Guarda el `selection_id` devuelto para crear el carrito y finalizar la compra.

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

El ejemplo siguiente supone que el punto de conexión devolvió `selection_id: 6`.

### Comprobar existencias

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

### Añadir el paquete al carrito

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

Envía este cuerpo a `POST /v1/cart`.

### Finalizar la compra

Envía `{"order":{"payment_method_id":7175,"type":"bundle","selection_id":6}}` a `POST /v1/cart/checkout`.

### Obtener componentes seleccionados para el cumplimiento

Sustituye `6563` por el ID del pedido devuelto por el pago y llama a `GET /v1/bundles/729379/orders/6563/components`.

Los vendedores solo pueden añadir sus propios anuncios como componentes fijos o artículos del grupo.