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.
El directorio de Info excluye los grupos de demostración (kind=demo). Se conservan
su acceso público por identificador y su presencia en el directorio de pantallas.
| Endpoint | Función |
|---|---|
GET /api/v4/groups |
Lista los grupos accesibles |
GET /api/v4/groups/<group_id> |
Describe un grupo y su configuración |
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.