API pública de ZonnaGPS

Versión 1.2. Descargar especificación OpenAPI · Power BI y Excel · Zapier, Make y n8n · Entorno de pruebas

URL base: https://app.zonnagps.es/api/public/v1. El administrador de la empresa crea sus claves en Ajustes → Integraciones del mapa, eligiendo los permisos que ZonnaGPS haya habilitado para su empresa; la clave se muestra una sola vez. Autenticación: Authorization: Bearer <clave>. Cada clave accede únicamente a su cliente. El permiso debe estar habilitado para el cliente y en los scopes de la clave. Las claves antiguas conservan solo lectura.

El límite por clave se comparte entre lectura y escritura. Las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining indican el límite; un HTTP 429 incluye Retry-After. Los errores de validación devuelven HTTP 422, las referencias ajenas HTTP 404 y los permisos insuficientes HTTP 403.

Método y rutaScopeDescripción
GET /api/public/v1/driversdrivers.listConductores del cliente, con búsqueda por nombre o NIF.
POST /api/public/v1/driversdrivers.createCrear conductor del cliente.
PATCH /api/public/v1/drivers/{id}drivers.updateEditar conductor del cliente.
DELETE /api/public/v1/drivers/{id}drivers.deactivateDesactivar conductor del cliente.
POST /api/public/v1/placesplaces.createCrear lugar del cliente.
PATCH /api/public/v1/places/{id}places.updateEditar lugar del cliente.
DELETE /api/public/v1/places/{id}places.deleteDesactivar lugar del cliente (no borra el historial).
POST /api/public/v1/geofencesgeofences.createCrear geocerca del cliente.
PATCH /api/public/v1/geofences/{id}geofences.updateEditar geocerca del cliente.
DELETE /api/public/v1/geofences/{id}geofences.deleteDesactivar geocerca del cliente (no borra el historial).
PUT /api/public/v1/assets/{id}/driverassets.assign_driverAsignar conductor del cliente.
POST /api/public/v1/transport-documentsdeca.drafts.createCrear borrador DeCA del cliente.
GET /api/public/v1/webhookswebhooks.listSuscripciones creadas con esta misma clave (REST Hook de Zapier, Make o n8n).
POST /api/public/v1/webhookswebhooks.createAlta de una suscripción a eventos (REST Hook). Devuelve el secreto de firma una sola vez.
DELETE /api/public/v1/webhooks/{id}webhooks.deleteBaja de una suscripción creada con esta misma clave.
GET /api/public/v1/reports/{dataset}reports.readTablas planas paginadas en JSON o CSV: vehículos, indicadores diarios por vehículo y por conductor, alertas y DeCA emitidos.
GET /api/public/v1/assetsassets.listListado paginado de los vehículos accesibles para el cliente.
GET /api/public/v1/assets/{asset}assets.readFicha y estado operativo de un vehículo concreto.
GET /api/public/v1/assets/{asset}/positionpositions.latestÚltima posición y odómetro disponibles para el vehículo.
GET /api/public/v1/assets/{asset}/positionspositions.historyPosiciones paginadas en un intervalo máximo de 31 días.
GET /api/public/v1/alarmsalarms.listAlarmas paginadas de los vehículos accesibles para el cliente.

Ejemplo: crear un conductor

POST /api/public/v1/drivers
Authorization: Bearer <clave>
Content-Type: application/json

{"name":"Ana García","nif":"12345678Z","phone":"+34600000000"}

Las bajas de conductores son desactivaciones: conservan el historial, retiran la asignación manual y los identificadores de detección. Las geocercas de esta versión son circulares. Las altas y bajas de vehículos corresponden exclusivamente al superadministrador.

DeCA exige el módulo contratado y los campos del validador existente. Solo se crean borradores: no se emiten documentos, PDF ni firmas. Los solapamientos de conductor o vehículo devuelven HTTP 409.

Webhooks salientes

Se gestionan desde Ajustes → Integraciones (o por API, ver más abajo). Desde allí puedes enviar un evento de prueba (test.ping, con "test": true; un solo intento que no cuenta para la desactivación) y ver las últimas veinte entregas. Solo se admiten endpoints HTTPS públicos en puerto 443. No se siguen redirecciones. El secreto se muestra una vez y se guarda cifrado. Los eventos son alert.triggered, geofence.enter, geofence.exit, deca.issued y vehicle.offline (cuando se dispara la regla de falta de comunicación del cliente).

{"id":"a304321c-1234-4567-8901-123456789012","event":"geofence.enter","occurred_at":"2026-10-18T10:00:00+00:00","data":{"id":12,"device_id":34,"geofence_id":56,"latitude":40.4,"longitude":-3.7}}
X-Zonna-Event-Id: a304321c-1234-4567-8901-123456789012
X-Zonna-Signature: t=1792317600,v1=<hexadecimal HMAC-SHA256>

Firma: hash_hmac('sha256', timestamp + '.' + cuerpo_original, secreto). Comprueba con comparación de tiempo constante, rechaza marcas de tiempo alejadas más de cinco minutos y deduplica por id del evento. La marca y firma se calculan de nuevo en cada intento; el cuerpo y el id se mantienen.

Cualquier respuesta 2xx confirma la entrega. Hasta seis intentos: esperas de 60, 300, 1800, 7200 y 21600 segundos. Tras doce intentos fallidos consecutivos se desactiva el endpoint («Desactivado por fallos» en Ajustes → Integraciones, con botón Reactivar); no se envía ningún correo. Un éxito reinicia el contador. Las entregas agotadas no se reenvían al reactivar. Se registran estado HTTP, intentos y fechas; no se guardan respuestas del receptor.

