# Carrelli

> Carrelli condivisibili che si chiudono su WhatsApp

- Pagina: https://tbit.app/it/docs/api/carts
- URL base: `https://rest-api.tbit.app/v1`
- Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`)

## Panoramica

I carrelli permettono a un visitatore del tuo negozio di comporre una lista di prodotti e portarla in una conversazione su WhatsApp con tutto il contesto. Un carrello è un'istantanea di breve durata: riceve un codice di 7 caratteri, è valido per 90 giorni ed è immutabile: per cambiarlo, creane uno nuovo.

## Come funziona il flusso

1. Un visitatore del tuo negozio compone una lista di prodotti.
2. Il tuo negozio crea un carrello con POST /v1/carts e riceve un codice breve.
3. Mandi al visitatore un link come https://<tuo-negozio>/c/<codice> su WhatsApp.
4. Quando inizia la conversazione, il tuo agente ha già tutto il contesto di quello che il visitatore ha scelto.

## Endpoint

| Metodo | Percorso | Descrizione |
| --- | --- | --- |
| `POST` | `/v1/carts` | Crea un carrello condivisibile |
| `GET` | `/v1/carts/:code` | Risolvi un carrello dal codice |

## Creare un carrello

Invia da 1 a 50 articoli, ognuno con un id di prodotto e una qty tra 1 e 99. La risposta è il codice breve del carrello:

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

Risposta:

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

## Ottenere un carrello

Risolve un codice nei suoi articoli, ognuno un oggetto prodotto completo più qty. I carrelli sono isolati per account: una chiave risolve solo i carrelli creati per il proprio agente; qualsiasi altra cosa restituisce 404:

`GET /v1/carts/K3F9X2A`

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

Risposta:

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

## Note

- I codici hanno 7 caratteri.
- I carrelli sono validi per 90 giorni.
- I carrelli sono immutabili: creane uno nuovo per cambiare gli articoli.
- I carrelli di altri agenti (o codici sconosciuti) restituiscono 404.