## Autenticación

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.

### Características principales de seguridad

- **Autenticación de dos factores**: combina `client_id` (`app_key`) y `client_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.


### Modo de prueba vs. Modo real

| 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. |


### Proceso de autenticación

#### Crea tu cuenta de ShipSaving

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)**.


#### Genera tu API Key

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.

Image description
ADVERTENCIA
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.

#### Obtén el Access Token

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
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'
```

#### Realiza la solicitud

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.

Nota
1. **Vigencia del token**: los tokens de acceso son válidos durante 30 minutos. Usar un token expirado devolverá `401 Unauthorized`.
2. **Solo un token activo por appKey**: en cualquier momento, únicamente el token emitido más recientemente para un `appKey` es válido. Si solicitas dos tokens en rápida sucesión, el primero será revocado y solo el segundo podrá utilizarse.
3. **Manejo del secreto**: no incluyas el `appSecret` directamente 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.