La API pública de Escher V2 (/v1/*) requiere un token Bearer en cada solicitud. Crea y gestiona tokens en la página API tokens — abre el menú de cuenta en la esquina inferior izquierda de la barra lateral y elige API tokens (/settings/api-tokens).
Primero necesitas habilitar el acceso a la API
Los tokens de API están limitados. La página solo te permite crear tokens si el acceso a la API está activado en tu cuenta.
Si no está activado, la página muestra:
API access isn't enabled on your account. Contact your account manager at support@theprintspace.co.uk to request it.
Envía un email a support@theprintspace.co.uk para habilitarlo, luego vuelve a la página.
Quién necesita tokens de API
- Artistas que crean integraciones personalizadas (por ejemplo, un sitio de portafolio que dispara drops bajo demanda).
- Agencias que ejecutan múltiples cuentas de artistas mediante automatización.
- Desarrolladores que crean herramientas internas que se comunican con la API.
Si solo usas la interfaz web para crear drops manualmente, no necesitas un token.
Cómo crear uno
- Abre la página API tokens (menú de cuenta → API tokens).
- Ingresa un Token name (el campo tiene el placeholder "Token name (e.g. 'Backend CI')") para identificarlo después.
- Opcionalmente ingresa una Webhook URL — ver más abajo. El campo tiene el placeholder "Webhook URL (optional, https://…)"; déjalo en blanco o proporciona una URL completa con
https://. - Haz clic en Generate token.
- El token completo se muestra una sola vez, con la nota "Copy this token now — it will never be shown again." Cópialo inmediatamente.
- Guárdalo de forma segura — en un gestor de secretos, en tu entorno de CI/CD, o en un archivo
.envfuera del control de versiones.
Los tokens nuevos aparecen en la lista con estas columnas: Name, Prefix, Webhook, Created, Last used. Solo se almacena el prefijo — el token completo no se puede recuperar después de la creación.
Webhook URL opcional
Cada token puede llevar una webhook URL opcional con https://. Configúrala cuando generes el token, o edítala después: haz clic en el lápiz junto a la celda Webhook de un token, ingresa una URL completa con https:// (o bórrala), y guarda.
Qué puedes hacer con el token
La superficie /v1 completa está documentada en el endpoint OpenAPI (/openapi.json en el servicio API). Operaciones comunes:
- Crear drops —
POST /v1/drops. - Añadir productos a drops —
POST /v1/drops/{drop_id}/products. - Configurar variantes —
PUT /v1/drops/{drop_id}/products/{product_id}/variants. - Activar publicación —
POST /v1/drops/{drop_id}/publish. - Consultar estado de publicación —
GET /v1/drops/{drop_id}/publish-attempts/latest. - Generar recomendaciones —
POST /v1/recommendations. - Extraer estilos de página de una URL —
POST /v1/styles/extract(devuelve cinco variaciones para elegir). - Guardar un preset de estilo de página —
POST /v1/styles.
Autenticación
Pasa el token como un encabezado Bearer en cada solicitud:
Authorization: Bearer <your-token>
Un token faltante, revocado o inválido devuelve HTTP 401. Si el acceso a la API ha sido deshabilitado en la cuenta, obtendrás HTTP 403.
Límites de velocidad
- Endpoints de lectura: 120 solicitudes por minuto por usuario.
- Endpoints de escritura: 30 solicitudes por minuto por usuario.
Las llamadas excedidas obtienen HTTP 429 con un encabezado Retry-After. Los límites son por usuario, no por token, así que múltiples tokens del mismo usuario comparten el mismo bucket.
Ciclo de vida del token
- Revocar — haz clic en el botón Revoke en la fila del token y confirma el diálogo ("Revoke … This cannot be undone and the token will stop working immediately."). Las solicitudes futuras con ese token devuelven 401.
- Rotar — genera un nuevo token, cambia tu integración para usarlo, luego revoca el antiguo. Sin tiempo de inactividad si lo haces en el orden correcto.
- Expiración — los tokens no expiran automáticamente por defecto. Rota cada 6–12 meses como práctica de higiene de seguridad.
No compartas
Los tokens son credenciales completas — cualquiera que tenga uno puede actuar como tú en la plataforma, incluyendo publicar drops y editar productos. Trátalos con el mismo cuidado que una contraseña.