# Produkte

> Deinen Produktkatalog lesen und semantisch durchsuchen

- Seite: https://tbit.app/de/docs/api/products
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`)

## Überblick

Die Produkt-Endpoints legen den Katalog deines Agenten offen: auflisten, ein einzelnes Produkt abrufen oder semantisch darin suchen. Es kommen nur aktive (veröffentlichte) Produkte zurück: Entwürfe werden nie offengelegt.

Veröffentlichbarer Schlüssel: Für die lesenden Katalog-Endpoints funktioniert der API-Schlüssel wie ein veröffentlichbarer Schlüssel (er identifiziert dein Konto und misst die Nutzung; die Katalogdaten sind öffentlich). Du kannst ihn bedenkenlos in Browser-Code verwenden, genau wie einen veröffentlichbaren Schlüssel von Stripe.

## Endpoints

| Methode | Pfad | Beschreibung |
| --- | --- | --- |
| `GET` | `/v1/products` | Aktive Produkte auflisten |
| `GET` | `/v1/products/:id` | Ein einzelnes Produkt abrufen |
| `GET` | `/v1/products/search` | Semantische Suche im Katalog |

## Produkte auflisten

Liefert eine paginierte Liste aktiver Produkte. Filtere nach Kategorie-Label oder nach Typ:

| Parameter | Typ | Beschreibung |
| --- | --- | --- |
| `limit` | `number` | 1-100, Standard 50 |
| `offset` | `number` | Paginierungs-Offset, Standard 0 |
| `tag` | `string` | Nach Kategorie-Label filtern |
| `kind` | `string` | 'product' oder '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"
```

Antwort:

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

## Ein Produkt abrufen

Ruft ein Produkt per ID ab. Entwürfe, unbekannte IDs und Produkte eines anderen Agenten liefern 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"
```

Antwort:

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

## Semantische Suche

Die Suche nutzt Vektor-Embeddings, keinen Abgleich von Schlüsselwörtern: Eine Anfrage wie "Dinosaurier-Party" findet Partyprodukte mit Dinosaurier-Motiv, auch wenn kein Titel genau diese Wörter enthält. Die Suche ist auf 30 Anfragen pro Minute pro Schlüssel begrenzt (zusätzlich zum globalen Limit von 100/min). Jedes Ergebnis kann einen Relevanz-Score enthalten:

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

Antwort:

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

## Das Produkt-Objekt

Alle Endpoints liefern Produkt-Objekte in folgender Form. base_price ist eine einfache Zahl in der Währung des Katalogs (z. B. COP, ohne Untereinheiten). compare_at_price ist nur vorhanden, wenn das Produkt im Angebot ist, und immer größer als base_price:

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `_id` | `string` | Produkt-ID |
| `kind` | `string` | 'product' oder 'service' |
| `title` | `string` | Produkttitel |
| `description` | `string` | Produktbeschreibung |
| `media` | `array` | Array aus { url, alt?, type: 'image' \| 'video', position? } |
| `category_tags` | `string[]` | Kategorie-Labels |
| `currency` | `string` | Währungscode nach ISO 4217 |
| `base_price` | `number` | Preis als einfache Zahl (z. B. COP, ohne Untereinheiten) |
| `compare_at_price` | `number?` | Nur bei Angeboten; immer größer als base_price |
| `variants` | `array` | Array aus { id, title, price, compare_at_price?, selected_options: [{ name, value }] } |
| `created_at` | `string` | ISO-8601-Zeitstempel |
| `updated_at` | `string` | ISO-8601-Zeitstempel |