API pública · v1

https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1

La versión mayor va en la ruta (/v1). Los cambios incompatibles estrenan /v2 sin romper /v1; los aditivos (campos nuevos opcionales) no suben la versión — tu cliente debe ignorar campos desconocidos. HTTPS obligatorio. GET /v1 (sin auth) devuelve el catálogo de endpoints.

Cada credencial está atada a un proyecto y a un conjunto de scopes. No existen credenciales globales que crucen tiendas. La API key se envía como Bearer token:

curl https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/products \
  -H "Authorization: Bearer rk_live_8f3c9a2b7e1d4056a9c2f8e4b6d1093a"

• Prefijo rk_live_ para producción, rk_test_ para desarrollo (misma tienda; te permite integrar y rotar sin tocar la key de producción).
• La key se muestra una sola vez. Se guarda solo un hash SHA-256 irreversible: si se pierde, se rota — no se puede recuperar.
• Solo servidor. Nunca la incrustes en código cliente, apps móviles ni variables públicas.

El token solo puede hacer lo que sus scopes permiten (mínimo privilegio). Un scope faltante devuelve 403 forbidden_scope.

• Validación estricta. Todo body y query se valida en el servidor; los campos desconocidos se rechazan con 400. Las URLs de imágenes deben ser HTTPS.
• Límite de cuerpo: 512 KB por request (413 si se supera).

• JSON en request y response. Fechas en ISO 8601 UTC. IDs en UUID v4.
• Dinero: los precios de producto van en centésimas (valor × 100) junto a currency (CLP · USD · UF). Ej: price: 1990000 + CLP = $19.990. El total de un pedido va en pesos CLP enteros.
• En PATCH, un campo omitido no se toca; un campo con null explícito lo limpia (donde el schema lo permita).

Un recurso individual se devuelve envuelto con su request_id:

{
  "data": { "id": "3f9c1e2a-…", "name": "Polera Reciba" },
  "request_id": "req_7Yk2m9Qp"
}

Códigos HTTP estándar. El cuerpo siempre tiene un type legible por máquina, un message humano (y field cuando aplica), más un request_id seguro de compartir con soporte.

{
  "error": {
    "type": "validation_error",
    "message": "Solo se permiten URLs HTTPS",
    "field": "images.0"
  },
  "request_id": "req_53e0d6990f91"
}

Límites por credencial y ventana deslizante: lectura 120 req/min, escritura 40 req/min. Al exceder, la API responde 429 con Retry-After en segundos; implementa backoff exponencial con jitter — no reintentes en bucle apretado.

Las colecciones usan paginación por cursor (estable ante inserciones). Pide limit (1–100, por defecto 25) y reenvía next_cursor en cursor para la página siguiente. Cuando has_more es false, next_cursor es null.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkQXQi…",
  "request_id": "req_…"
}

Toda petición de creación (POST) acepta el header opcional Idempotency-Key (por ejemplo, un UUID). La primera respuesta se guarda 24 horas y se re-devuelve idéntica ante reintentos con el mismo cuerpo (verás el header Idempotency-Replayed: true). La misma key con un cuerpo distinto responde 409 conflict.

curl -X POST https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/products \
  -H "Authorization: Bearer rk_live_…" \
  -H "Idempotency-Key: 9f1c2e7a-4b8d-4c6f-a0e1-3d2b5c7a9f10" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Polera Reciba", "slug": "polera-reciba", "price": 1990000 }'

Úsala siempre al crear productos: un reintento por timeout de red no generará duplicados.

Notas del objeto product: stock: null = ilimitado, 0 = agotado; price/compareAtPrice en centésimas + currency; metadata acepta hasta 50 atributos personalizados (string o number); slug único dentro del proyecto.

curl -X POST https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/products \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Polera Reciba",
    "slug": "polera-reciba",
    "price": 1990000,
    "currency": "CLP",
    "stock": 42,
    "tags": ["ropa"],
    "images": ["https://cdn.ejemplo.com/polera.webp"]
  }'

curl -X PATCH https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/products/860d03ea-… \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "price": 1790000, "isActive": false }'

Variantes de un producto (talla, color, …). priceOverride y stock en null heredan del producto padre. attributes es un objeto clave→valor (1–10 pares), ej. { "color": "negro", "talla": "M" }.

curl -X POST https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/products/860d03ea-…/variants \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "attributes": { "color": "negro", "talla": "M" }, "sku": "POL-NEG-M", "stock": 10 }'

Páginas del sitio, solo lectura en v1: el content es el árbol del editor visual y escribirlo crudo podría corromper el sitio. Para crear y editar páginas de forma segura usa el servidor MCP, que valida cada bloque.

Lectura y actualización de cumplimiento. Los pedidos se crean en el checkout de la tienda, nunca por la API (para no saltarse pagos ni stock). Los campos sensibles de pasarela jamás se exponen. Por defecto se excluyen los pedidos de prueba (includeTest=true para incluirlos).

curl -X PATCH https://api.y7qpdqpplczvfk4rnkgpnvgw.157.230.146.182.sslip.io/v1/orders/77aa…-… \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "shippingStatus": "in_transit", "trackingCode": "CHX-99887766" }'

Solo lectura. Incluye nombre, email, teléfono, opt-in de marketing y totales de compra. Los clientes que ejercieron su derecho de eliminación (anonimizados) no aparecen.

• Webhooks firmados con HMAC-SHA256 (order.paid, order.fulfilled, product.updated, …).
• Panel en la app para emitir, ver y rotar API keys.
• Escritura de páginas con validación de bloques (hoy: vía servidor MCP).

¿Prefieres editar tu tienda con IA en vez de escribir código? Mira el servidor MCP.