TiendaAPI

Inicio rápido

De cero a tu primera llamada a la API en menos de 5 minutos. Al final vas a tener una tienda funcionando con productos que podés consultar vía API.

Tip: La forma rápida: cloná el starter kit (Paso 0) y tenés una tienda funcionando en minutos. La forma manual: seguí los pasos curl de abajo para entender la API a mano.

Paso 0 — Cloná el starter kit (recomendado)

El starter kit es un proyecto Next.js con catálogo, carrito y checkout ya conectados a TiendaAPI. Lo clonás, pegás tu API key y lo modificás con tu IA favorita.

git clone https://github.com/vercel/next.js tiendaapi-starter && cd tiendaapi-starter/examples/with-stripe-typescript
cp .env.example .env.local
# Editá .env.local y pegá tu API key como TIENDAAPI_KEY
pnpm install
pnpm dev

Repo: https://github.com/vercel/next.js/tree/canary/examples/with-stripe-typescript

Info: Los pasos siguientes son para entender la API "a mano" usando curl. También podés usar el playground interactivo.

Requisitos previos

  • Una cuenta en TiendaAPI (o una instalación local)
  • Tu API key (empieza con ta_) — se entrega cuando se crea tu tienda

Pasos

1

Obtené tu API key

Cuando se crea tu tienda, recibís una API key. Esta clave identifica tu tienda en cada request. Guardala segura — tratala como una contraseña.

# Tu API key tiene este formato:
ta_abc123def456ghi789jkl012mno345pqr678stu901vwx
Tip: Para desarrollo local, ejecutá pnpm db:seed para crear una tienda de demo. El script imprime la API key en la terminal.
2

Listá tus productos

Hacé tu primera llamada a la API para listar productos. Pasá tu API key en el header x-api-key.

curl -s http://localhost:3000/api/store/products \
  -H "x-api-key: YOUR_API_KEY" | jq

Respuesta:

{
  "data": [
    {
      "id": "550e8400-...",
      "name": "Remera negra clásica",
      "slug": "remera-negra-clasica",
      "price": 2500,
      "images": ["https://placehold.co/600x600/1a1a1a/ffffff?text=Remera"],
      "isActive": true
    }
  ],
  "meta": {
    "has_more": true,
    "cursor": "550e8400-...",
    "count": 20,
    "limit": 20
  }
}
Info: Los precios están en centavos. 2500 = $25.00. Ver Precios y moneda.
3

Obtené un producto específico

Buscá un producto por su slug (nombre amigable para URLs).

curl -s http://localhost:3000/api/store/products/remera-negra-clasica \
  -H "x-api-key: YOUR_API_KEY" | jq

Respuesta:

{
  "data": {
    "id": "550e8400-...",
    "name": "Remera negra clásica",
    "slug": "remera-negra-clasica",
    "description": "Remera cómoda de algodón orgánico 100%.",
    "price": 2500,
    "comparePrice": 3500,
    "images": ["https://..."],
    "isActive": true,
    "metadata": {},
    "createdAt": "2026-04-03T10:00:00.000Z"
  }
}
4

Creá un carrito

Creá un carrito vacío. Vas a recibir un token para identificarlo.

curl -s -X POST http://localhost:3000/api/store/cart \
  -H "x-api-key: YOUR_API_KEY" | jq

Respuesta:

{
  "data": {
    "id": "660e8400-...",
    "token": "cart_abc123def456..."
  }
}
Tip: Guardá el token en una cookie o localStorage. Lo vas a necesitar para todas las operaciones del carrito.
5

Agregá un producto al carrito

Agregá un producto usando el token del carrito y el ID del producto.

curl -s -X POST http://localhost:3000/api/store/cart/CART_TOKEN/items \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId": "PRODUCT_ID", "quantity": 2}'

El precio queda fijado al momento de agregar — si el precio del producto cambia después, el ítem del carrito mantiene el precio original.

6

Consultá el carrito

Obtenés el carrito completo con ítems, detalles de productos y subtotal.

curl -s http://localhost:3000/api/store/cart/CART_TOKEN \
  -H "x-api-key: YOUR_API_KEY" | jq

Respuesta:

{
  "data": {
    "id": "660e8400-...",
    "token": "cart_abc123...",
    "status": "active",
    "items": [
      {
        "id": "...",
        "productId": "550e8400-...",
        "productName": "Remera negra clásica",
        "quantity": 2,
        "priceAtAdd": 2500,
        "productImages": ["https://..."]
      }
    ],
    "subtotal": 5000,
    "itemCount": 2
  }
}
7

Creá una sesión de checkout

Enviá el token del carrito, el email del cliente y la dirección de envío para crear una sesión de Stripe Checkout. Redirigí al cliente a la URL devuelta.

curl -s -X POST http://localhost:3000/api/store/checkout \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cartToken": "cart_abc123...",
    "email": "cliente@ejemplo.com",
    "shippingAddress": {
      "name": "Juan Pérez",
      "line1": "Av. Corrientes 1234",
      "city": "Buenos Aires",
      "state": "CABA",
      "postalCode": "C1043",
      "country": "AR"
    }
  }'

Respuesta:

{
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
  }
}
Atención: Nunca procesés pagos en tu servidor. Siempre redirigí a Stripe Checkout. Después del pago, Stripe envía un webhook que crea el pedido automáticamente.

¿Qué pasa después?

  1. El cliente paga en Stripe Checkout
  2. Stripe envía el webhook checkout.session.completed a tu servidor
  3. TiendaAPI crea el pedido automáticamente (idempotente — seguro contra duplicados)
  4. El cliente es redirigido a la página de confirmación del pedido
  5. Se envía el email de confirmación (si Resend está configurado)

Próximos pasos