Autenticacion

#API keys

La API de Karrito usa API keys para autenticacion. Cada key esta vinculada a tu tienda y tiene permisos especificos (scopes) que controlan que puede hacer.

#Generar tu API key

1. Ve a tu panel de admin en karrito.shop/admin
2. Navega a Settings → API
3. Haz click en Crear API key
4. Dale un nombre descriptivo (ejemplo: "Integracion 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, tendras que crear una nueva. Nunca compartas tu key en codigo publico, repositorios, ni chats.

#Usar tu API key

Incluye la key en el header Authorization de cada peticion:

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 minimo privilegio — dale a cada key solo los permisos que necesita.

Scope	Descripcion
products:read	Leer productos y sus variantes
products:write	Crear, editar, y eliminar productos
categories:read	Leer categorias
orders:read	Leer ordenes y sus detalles
orders:write	Actualizar estado de ordenes

#Combinaciones comunes

Caso de uso	Scopes necesarios
Mostrar productos en tu web	products:read, categories:read
Sincronizar inventario	products:read, products:write
Dashboard de ordenes externo	orders:read
Sistema de gestion completo	Todos los scopes

#Errores de autenticacion

#401 Unauthorized

La peticion 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"
}

Solucion: crea una nueva API key con los scopes necesarios o edita los scopes de la key existente desde Settings → API.

#Buenas practicas

• Una key por integracion — 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 codigo
• 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.