Autenticación
- Authorization: ApiKey
- La clave API se envía exclusivamente en la cabecera Authorization de POST /api/v1/auth/token. No la incluyas en JSON, una URL ni parámetros de consulta.
- Authorization: Bearer
- Utiliza el token devuelto para las solicitudes de recursos y renuévalo según expires_at; expires_in se expresa en segundos.
¿Por qué obtener primero un token?
La clave API sirve para obtener un token. Este es válido durante 15 minutos y puede usarse en varias solicitudes. Para acceder a los recursos, envía solo el token en la cabecera Authorization: Bearer.
Las solicitudes habituales no contienen la clave API. Un token filtrado solo permite acceder hasta que caduque. Una clave API robada puede seguir permitiendo obtener nuevos tokens.
¿Cuánto dura un token?
- expires_in
- 900 segundos, es decir, 15 minutos desde su emisión. Las solicitudes no prolongan su validez.
- expires_at
- Fecha y hora de caducidad en UTC. Las restricciones de acceso vigentes pueden bloquear el token antes.
¿Cuándo obtener otro token?
Reutiliza el token en varias solicitudes y obtén otro antes de expires_at. No solicites uno nuevo antes de cada operación. Usa la clave API para obtener el nuevo token.
Acceso denegado y reintentos
- 401
- 401 no siempre significa que el token haya caducado. Si ha caducado, obtén otro y repite la lectura como máximo una vez. Si la obtención del token devuelve 401, comprueba la clave y detén los intentos automáticos.
- 403
- Ante un 403, comprueba los permisos, las restricciones IP y el plan. Un token nuevo no restablece un acceso revocado.
Restricciones de IP
- Un token de acceso no evita la comprobación de los permisos actuales de la clave, los derechos de la tienda, la revocación ni las restricciones IP.
- Cuando corresponda, restringe la clave a las direcciones de origen de la integración.
- El administrador puede editar esta lista; se aceptan como máximo 32 direcciones.
Gestión de claves
- La gestión de claves API es independiente de los permisos de la integración sobre los recursos.
- Solo owner puede conceder a los grupos permisos administrativos para ver, crear, editar o eliminar claves; cada miembro autorizado puede realizar únicamente las acciones concedidas a su grupo.
Límites de solicitudes
Engine ≥ 4.143.0. Cada respuesta de token incluye data.rate_limits de la política de la tienda vigente al emitirlo. Todas las claves comparten estos presupuestos; un token nuevo no los reinicia. Un cambio de plan puede aplicarse antes de que caduque el token.
- read_per_minute
- Solicitudes de lectura por minuto.
- write_per_minute
- Solicitudes de escritura por minuto; este valor no concede permisos de escritura.
- auth_per_minute
- Solicitudes de token por minuto, incluidos los intentos de autenticación fallidos.