# Produits

> Lisez votre catalogue de produits, avec recherche sémantique

- Page: https://tbit.app/fr/docs/api/products
- 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 endpoints de produits exposent le catalogue de votre agent : le lister, obtenir un produit ou y faire une recherche sémantique. Seuls les produits actifs (publiés) sont renvoyés : les brouillons ne sont jamais exposés.

Clé publiable : pour les endpoints de lecture du catalogue, la clé API fonctionne comme une clé publiable (elle identifie votre compte et mesure l'usage ; les données du catalogue sont publiques). Vous pouvez l'utiliser sans risque depuis du code navigateur, comme une clé publiable Stripe.

## Endpoints

| Méthode | Chemin | Description |
| --- | --- | --- |
| `GET` | `/v1/products` | Lister les produits actifs |
| `GET` | `/v1/products/:id` | Obtenir un produit |
| `GET` | `/v1/products/search` | Recherche sémantique dans le catalogue |

## Lister les produits

Renvoie une liste paginée de produits actifs. Filtrez par étiquette de catégorie ou par type :

| Paramètre | Type | Description |
| --- | --- | --- |
| `limit` | `number` | 1-100, 50 par défaut |
| `offset` | `number` | Décalage de pagination, 0 par défaut |
| `tag` | `string` | Filtrer par étiquette de catégorie |
| `kind` | `string` | 'product' ou 'service' |

`GET /v1/products`

```bash
curl "https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "data": [
    {
      "_id": "prod_id_1",
      "kind": "product",
      "title": "Kit fiesta dinosaurios",
      "description": "Decoración completa para fiesta infantil",
      "media": [
        { "url": "https://api.tbit.app/media/dino-kit.jpg", "alt": "Kit fiesta", "type": "image", "position": 0 }
      ],
      "category_tags": ["fiestas", "infantil"],
      "currency": "COP",
      "base_price": 95000,
      "compare_at_price": 120000,
      "variants": [
        {
          "id": "var_id_1",
          "title": "Grande",
          "price": 95000,
          "selected_options": [{ "name": "Tamaño", "value": "Grande" }]
        }
      ],
      "created_at": "2024-09-01T12:00:00Z",
      "updated_at": "2024-09-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 134,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

## Obtenir un produit

Obtenez un produit par son id. Les brouillons, les ids inconnus et les produits d'un autre agent renvoient 404 :

`GET /v1/products/prod_id_1`

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

Réponse:

```json
{
  "error": {
    "code": "NOT_FOUND"
  }
}
```

## Recherche sémantique

La recherche utilise des embeddings vectoriels, pas une correspondance de mots-clés : une requête comme "fête dinosaures" trouve des produits de fête sur le thème des dinosaures même si aucun titre ne contient ces mots exacts. La recherche est limitée à 30 requêtes par minute par clé (en plus de la limite globale de 100/min). Chaque résultat peut inclure un score de pertinence :

`GET /v1/products/search`

```bash
curl "https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "data": [
    {
      "_id": "prod_id_1",
      "kind": "product",
      "title": "Kit fiesta dinosaurios",
      "currency": "COP",
      "base_price": 95000,
      "score": 0.91
    }
  ]
}
```

## L'objet produit

Tous les endpoints renvoient des objets produit avec la forme suivante. base_price est un nombre simple dans la devise du catalogue (p. ex. COP, sans sous-unités). compare_at_price n'est présent que lorsque le produit est en promotion et il est toujours supérieur à base_price :

| Champ | Type | Description |
| --- | --- | --- |
| `_id` | `string` | Id du produit |
| `kind` | `string` | 'product' ou 'service' |
| `title` | `string` | Titre du produit |
| `description` | `string` | Description du produit |
| `media` | `array` | Tableau de { url, alt?, type: 'image' \| 'video', position? } |
| `category_tags` | `string[]` | Étiquettes de catégorie |
| `currency` | `string` | Code de devise ISO 4217 |
| `base_price` | `number` | Prix en nombre simple (p. ex. COP, sans sous-unités) |
| `compare_at_price` | `number?` | Seulement en promotion ; toujours supérieur à base_price |
| `variants` | `array` | Tableau de { id, title, price, compare_at_price?, selected_options: [{ name, value }] } |
| `created_at` | `string` | Horodatage ISO 8601 |
| `updated_at` | `string` | Horodatage ISO 8601 |