La nueva API de ShipSaving utiliza el marco OAuth 2.1, que ofrece mayor seguridad, una autorización estandarizada y mejor escalabilidad en comparación con la autenticación tradicional basada en una única API Key. Implementa el flujo Client Credentials Grant, lo que permite a los servicios backend obtener tokens de acceso de forma segura e interactuar con los recursos protegidos utilizando sus propias credenciales.
- Autenticación de dos factores: combina
client_id(app_key) yclient_secret(app_secret) para una doble verificación. - Tokens de acceso de corta duración: los tokens de acceso tienen una validez predeterminada de 30 minutos, lo que reduce el riesgo en caso de que un token sea comprometido.
- Control de acceso basado en Scope: el acceso a la API se restringe según el parámetro
scope. - Mecanismo de revocación de tokens: se proporcionan endpoints para revocar tokens y mitigar posibles exposiciones de seguridad.
| Tipo | Cuándo usarlo | Consideraciones |
|---|---|---|
| Modo de prueba | Mientras pruebas y desarrollas tu integración con ShipSaving, utiliza el modo de prueba con tus claves de prueba. En este modo puedes usar todos los servicios de ShipSaving, como consultar tarifas de envío y crear etiquetas de ejemplo, sin que se generen cargos. | Las etiquetas compradas en modo de prueba son etiquetas de ejemplo y no pueden utilizarse para envíos reales. Las tarifas obtenidas en modo de prueba pueden diferir de las tarifas reales del modo real. Los datos están completamente aislados de tu cuenta real. |
| Modo real | Cuando tu integración esté lista para producción, utiliza el modo real con tus tokens reales. En este modo puedes obtener tarifas de envío y comprar etiquetas válidas para envíos reales. | Las etiquetas compradas en modo real son válidas para envíos reales y generarán registros de transacción reales. Tu cuenta será cobrada por la compra de etiquetas. |
Regístrate para obtener una cuenta en el ShipSaving API Portal.
- Completa el formulario de registro y verifica tu correo electrónico.
- Puedes iniciar sesión antes de la verificación, pero la creación de API Keys estará deshabilitada hasta que tu correo esté verificado.
- Una vez verificado, podrás administrar tus claves y generar API Keys de prueba (test) o reales (live).
Inicia sesión en el ShipSaving API Portal y sigue los pasos en pantalla (ver el GIF a continuación) para crear tus API Keys.
Una vez generada, tu API Key debe almacenarse de forma segura: otorga acceso completo a tu cuenta. Se muestra solo una vez al momento de su creación; si cierras la ventana, no podrá recuperarse.
Utiliza tu APP Key y tu APP Secret para obtener un access_token mediante el flujo Client Credentials. Consulta la especificación del endpoint /oauth2/token para conocer todos los parámetros y la estructura de la respuesta.
curl --location 'https://x-api.shipsaving.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic U1NfTElWRV9kWG8zT3k5V0VxS1k0ZnB1Q09Nd0N6Q19QanBJRHd1SnNXQ2Y6R1hBeFFkUUZHSWR5TElFVnhPTVY1amc1TjRma19YX3R0Nzc3' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=API'Al llamar a otros endpoints de la API de ShipSaving, configura el tipo de autenticación (Auth Type) como Bearer Token e incluye tu access_token en el campo Token. Esto otorga acceso a los recursos solicitados mientras el token siga siendo válido.
- Vigencia del token: los tokens de acceso son válidos durante 30 minutos. Usar un token expirado devolverá
401 Unauthorized. - Solo un token activo por appKey: en cualquier momento, únicamente el token emitido más recientemente para un
appKeyes válido. Si solicitas dos tokens en rápida sucesión, el primero será revocado y solo el segundo podrá utilizarse. - Manejo del secreto: no incluyas el
appSecretdirectamente en el código del lado del cliente. Almacénalo de forma segura (por ejemplo, en un gestor de secretos del lado del servidor) para evitar fugas.