Autenticación

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:

Vaya a Admin → API Access
Haga clic en Create New Application
Complete el Name y Description
Seleccione el permissions (ámbitos) que desee
Establezca un expiration date opcional para las credenciales
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:

client_id: El identificador único asignado a su aplicación por Alvys.
client_secret: El token confidencial proporcionado por Alvys al registrar la aplicación.
audience: Debe ser "https://api.alvys.com/public/".
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)

{
  "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

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

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.

NotaSi 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: <support@alvys.com>

​🔐 Creación de credenciales de aplicación de cliente

​Crear una solicitud de autorización

​🔐 Nuevo punto final de token

​URL del token

​Cuerpo de la solicitud (JSON)

​Ejemplo de tipo de contenido Curl JSON

​Ejemplo de formato codificado con formulario Curl

​Ejemplo de solicitud de token de Postman:

​🔒 Reclamación de alcance

​Alcances disponibles

​🧪 Solución de problemas

🔐 Creación de credenciales de aplicación de cliente

Crear una solicitud de autorización

🔐 Nuevo punto final de token

URL del token

Cuerpo de la solicitud (JSON)

Ejemplo de tipo de contenido Curl JSON

Ejemplo de formato codificado con formulario Curl

Ejemplo de solicitud de token de Postman:

🔒 Reclamación de alcance

Alcances disponibles

🧪 Solución de problemas