# Paniers

> Des paniers partageables qui se concluent sur WhatsApp

- Page: https://tbit.app/fr/docs/api/carts
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Vue d'ensemble

Les paniers permettent à un visiteur de votre boutique de composer une liste de produits et de l'emporter dans une conversation WhatsApp avec tout le contexte. Un panier est un instantané de courte durée : il reçoit un code de 7 caractères, reste valable 90 jours et est immuable : pour le modifier, créez-en un nouveau.

## Comment fonctionne le parcours

1. Un visiteur de votre boutique compose une liste de produits.
2. Votre boutique crée un panier avec POST /v1/carts et reçoit un code court.
3. Vous envoyez au visiteur un lien comme https://<votre-boutique>/c/<code> sur WhatsApp.
4. Quand la conversation commence, votre agent a déjà tout le contexte de ce que le visiteur a choisi.

## Endpoints

| Méthode | Chemin | Description |
| --- | --- | --- |
| `POST` | `/v1/carts` | Créer un panier partageable |
| `GET` | `/v1/carts/:code` | Résoudre un panier par son code |

## Créer un panier

Envoyez de 1 à 50 articles, chacun référençant un id de produit avec un qty entre 1 et 99. La réponse est le code court du panier :

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

Réponse:

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

## Obtenir un panier

Résout un code en ses articles, chacun étant un objet produit complet plus qty. Les paniers sont cloisonnés par compte : une clé ne résout que les paniers créés pour son propre agent ; tout le reste renvoie 404 :

`GET /v1/carts/K3F9X2A`

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

Réponse:

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

## Notes

- Les codes font 7 caractères.
- Les paniers sont valables 90 jours.
- Les paniers sont immuables : créez-en un nouveau pour changer les articles.
- Les paniers d'autres agents (ou les codes inconnus) renvoient 404.