> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Autenticación
> Autentíquese con Alvys Public API utilizando el flujo de credenciales de cliente OAuth 2.0, incluida la creación de aplicaciones de cliente, la solicitud de tokens y alcances.
Esta página explica cómo autenticarse con Alvys Public API utilizando el flujo de credenciales de cliente OAuth 2.0.
Al aprovechar OAuth 2.0, los desarrolladores pueden permitir que sus aplicaciones interactúen sin problemas con la API de Alvys en nombre de sus usuarios. Esta guía describe el proceso de autenticación y proporciona instrucciones detalladas sobre cómo obtener tokens de acceso mediante la integración directa de la aplicación.
Obtener acceso a la API
* Los clientes existentes de Alvys pueden obtener acceso a la API comunicándose con su representante de cuenta.
* Los proveedores de software independientes (ISV) deben comunicarse con el equipo de asociación Alvys.
### 🔐 Creación de credenciales de aplicación de cliente
Siga estos pasos para crear sus credenciales en el Portal de administración Alvys:
1. Vaya a **Admin → API Access**
2. Haga clic en **Create New Application**
3. Complete el **Name** y **Description**
4. Seleccione el **permissions** (ámbitos) que desee
5. Establezca un **expiration date** opcional para las credenciales
6. Haga clic en **Generate**
Después de la creación, se mostrarán sus **Client ID** y **Client Secret**, junto con los alcances incluidos para la generación de tokens. Los clientes pueden generar hasta 10 conjuntos de credenciales de cliente, pero solo se pueden editar las recién generadas.
Estos valores son confidenciales y deben almacenarse de forma segura; evite compartirlos públicamente o exponerlos en el código de front-end.
Estas credenciales se utilizan para solicitar un token de acceso a través del punto final del token de emisión.
### Crear una solicitud de autorización
Construya una URL con los siguientes parámetros en el cuerpo de la solicitud:
1. `client_id`: El identificador único asignado a su aplicación por Alvys.
2. `client_secret`: El token confidencial proporcionado por Alvys al registrar la aplicación.
3. `audience`: Debe ser `"https://api.alvys.com/public/"`.
4. `grant_type`: El tipo de flujo de concesión que se utilizará. **Debe ser `client_credentials`**
### 🔐 Nuevo punto final de token
Todas las solicitudes de tokens nuevas ahora deben utilizar el siguiente punto final:
### URL del token
```
https://auth.alvys.com/oauth/token
```
### Cuerpo de la solicitud (JSON)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"audience": "https://api.alvys.com/public/",
"grant_type": "client_credentials"
}
```
Al incluir un campo "alcance" en el cuerpo de la solicitud del token, tenga en cuenta:
* El token devuelto **siempre incluirá todos los ámbitos** que se hayan otorgado a su aplicación cliente, independientemente de lo que especifique en el campo de alcance.
* Por lo tanto, incluir un campo `scope` en la solicitud **no anula ni limita el acceso** definido por los permisos asignados en el token emitido.
* El único efecto funcional de proporcionar un campo `scope` es que la solicitud de token fallará (no autorizada) si incluye algún alcance que no se haya otorgado a su cliente.
* Si se omite el campo `scope`, el token seguirá incluyendo **todos los ámbitos** otorgados a su aplicación.
Se puede utilizar cualquier formato (JSON o codificado en formulario); ambos devolverán el mismo token y aplicarán alcances de manera idéntica.
### Ejemplo de tipo de contenido Curl JSON
```bash theme={null}
curl --request POST \
--url 'https://auth.alvys.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"audience": "https://api.alvys.com/public/",
"grant_type": "client_credentials"
}'
```
### Ejemplo de formato codificado con formulario Curl
```bash theme={null}
curl --request POST \
--url https://auth.alvys.com/oauth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'audience=https://api.alvys.com/public/' \
--data 'grant_type=client_credentials'
```
El token que reciba incluirá un reclamo de alcance (por ejemplo, `"load:read trip:create"`) y nuestro Public API aplica esos alcances en cada solicitud. Utilice el token de acceso resultante en los encabezados de su solicitud de API:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```
> `client_id` y `client_secret` se crean en el Portal de administración Alvys en Acceso API.
### Ejemplo de solicitud de token de Postman:
**El token de cada credencial de cliente está restringido a los alcances exactos que usted asigne, lo que garantiza que solo pueda acceder a los puntos finales de API correspondientes.**
***
***Nota***
*Si bien puede asignar alcances `create`, `update` y `delete` y su token los incluirá, los puntos finales de escritura correspondientes **aún no están disponibles**. En este momento, Public API solo expone operaciones de **lectura**; esos alcances adicionales están implementados para una adopción perfecta una vez que se lanza la funcionalidad de escritura.*
***
### 🔒 Reclamación de alcance
**Importante:** Los tokens heredados generados a través del flujo de autenticación `/api/authentication/{tenant_id}/token` anterior no incluyen el reclamo `scope`. Estos tokens seguirán siendo válidos temporalmente y se comportarán como si se otorgaran todos los ámbitos de solo lectura, pero esto solo se admite durante el período de transición. Todos los clientes deben migrar al nuevo flujo antes del **31 de julio de 2025** para evitar interrupciones.
Los nuevos tokens ahora siguen un modelo de permisos detallado, lo que garantiza que cada aplicación solo tenga acceso a las funciones API específicas que se le otorgaron.
Ejemplo:
```
"scope": "load:read driver:create"
```
Los ámbitos controlan el acceso a los puntos finales de API y deben seleccionarse al crear su aplicación en el Portal de administración.
### Alcances disponibles
| Entidad | Permiso | Descripción |
| --------------------- | -------------------- | ----------------------------------------------- |
| Clientes | `customer:read` | Ver registros de clientes |
| Clientes | `customer:create` | Añadir un cliente |
| Clientes | `customer:update` | Editar datos del cliente |
| Clientes | `customer:delete` | Eliminar un cliente |
| Conductores | `driver:read` | Ver perfiles conductor |
| Conductores | `driver:create` | Agregar nuevo conductor |
| Conductores | `driver:update` | Editar información conductor |
| Conductores | `driver:delete` | Eliminar un conductor |
| Combustible | `fuel:read` | Ver registros de combustible |
| Combustible | `fuel:create` | Agregar transacción de combustible |
| Combustible | `fuel:update` | Actualizar entrada de combustible |
| Combustible | `fuel:delete` | Eliminar registro de combustible |
| Facturas | `invoice:read` | Ver facturas |
| Facturas | `invoice:create` | Crear factura |
| Facturas | `invoice:update` | Editar factura |
| Facturas | `invoice:delete` | Eliminar factura |
| Cargas | `load:read` | Recuperar información carga |
| Cargas | `load:create` | Crear un carga |
| Cargas | `load:update` | Actualizar un carga |
| Cargas | `load:delete` | Eliminar un carga |
| Mantenimiento | `maintenance:read` | Ver datos de mantenimiento |
| Mantenimiento | `maintenance:create` | Evento de mantenimiento de registros |
| Mantenimiento | `maintenance:update` | Editar registro de mantenimiento |
| Mantenimiento | `maintenance:delete` | Eliminar registro de mantenimiento |
| Peajes | `toll:read` | Ver datos de peajes |
| Peajes | `toll:create` | Peaje de registro |
| Peajes | `toll:update` | Actualizar entrada de peaje |
| Peajes | `toll:delete` | Eliminar entrada de peaje |
| Remolques | `trailer:read` | Ver información del tráiler |
| Remolques | `trailer:create` | Registrar tráiler |
| Remolques | `trailer:update` | Editar registro de remolque |
| Remolques | `trailer:delete` | Quitar remolque |
| Viajes | `trip:read` | Ver detalles de viaje |
| Viajes | `trip:create` | Crear viaje |
| Viajes | `trip:update` | Actualización viaje |
| Viajes | `trip:delete` | Cancelar/eliminar viaje |
| Camiones | `truck:read` | Ver información del camión |
| Camiones | `truck:create` | Registrar camión |
| Camiones | `truck:update` | Actualizar registro de camiones |
| Camiones | `truck:delete` | Quitar camión |
| Usuarios | `user:read` | Ver usuarios |
| Usuarios | `user:create` | Agregar nuevo usuario |
| Usuarios | `user:update` | Modificar usuario |
| Usuarios | `user:delete` | Eliminar usuario |
| Visibilidad | `visibility:read` | Acceder a los datos de seguimiento |
| Visibilidad | `visibility:create` | Actualización de visibilidad del desencadenador |
| Visibilidad | `visibility:update` | Modificar datos de visibilidad |
| Visibilidad | `visibility:delete` | Eliminar entrada de seguimiento |
| Despacho Preferencias | `dispatch:read` | Ver reglas despacho |
| Despacho Preferencias | `dispatch:update` | Actualizar preferencias despacho |
| Transportistas | `carrier:read` | Ver perfiles transportista |
| Transportistas | `carrier:create` | Agregue un nuevo transportista |
| Transportistas | `carrier:update` | Actualizar detalles de transportista |
| Transportistas | `carrier:delete` | Eliminar un transportista de los registros |
***
### 🧪 Solución de problemas
* ✅ Vuelva a verificar su `client_id`, `client_secret` y `audience`
* ✅ Asegúrese de que los alcances estén asignados correctamente en el acceso API: portal de administración
* ✅ Validar que el cliente esté activo y no caducado
* ✅ Utilice solo tipos de contenido admitidos: `application/json` o `application/x-www-form-urlencoded`
* Para soporte técnico: ``