# MyGPS API — τεκμηρίωση για LLMs και AI agents

> REST API της πλατφόρμας MyGPS ([app.mygps.gr](https://app.mygps.gr)) για εντοπισμό οχημάτων και διαχείριση στόλου. Base URL: `https://app.mygps.gr/api`. Όλες οι αποκρίσεις JSON εκτός όπου δηλώνεται. **Διαθέσιμο στα πλάνα Business και Enterprise, χωρίς επιπλέον χρέωση** — δεν περιλαμβάνεται στο Standard. Κάθε κλήση εκτελείται με τα δικαιώματα του λογαριασμού: ο χρήστης βλέπει μόνο τα οχήματα και τα δεδομένα που του ανήκουν ή του έχουν ανατεθεί.

Τεκμηρίωση για ανθρώπους: [Τεκμηρίωση API](https://www.mygps.gr/pages/useful/api-documentation.php)
Γενικές πληροφορίες πλατφόρμας: [llms.txt](https://www.mygps.gr/llms.txt)

## Κανόνες για AI agents — ΔΙΑΒΑΣΕ ΠΡΩΤΑ

- **Ποτέ μην αποθηκεύεις email/κωδικό σε prompts, logs ή ιστορικό συνομιλίας.** Χρησιμοποίησε token.
- **Οι εντολές (`POST /api/commands/send`) επηρεάζουν φυσικά το όχημα** — π.χ. `engineStop`, `outputControl`, `rebootDevice`. Ζήτα ρητή επιβεβαίωση από τον χρήστη πριν από ΚΑΘΕ αποστολή. Ποτέ αυτόματα, ποτέ σε batch χωρίς έγκριση.
- **DELETE είναι μη αναστρέψιμο.** Μόνο με ρητή εντολή χρήστη.
- Για ζωντανή εικόνα χρησιμοποίησε **WebSocket**, όχι polling. Το `GET /api/positions` σε βρόχο ανά δευτερόλεπτο είναι λάθος χρήση.
- Για ερωτήσεις τύπου «πόσα χιλιόμετρα έκανε το Χ τον Ιούλιο;» χρησιμοποίησε τα **reports** (συγκεντρωτικά), όχι άθροιση raw θέσεων.

## Αυθεντικοποίηση

Προϋπόθεση: ενεργό πλάνο **Business ή Enterprise**. Σε λογαριασμούς Standard τα endpoints δεν είναι διαθέσιμα — απαιτείται αναβάθμιση πλάνου (χωρίς χρέωση για το ίδιο το API).

Δύο σχήματα στο header `Authorization`:

- **Bearer token (προτεινόμενο):** `Authorization: Bearer <token>`
  Δημιουργία: στην πλατφόρμα → Ρυθμίσεις λογαριασμού → ενότητα «Token», ή με `POST /api/session/token` (με ενεργή συνεδρία), form param `expiration` σε ISO 8601. Επιστρέφει το token ως καθαρό κείμενο. Ανάκληση: `POST /api/session/token/revoke`. Το token φέρει δική του ημερομηνία λήξης.
- **Basic:** `Authorization: Basic base64(email:password)` — λειτουργεί, αλλά **μην το χρησιμοποιείς σε AI agents ή scripts**· προτίμησε token.

Εναλλακτικά, session cookie: `POST /api/session` (form: `email`, `password`) → `JSESSIONID`. `GET /api/session` = τρέχων χρήστης, `DELETE /api/session` = αποσύνδεση.

Χωρίς έγκυρη ταυτοποίηση επιστρέφεται **HTTP 401**.

## Συμβάσεις

- Ημερομηνίες/ώρες: **ISO 8601 σε UTC**, π.χ. `2026-08-01T00:00:00Z`. Ισχύει και σε αιτήματα και σε αποκρίσεις.
- Ταχύτητα: **κόμβοι (knots)**. Απόσταση: **μέτρα**. Course: μοίρες. Συντεταγμένες: δεκαδικές μοίρες WGS84.
- `deviceId` και `groupId` σε reports είναι **επαναλαμβανόμενες** παράμετροι: `?deviceId=1&deviceId=2`.
- Συλλογές (geofences, drivers, groups, maintenance, notifications) δέχονται: `all`, `userId`, `groupId`, `deviceId`, `excludeAttributes`, `limit`, `offset`, `keyword`.
- Τα ειδικά δεδομένα κάθε συσκευής βρίσκονται στο αντικείμενο `attributes` (π.χ. `ignition`, `odometer`, `fuel`, `sat`, `battery`) — το περιεχόμενο εξαρτάται από το μοντέλο και την εγκατάσταση.
- Περιορισμοί λογαριασμού μπορούν να απενεργοποιήσουν λειτουργίες (`readonly`, `deviceReadonly`, `disableReports`, `limitCommands`) — τότε επιστρέφεται σφάλμα εξουσιοδότησης.

## Οχήματα

- `GET /api/devices` — όλα τα οχήματα του λογαριασμού. Παράμετροι: `all`, `userId`, `groupId`, `projectId`, `id` (επαναλαμβανόμενο), `uniqueId` (επαναλαμβανόμενο), `excludeAttributes`.
  Πεδία: `id`, `name`, `uniqueId` (IMEI), `status` (`online` / `offline` / `unknown`), `lastUpdate`, `positionId`, `groupId`, `phone`, `model`, `contact`, `category`, `disabled`, `expirationTime`, `motionState`, `attributes`.
- `GET /api/devices/{id}` · `POST /api/devices` · `PUT /api/devices/{id}` · `DELETE /api/devices/{id}`
- `GET /api/devices/{id}/accumulators` · `PUT /api/devices/{id}/accumulators` — οδόμετρο και ώρες λειτουργίας.

## Θέσεις

- `GET /api/positions` — τελευταία γνωστή θέση κάθε οχήματος (χωρίς παραμέτρους).
- `GET /api/positions?deviceId={id}&from={ISO}&to={ISO}` — ιστορικές θέσεις διαστήματος. Επίσης `id` (επαναλαμβανόμενο) για συγκεκριμένες θέσεις, `geofenceId` για φιλτράρισμα.
  Πεδία: `deviceId`, `deviceTime`, `fixTime`, `serverTime`, `latitude`, `longitude`, `altitude`, `speed`, `course`, `address`, `accuracy`, `valid`, `attributes`.
- Εναλλακτικές μορφές με header `Accept`: KML (`application/vnd.google-earth.kml+xml`), CSV (`text/csv`), XLSX, GPX.

## Ζωντανή ροή (WebSocket)

- `wss://app.mygps.gr/api/socket` — απαιτεί ενεργή συνεδρία (cookie).
- Μηνύματα JSON με κλειδιά: `positions`, `devices`, `events` (και `logs` για διαχειριστές). Στην αρχική σύνδεση στέλνονται οι τρέχουσες θέσεις· μετά push σε κάθε μεταβολή.
- Αυτό είναι ο σωστός τρόπος για live χάρτες και ειδοποιήσεις.

## Αναφορές

Κοινές παράμετροι: `deviceId` (επαναλαμβανόμενο), `groupId` (επαναλαμβανόμενο), `from`, `to` (ISO 8601).
JSON από προεπιλογή. Για **XLSX** στείλε header `Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`.

- `GET /api/reports/summary` — σύνοψη ανά όχημα: απόσταση, μέγιστη/μέση ταχύτητα, ώρες κινητήρα, καύσιμο όπου υπάρχει. Extra param: `daily=true` για ημερήσια ανάλυση.
- `GET /api/reports/trips` — ταξίδια: έναρξη/λήξη (χρόνος, θέση, διεύθυνση), απόσταση, διάρκεια, μέση/μέγιστη ταχύτητα, οδηγός.
- `GET /api/reports/stops` — στάσεις: θέση, άφιξη/αναχώρηση, διάρκεια, ώρες κινητήρα σε στάση.
- `GET /api/reports/events` — συμβάντα διαστήματος. Extra param: `type` (επαναλαμβανόμενο· `allEvents` για όλα).
- `GET /api/reports/route` — αναλυτικές θέσεις διαδρομής, για χαρτογράφηση.
- `GET /api/reports/geofences` · `GET /api/reports/circle-passage` · `GET /api/reports/combined` — ειδικές αναφορές.
- `GET /api/reports` · `POST /api/reports` — αποθηκευμένες/προγραμματισμένες αναφορές.

## Συμβάντα (event types)

`deviceOnline`, `deviceOffline`, `deviceUnknown`, `deviceInactive`, `deviceMoving`, `deviceStopped`, `deviceOverspeed`, `deviceFuelDrop`, `deviceFuelIncrease`, `geofenceEnter`, `geofenceExit`, `ignitionOn`, `ignitionOff`, `alarm`, `maintenance`, `maintenanceDue`, `driverChanged`, `commandResult`, `media`.

## Γεωφράχτες

- `GET /api/geofences` · `POST` · `PUT /api/geofences/{id}` · `DELETE /api/geofences/{id}`
- Πεδίο `area` σε **WKT**: `CIRCLE (lat lon, radius)`, `POLYGON ((lat lon, lat lon, ...))`, `LINESTRING (...)`.
- Σύνδεση με όχημα: `POST /api/permissions` με `{"deviceId": X, "geofenceId": Y}` (και `DELETE` για αποσύνδεση).

## Ειδοποιήσεις

- `GET /api/notifications` · `POST` · `PUT /api/notifications/{id}` · `DELETE /api/notifications/{id}`
- `GET /api/notifications/types` — διαθέσιμοι τύποι συμβάντων.
- `GET /api/notifications/notificators` — διαθέσιμα κανάλια (web, mail, sms, firebase, telegram, pushover, whatsapp, command — ανάλογα με τη διαμόρφωση του server).
- Πεδία: `type`, `notificators` (CSV), `always` (όλα τα οχήματα) ή σύνδεση ανά όχημα μέσω `/api/permissions`, προαιρετικά `calendarId` για χρονικό παράθυρο.

## Οδηγοί, ομάδες, συντηρήσεις

- `GET/POST/PUT/DELETE /api/drivers` — `name`, `uniqueId` (κωδικός κάρτας/iButton).
- `GET/POST/PUT/DELETE /api/groups` — ομάδες οχημάτων· `GET /api/groups/device/{deviceId}`.
- `GET/POST/PUT/DELETE /api/maintenance` — κανόνες συντήρησης: `type` (π.χ. odometer/hours), `start`, `period`. Σύνδεση με οχήματα μέσω `/api/permissions`.

## Εντολές — ΜΟΝΟ με ρητή επιβεβαίωση χρήστη

- `GET /api/commands` — αποθηκευμένες εντολές.
- `GET /api/commands/send?deviceId={id}` — ποιες αποθηκευμένες εντολές μπορούν να σταλούν στο όχημα.
- `GET /api/commands/types?deviceId={id}` — υποστηριζόμενοι τύποι για το πρωτόκολλο της συσκευής.
- `POST /api/commands/send` — `{"deviceId": X, "type": "...", "attributes": {...}}`.
  Ενδεικτικοί τύποι: `custom`, `positionSingle`, `positionPeriodic`, `engineStop`, `engineResume`, `outputControl`, `rebootDevice`, `setOdometer`, `requestPhoto`, `getDeviceStatus`.
  **Το `engineStop` και το `outputControl` μπορούν να ακινητοποιήσουν όχημα. Απαιτείται ανθρώπινη επιβεβαίωση και σωστή εγκατάσταση· η ευθύνη χρήσης ανήκει στον πελάτη.**

## Λοιπά

- `GET /api/server` — ζώνη ώρας, χάρτες, μονάδες, δυνατότητες.
- `GET /api/users` · CRUD — για λογαριασμούς με υπο-χρήστες (διαχειριστές).
- `GET/POST/DELETE /api/permissions` — συνδέσεις αντικειμένων (device↔user, device↔geofence, device↔notification, device↔maintenance, device↔driver).
- `POST /api/share/device` — δημιουργία προσωρινού συνδέσμου κοινοποίησης οχήματος με χρονικό παράθυρο.

## Τι ΔΕΝ τεκμηριώνεται δημόσια

Τα ιδιόκτητα modules της MyGPS — Ψηφιακή Διακίνηση ΑΑΔΕ/myDATA, ενδοεπικοινωνία PTT,
βίντεο/κάμερες, βιβλία στόλου (συντηρήσεων, καυσίμων, ΚΤΕΟ, εξοπλισμού, ενοικιάσεων),
dispatch εργασιών, διαχείριση έργων, driver scoring, διασυνδέσεις ERP και SIM management —
**δεν έχουν δημόσια τεκμηρίωση**. Υπάρχουν και λειτουργούν, αλλά η διασύνδεση σχεδιάζεται
κατά περίπτωση με το τεχνικό τμήμα της MyGPS. Μην υποθέτεις endpoints γι' αυτά.

## Υποστήριξη

- Email: [info@mygps.gr](mailto:info@mygps.gr) · Τηλέφωνο: +30 2331 200 215
- Ωράριο: Δευτέρα–Παρασκευή 09:00–18:00, Σάββατο 10:00–14:00
- Για διασυνδέσεις ERP ή τρίτων συστημάτων: επικοινωνήστε πρώτα — προτείνουμε τον σωστό τρόπο ανά περίπτωση.