# Prodotti

> Leggi il tuo catalogo prodotti e fai ricerca semantica

- Pagina: https://tbit.app/it/docs/api/products
- 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

Gli endpoint dei prodotti espongono il catalogo del tuo agente: elencarlo, ottenere un singolo prodotto o fare una ricerca semantica. Vengono restituiti solo i prodotti attivi (pubblicati): le bozze non vengono mai esposte.

Chiave pubblicabile: per gli endpoint di lettura del catalogo la chiave API funziona come una chiave pubblicabile (identifica il tuo account e misura l'uso; i dati del catalogo sono pubblici). Puoi usarla in sicurezza dal codice del browser, proprio come una chiave pubblicabile di Stripe.

## Endpoint

| Metodo | Percorso | Descrizione |
| --- | --- | --- |
| `GET` | `/v1/products` | Elenca i prodotti attivi |
| `GET` | `/v1/products/:id` | Ottieni un singolo prodotto |
| `GET` | `/v1/products/search` | Ricerca semantica nel catalogo |

## Elencare i prodotti

Restituisce un elenco paginato di prodotti attivi. Filtra per etichetta di categoria o per tipo:

| Parametro | Tipo | Descrizione |
| --- | --- | --- |
| `limit` | `number` | 1-100, predefinito 50 |
| `offset` | `number` | Offset di paginazione, predefinito 0 |
| `tag` | `string` | Filtra per etichetta di categoria |
| `kind` | `string` | 'product' o '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"
```

Risposta:

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

## Ottenere un prodotto

Ottieni un prodotto per id. Bozze, id sconosciuti e prodotti di un altro agente restituiscono 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"
```

Risposta:

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

## Ricerca semantica

La ricerca usa embedding vettoriali, non la corrispondenza di parole chiave: una query come "festa di dinosauri" trova prodotti per feste a tema dinosauri anche se nessun titolo contiene quelle parole esatte. La ricerca ha un limite di 30 richieste al minuto per chiave (oltre al limite globale di 100/min). Ogni risultato può includere un punteggio di pertinenza (score):

`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"
```

Risposta:

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

## L'oggetto prodotto

Tutti gli endpoint restituiscono oggetti prodotto con la forma seguente. base_price è un numero semplice nella valuta del catalogo (es. COP, senza unità minori). compare_at_price è presente solo quando il prodotto è in offerta ed è sempre maggiore di base_price:

| Campo | Tipo | Descrizione |
| --- | --- | --- |
| `_id` | `string` | Id del prodotto |
| `kind` | `string` | 'product' o 'service' |
| `title` | `string` | Titolo del prodotto |
| `description` | `string` | Descrizione del prodotto |
| `media` | `array` | Array di { url, alt?, type: 'image' \| 'video', position? } |
| `category_tags` | `string[]` | Etichette di categoria |
| `currency` | `string` | Codice valuta ISO 4217 |
| `base_price` | `number` | Prezzo come numero semplice (es. COP, senza unità minori) |
| `compare_at_price` | `number?` | Solo quando è in offerta; sempre maggiore di base_price |
| `variants` | `array` | Array di { id, title, price, compare_at_price?, selected_options: [{ name, value }] } |
| `created_at` | `string` | Timestamp ISO 8601 |
| `updated_at` | `string` | Timestamp ISO 8601 |