API

Produtos

Leia o seu catálogo de produtos e faça busca semântica

Visão geral

Os endpoints de produtos expõem o catálogo do seu agente: listá-lo, obter um produto específico ou fazer uma busca semântica nele. Só são retornados produtos ativos (publicados): os rascunhos nunca são expostos.

Chave publicável: nos endpoints de leitura do catálogo a chave de API funciona como uma chave publicável (identifica a sua conta e mede o uso; os dados do catálogo são públicos). É seguro usá-la em código do navegador, igual a uma chave publicável do Stripe.

Endpoints

Método	Rota	Descrição
GET	`/v1/products`	Listar os produtos ativos
GET	`/v1/products/:id`	Obter um produto
GET	`/v1/products/search`	Busca semântica no catálogo

Listar produtos

Retorna uma lista paginada de produtos ativos. Filtre por etiqueta de categoria ou por tipo:

Parâmetro	Tipo	Descrição
`limit`	`number`	1-100, padrão 50
`offset`	`number`	Deslocamento da paginação, padrão 0
`tag`	`string`	Filtrar por etiqueta de categoria
`kind`	`string`	'product' ou 'service'

GET/v1/products

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

const response = await fetch('https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();

import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);

import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()

<?php
$ch = curl_init('https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Resposta

{
  "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
  }
}

Obter um produto

Obtenha um produto pelo id. Rascunhos, ids desconhecidos e produtos de outro agente retornam 404:

GET/v1/products/prod_id_1

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

const response = await fetch('https://rest-api.tbit.app/v1/products/prod_id_1', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();

import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/products/prod_id_1',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);

import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/products/prod_id_1',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()

<?php
$ch = curl_init('https://rest-api.tbit.app/v1/products/prod_id_1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Resposta

{
  "error": {
    "code": "NOT_FOUND"
  }
}

Busca semântica

A busca usa embeddings vetoriais, não correspondência de palavras-chave: uma consulta como "fiesta de dinosaurios" encontra produtos de festa com tema de dinossauros mesmo que nenhum título tenha essas palavras exatas. A busca tem um limite de 30 requisições por minuto por chave (além do limite global de 100/min). Cada resultado pode incluir um score de relevância:

GET/v1/products/search

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

const response = await fetch('https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();

import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);

import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()

<?php
$ch = curl_init('https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Resposta

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

O objeto produto

Todos os endpoints retornam objetos produto com o formato a seguir. base_price é um número simples na moeda do catálogo (ex.: COP, sem subunidades). compare_at_price só aparece quando o produto está em oferta e é sempre maior que base_price:

Campo	Tipo	Descrição
`_id`	`string`	Id do produto
`kind`	`string`	'product' ou 'service'
`title`	`string`	Título do produto
`description`	`string`	Descrição do produto
`media`	`array`	Array de { url, alt?, type: 'image' \| 'video', position? }
`category_tags`	`string[]`	Etiquetas de categoria
`currency`	`string`	Código de moeda ISO 4217
`base_price`	`number`	Preço como número simples (ex.: COP, sem subunidades)
`compare_at_price`	`number?`	Só quando está em oferta; sempre maior que base_price
`variants`	`array`	Array de { id, title, price, compare_at_price?, selected_options: [{ name, value }] }
`created_at`	`string`	Timestamp ISO 8601
`updated_at`	`string`	Timestamp ISO 8601