Introducción a la API REST

#La API de Karrito

La API REST v1 te permite acceder a los datos de tu tienda de forma programática. Puedes gestionar productos, categorías, pedidos, descuentos, reseñas, clientes, envíos y estadísticas.

Todo lo que ves en tu panel de admin, lo puedes hacer por API.

#Base URL

Todas las peticiones van a:

https://karrito.shop/api/v1

Siempre HTTPS. Las peticiones HTTP sin cifrar se rechazan con un redirect 301.

#Endpoints disponibles

La API v1 cubre 9 recursos con operaciones completas:

#Detalle por recurso

Store — Configuración general de tu tienda (nombre, slug, WhatsApp, moneda, template de mensaje, descripción). PUT actualiza parcialmente.

Products — CRUD completo. Soporta nombre, precio, precio comparativo, descripción, imagen, categoría, estado activo/inactivo. DELETE es soft delete (el producto se marca como eliminado pero los datos se conservan).

Categories — CRUD completo. Nombre, slug, posición y estado activo.

Orders — Solo lectura + cambio de estado. Los pedidos se crean desde el checkout de WhatsApp. Puedes cambiar el estado siguiendo el flujo: pending → confirmed → shipped → delivered (o cancelled desde cualquier estado previo a delivered).

Discounts — CRUD completo. Código, tipo (percentage o fixed), valor, fecha de expiración, estado activo.

Reviews — Lectura + moderación. Puedes filtrar por estado (pending, approved, rejected) y aprobar o rechazar reseñas individuales.

Customers — Solo lectura. Lista de clientes con historial de pedidos.

Stats — Solo lectura. Estadísticas agregadas: total de ordenes, revenue, productos más populares, tasa de conversión.

Shipping — CRUD completo. Nombre, precio, descripción, tiempo estimado de entrega.

#Formato de respuestas

Todas las respuestas son JSON con Content-Type: application/json.

#Respuesta exitosa (recurso individual)

{
  "data": {
    "id": "clx1a2b3c4d5e6f7g8h9i0",
    "name": "Camisa azul",
    "price": 25.00
  }
}

#Respuesta exitosa (lista de recursos)

{
  "data": [
    { "id": "clx1a2b3c4d5e6f7g8h9i0", "name": "Camisa azul" },
    { "id": "clx2b3c4d5e6f7g8h9i0j1", "name": "Pantalon negro" }
  ],
  "total": 47,
  "limit": 50,
  "offset": 0
}

#Respuesta de error

{
  "error": "API key invalida o expirada",
  "code": "UNAUTHORIZED"
}

#Paginación

Todos los endpoints que devuelven listas soportan paginación con dos parametros:

Ejemplo: obtener la segunda página de 20 productos:

curl "https://karrito.shop/api/v1/products?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

La respuesta incluye total para que sepas cuantas páginas hay:

{
  "data": [],
  "total": 47,
  "limit": 20,
  "offset": 20
}

Con total: 47 y limit: 20, sabes que hay 3 páginas (0-19, 20-39, 40-46).

#Rate limiting

La API tiene límites de uso para proteger la estabilidad del servicio:

• 100 requests por minuto por API key para endpoints autenticados
• Límites específicos por endpoint (ver rate limiting)

Cuando excedes el limite, recibes un 429 Too Many Requests. Los headers de respuesta te dicen cuanto falta para poder hacer la siguiente petición.

#Versionado

La API usa versionado en la URL: /api/v1/. Cuando lancemos cambios que rompan compatibilidad, serán en /api/v2/ y la versión anterior seguira funcionando por al menos 6 meses.

Cambios que NO rompen compatibilidad (y se aplican sin nueva versión):

• Agregar campos nuevos a las respuestas
• Agregar endpoints nuevos
• Agregar parametros opcionales

Cambios que SI requieren nueva versión:

• Eliminar o renombrar campos existentes
• Cambiar el tipo de un campo
• Cambiar el comportamiento de un endpoint

#Requisitos

Para usar la API necesitas:

• Una cuenta en Karrito con plan Pro o Lifetime
• Una API key generada desde tu panel de admin
• HTTPS en todas las peticiones

#También disponible via MCP

Si prefieres gestionar tu tienda desde un asistente de IA (Claude, Cursor, Windsurf), el MCP Server de Karrito expone los 34 tools que cubren toda la API sin escribir código.

#Siguiente paso

Aprende a autenticarte con tu API key para empezar a hacer peticiones.