Autenticacion

#API keys

La API de Karrito usa API keys para autenticación. Cada key esta vinculada a tu tienda y tiene permisos específicos (scopes) que controlan que puede hacer.

#Generar tu API key

1. Ve a tu panel de admin en karrito.shop/admin
2. Navega a Configuración → Conexiones → Llaves de acceso
3. Haz click en Crear API key
4. Dale un nombre descriptivo (ejemplo: "Integración Google Sheets")
5. Selecciona los scopes que necesitas
6. Copia la key generada — solo se muestra una vez

Importante: Guarda tu API key en un lugar seguro. Si la pierdes, tendrás que crear una nueva. Nunca compartas tu key en código publico, repositorios, ni chats.

#Usar tu API key

Incluye la key en el header Authorization de cada petición:

Authorization: Bearer YOUR_API_KEY

#Ejemplo con curl

curl "https://karrito.shop/api/v1/products" \
  -H "Authorization: Bearer krt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

#Ejemplo con JavaScript

const response = await fetch("https://karrito.shop/api/v1/products", {
  headers: {
    "Authorization": "Bearer krt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "Content-Type": "application/json"
  }
});

const { data, total } = await response.json();
console.log(`${total} productos encontrados`);

#Scopes

Cada API key tiene scopes que limitan que puede hacer. Esto sigue el principio de mínimo privilegio — dale a cada key solo los permisos que necesita.

#Combinaciones comunes

#Errores de autenticación

#401 Unauthorized

La petición no incluye API key o la key es invalida.

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

Causas comunes:

• No incluiste el header Authorization
• La key tiene un typo
• La key fue eliminada desde el panel de admin
• El formato es incorrecto (falta el prefijo Bearer)

#403 Forbidden

La API key es valida pero no tiene permisos para este recurso.

{
  "error": "Tu API key no tiene el scope 'orders:read'",
  "code": "FORBIDDEN"
}

Solución: crea una nueva API key con los scopes necesarios o edita los scopes de la key existente desde Configuración → Conexiones → Llaves de acceso.

#Buenas practicas

• Una key por integración — Si conectas Google Sheets y Zapier, crea dos keys separadas. Asi puedes revocar una sin afectar la otra
• Minimos scopes — Si solo necesitas leer productos, no le des products:write
• Variables de entorno — Guarda la key en una variable de entorno (KARRITO_API_KEY), nunca hardcodeada en el código
• Rotar periodicamente — Crea una key nueva cada 3-6 meses y elimina la anterior

#Siguiente paso

Con tu API key lista, puedes empezar a consultar productos.