La recepción es al menos una vez: el consumidor debe ser idempotente.

Suscripciones por API (REST Hook: Zapier, Make, n8n)

Las plataformas de automatización dan de alta su URL al activar un flujo y la dan de baja al pararlo. Scopes webhooks.create, webhooks.list y webhooks.delete. Una clave solo ve y borra las suscripciones que creó ella misma; las reglas de URL (HTTPS público, puerto 443), firma y reintentos son las mismas que las del panel.

POST /api/public/v1/webhooks
Authorization: Bearer <clave>
Content-Type: application/json

{"url":"https://hooks.ejemplo.es/zonnagps","events":["geofence.enter","geofence.exit"]}

HTTP 201
{"data":{"id":7,"url":"https://hooks.ejemplo.es/zonnagps","events":["geofence.enter","geofence.exit"],"enabled":true,"status":"active","source":"api"},"secret":"<64 caracteres, solo ahora>"}

DELETE /api/public/v1/webhooks/7

Para buscar conductores (por ejemplo, antes de asignarlos): GET /api/public/v1/drivers?search=Ana o ?nif=12345678Z; los desactivados solo salen con include_inactive=1. Para buscar un vehículo por matrícula: GET /api/public/v1/assets?search=1234ABC.

Enlace de datos: Power BI y Excel

Tablas planas de solo lectura con el scope reports.read: GET /api/public/v1/reports/{tabla}. Siempre del cliente de la clave y de los vehículos que tiene visibles.

TablaContenidoFiltro de fechas
vehiclesVehículos visibles para el cliente.
asset_id, name, plate, identifier, device_type, provider, status, last_position_at		—
vehicle-dailyIndicadores diarios por vehículo: km, horas, ralentí, fuera de horario, paradas, excesos, alertas, velocidad máxima, conductor principal y combustible.
date, asset_id, vehicle_name, plate, km, active_hours, idle_hours, idle_source, out_of_hours_hours, stops, exceedances, alerts_total, max_speed_kph, first_move_at, last_move_at, main_driver_id, main_driver_name, fuel_used_l		Día
driver-dailyIndicadores diarios por conductor y vehículo.
date, driver_id, driver_name, asset_id, vehicle_name, plate, km, active_hours, idle_hours, out_of_hours_hours, exceedances, alerts_total, first_move_at, last_move_at		Día
alertsAlertas disparadas por las reglas del cliente.
id, created_at, rule_name, condition_type, severity, status, asset_id, vehicle_name, plate		Fecha de la alerta
decaDeCA emitidos, en curso o terminados (sin el contenido legal del documento).
id, reference, document_type, status, version, service_starts_at, service_ends_at, delivered_at, driver_id, driver_name, vehicle_plate		Inicio del servicio

Parámetros: from y to (AAAA-MM-DD; por defecto los últimos 30 días; máximo 366 días por petición), page, per_page (por defecto 1000, máximo 5000 filas), format=json|csv (o cabecera Accept: text/csv) y delimiter=semicolon para Excel en español. Además del límite general de la clave, el enlace de datos admite 30 peticiones por minuto. Los indicadores diarios son de días cerrados (se calculan cada noche); el día en curso aparece al día siguiente. Las horas van en ISO 8601 y los decimales con punto.

JSON: {"data":[…],"meta":{"columns":[…],"current_page":1,"last_page":3,"total":12000,"next_page_url":"…"}}. CSV: UTF-8 con BOM, primera fila con los nombres de columna y la paginación en las cabeceras X-Total-Count, X-Page, X-Last-Page y Link: <…>; rel="next".

Power BI Desktop

  1. Inicio → Obtener datos → Web → Avanzado.
  2. Partes de la dirección URL: https://app.zonnagps.es/api/public/v1/reports/vehicle-daily?from=2026-10-01&to=2026-10-31&format=csv.
  3. Parámetros de encabezado de solicitud HTTP: Authorization = Bearer TU_CLAVE_DE_API.
  4. Si pregunta cómo autenticarse, elige Anónimo (la clave ya va en la cabecera) y acepta.
  5. Para más de una página o para la actualización programada en el servicio de Power BI, usa la consulta de ejemplo: zonnagps-enlace-de-datos.pq (Obtener datos → Consulta en blanco → Editor avanzado). Recorre todas las páginas y pone los tipos de columna.

Excel (Microsoft 365)

  1. Datos → Obtener datos → De otras fuentes → Desde la web → Avanzado.
  2. Misma URL (añade &delimiter=semicolon si tu Excel usa punto y coma) y la cabecera Authorization: Bearer TU_CLAVE_DE_API.
  3. Acceso Anónimo → Cargar. Para refrescar: Datos → Actualizar todo. Para varias páginas usa también el fichero .pq.

La clave da acceso a los datos de tu empresa: no la compartas en libros que vayan a salir de ella. Lo más seguro es una clave dedicada solo con reports.read, que se revoca en Ajustes → Integraciones si el libro se filtra.

Entorno de pruebas

Las pruebas no se hacen con claves de producción: ZonnaGPS da acceso a https://pruebas.app.zonnagps.es con la empresa de demostración (datos ficticios), donde se crean claves y webhooks propios de ese entorno. Para cambiar de entorno basta con la URL base: https://pruebas.app.zonnagps.es/api/public/v1. Las claves de un entorno no valen en el otro.