Guía del sistema¶
Esta guía explica cómo se articulan los objetos de la API: de dónde proceden los datos, qué los transforma y dónde leerlos. Complementa el glosario, que define cada entidad por separado.
Orden de lectura¶
Las cinco páginas se leen en este orden, que sigue el recorrido de los datos en el sistema.
| Paso | Página | Qué se entiende en ella |
|---|---|---|
| 1 | Referencia GTFS | Cómo entra la oferta teórica en el sistema y qué GTFS es el de referencia |
| 2 | Expediciones | Qué distingue una expedición prevista de una expedición realizada, y cómo designarla sin ambigüedad |
| 3 | Tiempo real | Cómo llegan los datos de campo y qué se difunde a los viajeros |
| 4 | Explotación | Quién conduce qué, y cómo se contrasta lo previsto con lo realizado |
| 5 | Estadísticas y exportaciones | Cómo extraer los datos de forma masiva para analizarlos |
Una página queda fuera de este orden: Estaciones ferroviarias describe la referencia de las estaciones de viajeros de SNCF, el único endpoint de la API sin grupo y sin autenticación. Léala si vincula paradas de su red a estaciones; en caso contrario, puede ignorarla.
El grupo, requisito previo de toda llamada¶
Un grupo es una red explotada y la unidad de aislamiento de la API: casi todos los endpoints llevan el prefijo /groups/<group_id>, y un dato nunca existe fuera del grupo que lo contiene. Por tanto, antes de cualquier llamada, lo primero es saber con qué grupo se trabaja.
Un integrador recibe su <group_id> y una clave de API con los permisos correspondientes. La página Autenticación describe cómo obtener esta clave y transmitirla.
Cada grupo tiene también una clasificación, el campo kind: customer, demo, internal o test. Un grupo nunca clasificado no tiene valor almacenado y se lee como customer. Solo un superusuario la modifica, mediante la ruta dedicada que figura a continuación; la actualización completa del grupo (PUT /api/v3/groups/<group_id>) conserva el valor almacenado, incluido un customer establecido explícitamente, sea cual sea el kind enviado.
| Endpoint | Función |
|---|---|
PUT /api/v3/groups/<group_id>/config/kind |
Clasifica el grupo (solo superusuario) |
Los dos tiempos del sistema¶
Toda la lectura de la API se basa en una distinción, que recorre esta guía de principio a fin.
| Teórico | Realizado | |
|---|---|---|
| Qué es | Lo que la red tiene previsto | Lo que ha ocurrido |
| Origen | El GTFS importado | Los datos transmitidos por los dispositivos de los conductores |
| Cambia cuando | Se publica un nuevo GTFS | Continuamente, durante el servicio |
| Ejemplo | Una expedición sale a las 8:05 | Salió a las 8:09, con dos paradas no atendidas |
Confundir ambos es el error más frecuente en la integración: una misma expedición tiene un horario previsto y horas de paso observadas, y ambos se leen en lugares diferentes.
Unas palabras sobre las versiones¶
La API está versionada de v2 a v5; v4 es la versión por defecto y la que utiliza esta guía. El versionado y las tres categorías de endpoints (public, internal, datahub) se describen en la página de inicio.