# Carritos

> Carritos compartibles que cierran en WhatsApp

- Página: https://tbit.app/es/docs/api/carts
- URL base: `https://rest-api.tbit.app/v1`
- Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`)

## Descripción General

Los carritos permiten que un visitante de tu tienda arme una lista de productos y la lleve a una conversación de WhatsApp con todo el contexto. Un carrito es una instantánea de corta duración: recibe un código de 7 caracteres, es válido por 90 días y es inmutable: para cambiarlo, crea uno nuevo.

## Cómo Funciona el Flujo

1. Un visitante de tu tienda arma una lista de productos.
2. Tu tienda crea un carrito con POST /v1/carts y recibe un código corto.
3. Le envías al visitante un enlace como https://<tu-tienda>/c/<código> por WhatsApp.
4. Cuando empieza la conversación, tu agente ya tiene todo el contexto de lo que el visitante eligió.

## Endpoints

| Método | Ruta | Descripción |
| --- | --- | --- |
| `POST` | `/v1/carts` | Create a shareable cart |
| `GET` | `/v1/carts/:code` | Resolve a cart by code |

## Crear un Carrito

Envía de 1 a 50 artículos, cada uno referenciando un id de producto con un qty entre 1 y 99. La respuesta es el código corto del carrito:

`POST /v1/carts`

```bash
curl -X POST "https://rest-api.tbit.app/v1/carts" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "prod_id_1",
        "qty": 2
      },
      {
        "id": "prod_id_2",
        "qty": 1
      }
    ]
  }'
```

Respuesta:

```json
{
  "data": {
    "code": "K3F9X2A"
  }
}
```

## Obtener un Carrito

Resuelve un código de vuelta a sus artículos, cada uno un objeto producto completo más qty. Los carritos están aislados por cuenta: una clave solo resuelve carritos creados para su propio agente: cualquier otra cosa devuelve 404:

`GET /v1/carts/K3F9X2A`

```bash
curl "https://rest-api.tbit.app/v1/carts/K3F9X2A" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Respuesta:

```json
{
  "data": {
    "code": "K3F9X2A",
    "created_at": "2024-09-01T12:00:00Z",
    "items": [
      {
        "_id": "prod_id_1",
        "kind": "product",
        "title": "Kit fiesta dinosaurios",
        "currency": "COP",
        "base_price": 95000,
        "qty": 2
      },
      {
        "_id": "prod_id_2",
        "kind": "product",
        "title": "Piñata dinosaurio",
        "currency": "COP",
        "base_price": 45000,
        "qty": 1
      }
    ]
  }
}
```

## Notas

- Los códigos tienen 7 caracteres.
- Los carritos son válidos por 90 días.
- Los carritos son inmutables: crea uno nuevo para cambiar los artículos.
- Los carritos de otros agentes (o códigos desconocidos) devuelven 404.