# प्रोडक्ट

> अपना प्रोडक्ट कैटलॉग पढ़ें और सिमैंटिक सर्च करें

- पेज: https://tbit.app/hi/docs/api/products
- Base URL: `https://rest-api.tbit.app/v1`
- ऑथेंटिकेशन: हर request में आपकी key के साथ `X-API-Key` header (उदाहरण इसे `TBIT_API_KEY` environment variable से पढ़ते हैं)

## परिचय

प्रोडक्ट endpoints आपके एजेंट का कैटलॉग खोलते हैं: उसकी लिस्ट देखें, कोई एक प्रोडक्ट पाएँ या उस पर सिमैंटिक सर्च चलाएँ। सिर्फ़ active (पब्लिश किए गए) प्रोडक्ट ही लौटाए जाते हैं: ड्राफ़्ट कभी नहीं दिखाए जाते।

Publishable key: कैटलॉग पढ़ने वाले endpoints के लिए API key एक publishable key की तरह काम करती है (यह आपके अकाउंट की पहचान करती है और इस्तेमाल मापती है; कैटलॉग का डेटा पब्लिक है)। इसे ब्राउज़र कोड से इस्तेमाल करना सुरक्षित है, बिल्कुल Stripe की publishable key की तरह।

## Endpoints

| Method | Path | विवरण |
| --- | --- | --- |
| `GET` | `/v1/products` | List active products |
| `GET` | `/v1/products/:id` | Get a single product |
| `GET` | `/v1/products/search` | Semantic search over the catalog |

## प्रोडक्ट की लिस्ट

Active प्रोडक्ट की पेज-दर-पेज लिस्ट लौटाता है। कैटेगरी टैग या टाइप से फ़िल्टर करें:

| Parameter | टाइप | विवरण |
| --- | --- | --- |
| `limit` | `number` | 1-100, default 50 |
| `offset` | `number` | Pagination offset, default 0 |
| `tag` | `string` | Filter by category tag |
| `kind` | `string` | 'product' or '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"
```

Response:

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

## एक प्रोडक्ट पाएँ

id से एक प्रोडक्ट पाएँ। ड्राफ़्ट, अनजान ids और किसी दूसरे एजेंट के प्रोडक्ट 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"
```

Response:

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

## सिमैंटिक सर्च

सर्च vector embeddings इस्तेमाल करता है, keyword matching नहीं: "fiesta de dinosaurios" जैसी query डायनासोर थीम वाले पार्टी प्रोडक्ट ढूँढ लेती है, भले ही किसी टाइटल में ठीक वही शब्द न हों। सर्च की सीमा हर key पर प्रति मिनट 30 requests है (100/min की ग्लोबल सीमा के अलावा)। हर नतीजे में relevance 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"
```

Response:

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

## प्रोडक्ट ऑब्जेक्ट

सभी endpoints इस ढाँचे वाले प्रोडक्ट ऑब्जेक्ट लौटाते हैं। base_price कैटलॉग की करेंसी में एक सादा नंबर है (जैसे COP, बिना छोटी इकाइयों के)। compare_at_price सिर्फ़ तब होता है जब प्रोडक्ट सेल में हो, और यह हमेशा base_price से ज़्यादा होता है:

| फ़ील्ड | टाइप | विवरण |
| --- | --- | --- |
| `_id` | `string` | Product id |
| `kind` | `string` | 'product' or 'service' |
| `title` | `string` | Product title |
| `description` | `string` | Product description |
| `media` | `array` | Array of { url, alt?, type: 'image' \| 'video', position? } |
| `category_tags` | `string[]` | Category tags |
| `currency` | `string` | ISO 4217 currency code |
| `base_price` | `number` | Price as a plain number (e.g. COP, no minor units) |
| `compare_at_price` | `number?` | Only when on sale; always higher than base_price |
| `variants` | `array` | Array of { id, title, price, compare_at_price?, selected_options: [{ name, value }] } |
| `created_at` | `string` | ISO 8601 timestamp |
| `updated_at` | `string` | ISO 8601 timestamp |