Saltar a contenido

Organización

Estas entidades responden a dos preguntas que se plantean antes de cualquier llamada: sobre qué perímetro actúa y en nombre de quién.

groups

Grupo — la red explotada. Es la unidad de aislamiento de la API: todas las demás entidades pertenecen a un grupo, y un dato nunca existe fuera del suyo. Un operador que gestiona varias redes dispone de un grupo por red.

Identificador <group_id>, presente en la ruta de casi todos los endpoints. El grupo contiene su configuración — GTFS publicados, opciones de explotación, parámetros de información al viajero — de la que dependen las entidades que contiene.

El grupo se gestiona desde las aplicaciones Pysae; sus endpoints no se publican en la especificación pública, ya que un integrador trabaja sobre un grupo que se le comunica.

teams

Equipo — una subdivisión del grupo, utilizada para compartimentar la explotación: una cochera, un sector geográfico, un subcontratista. Los conductores y los vehículos están vinculados a él, y un usuario puede tener acceso únicamente a los datos de determinados equipos.

Identificador <team_id>. La vinculación es múltiple: tanto un conductor como un vehículo llevan una lista de equipos.

Endpoint Función
GET /api/v4/groups/<group_id>/teams Lista los equipos del grupo

users

Usuario — una cuenta humana que accede al grupo, normalmente un regulador o un responsable de explotación. No debe confundirse con el conductor, que no es un usuario: se identifica en la aplicación Pysae Driver, no en la interfaz de explotación.

Identificador <user_id>. Un usuario puede pertenecer a varios grupos, con un rol propio en cada uno.

Endpoint Función
GET /api/v4/groups/<group_id>/users/me Describe al usuario autenticado en el grupo

roles

Rol — el nivel de acceso de un usuario en un grupo determinado. Condiciona los endpoints que puede llamar y los datos visibles; un rol restringido a determinados equipos solo ve sus conductores y vehículos.

El rol no tiene identificador propio: vincula un usuario a un grupo y, por tanto, se manipula mediante <user_id>.

Endpoint Función
GET /api/v4/groups/<group_id>/roles Lista los roles asignados en el grupo

api-keys

Clave de API — un identificador persistente y revocable, destinado a las integraciones automatizadas. Es el mecanismo recomendado para llamar a la API desde un sistema de terceros, en lugar de una sesión abierta con una contraseña.

Identificador <api_key_id>. Una clave está vinculada a exactamente un principal — un usuario, un dispositivo o un rol — y puede restringirse por alcance y por fecha de caducidad. Una clave puede abarcar varios grupos.

Endpoint Función
GET /api/v4/groups/<group_id>/api-keys Lista las claves del grupo
POST /api/v4/groups/<group_id>/api-keys Crea una clave en el grupo
DELETE /api/v4/groups/<group_id>/api-keys/<api_key_id> Revoca una clave

La creación de una clave y su uso en una petición se detallan en la página Autenticación.