Inicio Rápido

Esta guía te lleva desde cero hasta tu primera llamada exitosa a la API de TunoCommerce. En 5 minutos tendrás un token y podrás listar productos.

Requisitos previos

Una instancia de TunoCommerce en ejecución (o acceso a una ya configurada)
Un cliente HTTP como curl, Postman, o tu lenguaje favorito
Credenciales de administrador para crear un API token

Paso 1: Obtener un API Token

Los tokens de la API (pk_*) son la forma principal de autenticarte con la API v1. Se crean desde el dashboard de administración:

Inicia sesión en el dashboard administrativo
Ve a Mi Empresa → API Tokens
Haz clic en Crear token
Dale un nombre descriptivo (ej. "Integración ERP")
Copia el token ahora — solo se muestra una vez

El token tiene el formato pk_ seguido de 64 caracteres hexadecimales, por ejemplo:

pk_a1b2c3d4e5f6...

Si estás usando el entorno de desarrollo con datos de semilla, ya tienes un token listo: pk_dev_seed_catalog_token

Paso 2: Tu primera llamada

Todos los endpoints de la API viven bajo /api/v1/. Agrega el token en el header Authorization:

curl https://tu-instancia.com/api/v1/products \
  -H "Authorization: Bearer pk_dev_seed_catalog_token"

Respuesta exitosa:

{
  "data": [
    {
      "id": "clx...",
      "name": "Playera Básica",
      "slug": "playera-basica",
      "sku": "PLY-001",
      "status": "active",
      "price": 350.00,
      "currency": "MXN",
      "brand": {
        "id": "clx...",
        "name": "Marca Propia",
        "slug": "marca-propia"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 47,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Estructura de respuestas

Todas las respuestas de la API siguen el mismo patrón:

Respuesta exitosa (recurso único)

{
  "data": {
    "id": "clx...",
    "name": "..."
  }
}

Respuesta exitosa (lista paginada)

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Respuesta de error

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "El producto solicitado no existe",
    "statusCode": 404
  }
}

Paginación

Los endpoints de listado aceptan los parámetros page y pageSize:

# Página 2 con 50 resultados por página
curl "https://tu-instancia.com/api/v1/products?page=2&pageSize=50" \
  -H "Authorization: Bearer pk_..."

Parámetro	Tipo	Default	Máximo
`page`	número	`1`	—
`pageSize`	número	`20`	`100`

Filtros y búsqueda

La mayoría de los endpoints de listado aceptan parámetros de filtro:

# Buscar productos por nombre, filtrar por estado y ordenar
curl "https://tu-instancia.com/api/v1/products?search=playera&status=active&sortBy=name&sortOrder=asc" \
  -H "Authorization: Bearer pk_..."

Consulta la Referencia API para los filtros disponibles en cada endpoint.

Manejo de errores

La API usa códigos HTTP estándar:

Código	Significado
`200`	Éxito
`201`	Recurso creado
`400`	Error de validación — revisa el cuerpo de la respuesta
`401`	No autenticado — token inválido o faltante
`403`	Sin permisos — el token no tiene acceso a este recurso
`404`	Recurso no encontrado
`409`	Conflicto — ej. slug duplicado, transición de estado inválida
`429`	Límite de velocidad excedido
`500`	Error del servidor

Ejemplo de error de validación:

curl -X POST https://tu-instancia.com/api/v1/products \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": ""}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Error de validación",
    "statusCode": 400,
    "details": [
      {
        "field": "name",
        "message": "El nombre es requerido"
      },
      {
        "field": "brandId",
        "message": "La marca es requerida"
      }
    ]
  }
}

Límites de velocidad

La API aplica rate limiting por token:

Tipo de endpoint	Límite
General	100 req/minuto
Creación de recursos (POST)	10 req/minuto

Cuando excedes el límite, recibes un 429 con el header Retry-After indicando cuándo puedes reintentar.

Próximos pasos

Autenticación — Aprende sobre los 3 métodos de autenticación, incluyendo auth de compradores
Catálogo — Gestión completa de productos, categorías y marcas
Comercio — Flujo de cotizaciones y gestión de clientes
Tiendas — API pública de storefront para frontends de cliente
Referencia API — Documentación completa de todos los endpoints

Inicio Rápido

On this page