Claves y autenticación
Una tienda tiene dos tipos de clave y la API se divide según ellas. La clave pública está en la página de la tienda y solo puede hacer lo que hace un cliente. La clave secreta se queda en tu servidor y es la única que puede confirmar un precio.
Las rutas, los nombres de campo, los códigos de error, los nombres de cabecera y los ejemplos de código se quedan en inglés: son el contrato.
Clave pública y clave secreta
La clave pública viaja en la URL como ?key=. Es pública por diseño: está en el código fuente de tu página y solo funciona desde los orígenes que figuran en ella. La clave secreta viaja como Authorization: Bearer <key> y es solo para tu servidor. Un navegador ni siquiera puede enviarla al servicio: Authorization no está en la lista de cabeceras permitidas de CORS.
| Clave | Cabecera | Ruta |
|---|---|---|
| pública | ?key=pk_… | GET /cfg/v1/config/public · GET /cfg/v1/catalog/search · POST /cfg/v1/preview · POST /cfg/v1/quote · POST /cfg/v1/order · POST /cfg/v1/projects · GET /cfg/v1/projects · GET /cfg/v1/projects/{id} · POST /cfg/v1/projects/{id} · POST /cfg/v1/projects/{id}/duplicate · POST /cfg/v1/projects/{id}/reorder |
| secreta | Authorization: Bearer sk_… | POST /cfg/v1/quote/verify · GET /cfg/v1/orders/{id} |
Orígenes permitidos
Cada clave pública lleva una lista de hasta 20 orígenes: esquema, host y puerto exactamente como los envía el navegador, por ejemplo https://shop.example.com. Una solicitud desde cualquier otro origen se rechaza con 403 origin_not_allowed, incluida la solicitud preflight, y el servicio nunca responde con Access-Control-Allow-Origin: *. La lista es una señal, no una autenticación: las defensas reales son el precio calculado en el servidor y los límites de frecuencia.
Claves de prueba
Una tienda en producción puede crear hasta 3 claves de prueba (pk_test_…, sk_test_…). Una clave de prueba calcula precios sobre tu borrador validado más reciente, de modo que puedes probar un cambio antes de publicarlo. No se factura, sus pedidos no envían ningún webhook ni correo y caduca a los 30 días. Prueba y producción nunca se mezclan: un presupuesto de prueba solo se verifica con una clave secreta de prueba, un pedido de prueba solo lo ve una clave de prueba y una clave real nunca lo ve. Una clave de prueba puede incluir http://localhost como origen.
El token de proyecto
Los proyectos guardados pertenecen a un cliente, no a un inicio de sesión. El primer POST /cfg/v1/projects emite un token aleatorio (cfgpt_…) y lo devuelve una sola vez; la incrustación lo conserva y lo envía como X-Cfg-Project-Token en cada llamada posterior de proyecto. El token de otro cliente, la clave de otra tienda y un id desconocido responden todos igual: 404.
Rotación sin cortes
La rotación se hace en la consola y cada tipo tiene un solapamiento para que nada se rompa mientras cambias.
- Clave pública: la clave nueva conserva la misma lista de orígenes; la antigua sigue funcionando 168 horas por defecto (como máximo 720).
- Clave secreta: se muestra una sola vez; la antigua sigue autenticando 24 horas por defecto (como máximo 720).
- Clave de firma de presupuestos: la clave nueva firma desde ese momento; los presupuestos que firmó la antigua siguen verificándose y se pueden pedir durante hasta 31 días.
- Secreto del webhook: durante un cambio, ambos secretos firman cada entrega durante 7 días, como dos valores
v1=, de modo que tu receptor puede usar cualquiera de los dos.
Lo que nunca va en un navegador
La clave secreta y el secreto del webhook (whsec_…). Guárdalos en el entorno de tu servidor, nunca en una página, un repositorio ni un log. Si uno se filtra, rótalo en la consola.
Aquí no hay un botón «probar» a propósito: la clave secreta pertenece a tu servidor, nunca a un navegador. La tienda demo muestra la incrustación y el traspaso del pedido funcionando de principio a fin.
Información legalCondiciones del configurador (EN) ·Contrato de encargo de tratamiento (EN) ·Aviso de privacidad para compradores ·Licencias de terceros (EN)