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.