Introduccion a la API REST

#La API de Karrito

La API REST v1 te permite acceder a los datos de tu tienda de forma programatica. Puedes gestionar productos, categorias, pedidos, descuentos, resenas, clientes, envios y estadisticas.

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:

Recurso	GET	POST	PUT	DELETE
/store	Info de la tienda	-	Actualizar settings	-
/products	Listar / Obtener por ID	Crear producto	Actualizar producto	Soft delete
/categories	Listar categorias	Crear categoria	Actualizar categoria	Eliminar categoria
/orders	Listar / Obtener por ID	-	Actualizar estado	-
/discounts	Listar descuentos	Crear descuento	Actualizar descuento	Eliminar descuento
/reviews	Listar resenas	-	Moderar (aprobar/rechazar)	Eliminar resena
/customers	Listar / Obtener por ID	-	-	-
/stats	Analytics y metricas	-	-	-
/shipping	Listar opciones de envio	Crear opcion	Actualizar opcion	Eliminar opcion

#Detalle por recurso

Store — Configuracion general de tu tienda (nombre, slug, WhatsApp, moneda, template de mensaje, descripcion). PUT actualiza parcialmente.

Products — CRUD completo. Soporta nombre, precio, precio comparativo, descripcion, imagen, categoria, estado activo/inactivo. DELETE es soft delete (el producto se marca como eliminado pero los datos se conservan).

Categories — CRUD completo. Nombre, slug, posicion 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. Codigo, tipo (percentage o fixed), valor, fecha de expiracion, estado activo.

Reviews — Lectura + moderacion. Puedes filtrar por estado (pending, approved, rejected) y aprobar o rechazar resenas individuales.

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

Stats — Solo lectura. Estadisticas agregadas: total de ordenes, revenue, productos mas populares, tasa de conversion.

Shipping — CRUD completo. Nombre, precio, descripcion, 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"
}

#Paginacion

Todos los endpoints que devuelven listas soportan paginacion con dos parametros:

Parametro	Tipo	Default	Max	Descripcion
limit	number	50	100	Cantidad de resultados por pagina
offset	number	0	-	Cantidad de resultados a saltar

Ejemplo: obtener la segunda pagina 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 paginas hay:

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

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

#Rate limiting

La API tiene limites de uso para proteger la estabilidad del servicio:

• 100 requests por minuto por API key para endpoints autenticados
• Limites especificos 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 peticion.

#Versionado

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

Cambios que NO rompen compatibilidad (y se aplican sin nueva version):

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

Cambios que SI requieren nueva version:

• 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

#Tambien disponible via MCP

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

#Siguiente paso

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