Introducción a la API REST
Overview de la API REST v1 de Karrito: endpoints, formato de respuestas, paginación y versionado.
#¿Para qué sirve la API de Karrito?
La API REST v1 permite consultar y modificar recursos de una tienda mediante las operaciones expuestas. No se promete que todas las funciones del panel tengan un endpoint equivalente. La API de administración pertenece a Pro y requiere una llave válida y permisos.
#Base y autenticación
https://karrito.app/api/v1Usa HTTPS y Authorization: Bearer <tu_llave>. Cuando la llave alcance varias tiendas, selecciona la tienda con Karrito-Store. Consulta Autenticación.
#Referencias principales
| Recurso | Qué documenta esta guía |
|---|---|
| Productos | Lectura, búsqueda, creación, actualización y borrado lógico. |
| Categorías | Listado, estados y pertenencias. |
| Pedidos | Lectura, filtros de pedidos reales/prueba y cambios permitidos. |
| Webhooks | Eventos, firma y entrega a un servidor propio. |
| Errores | Interpretación de HTTP y cuerpos de respuesta. |
| Rate limiting | Cuotas y reintentos acotados. |
La API expone además operaciones de otros recursos, como tienda, descuentos, clientes, reseñas y envíos. Comprueba el contrato de cada operación antes de usarla; no infieras escritura porque exista lectura ni instalación porque exista documentación.
#Formato y paginación
Los listados habituales usan { data, total, limit, offset }. Un recurso individual suele usar { data }; revisa su contrato concreto. Los campos decimales pueden llegar como texto y los valores opcionales pueden ser null.
Los listados documentados de productos, categorías y pedidos usan limit de 50 por defecto y máximo 100, y offset desde cero. Los filtros de estado y cobertura importan: productos/categorías consultan activos por defecto; pedidos puede incluir pruebas si no filtras kind.
#Límites y cambios de estado
La cuota autenticada es 60 peticiones por minuto por llave. Consulta Rate limiting para manejar 429.
Los estados de pedidos de esta API son PENDING, COMPLETED y CANCELLED. El servidor valida las transiciones. Cambiar un estado no efectúa automáticamente un pago o envío externo.
#API, checkout y asistentes de IA
El checkout público y la API de administración tienen alcances diferentes. Para asistentes consulta Karrito desde IA y MCP: una skill o un futuro conector no acredita cobertura de toda la API.
Consulta SDKs y ejemplos.