# 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. Κάθε κλήση εκτελείται με τα δικαιώματα του λογαριασμού: ο χρήστης βλέπει μόνο τα οχήματα και τα δεδομένα που του ανήκουν ή του έχουν ανατεθεί.

Τελευταίος έλεγχος: 2026-08-10.
Τεκμηρίωση για ανθρώπους: [Τεκμηρίωση 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`) — τότε επιστρέφεται σφάλμα εξουσιοδότησης.

## Παραδείγματα κλήσεων

Λίστα οχημάτων του λογαριασμού:

```
curl -H "Authorization: Bearer <token>" "https://app.mygps.gr/api/devices"
```

Ιστορικές θέσεις οχήματος για ένα 24ωρο:

```
curl -H "Authorization: Bearer <token>" "https://app.mygps.gr/api/positions?deviceId=12&from=2026-08-01T00:00:00Z&to=2026-08-02T00:00:00Z"
```

Ενδεικτικό στοιχείο απόκρισης (η απόκριση είναι πίνακας από αντικείμενα θέσης):

```json
{
  "deviceId": 12,
  "fixTime": "2026-08-01T07:42:10Z",
  "latitude": 40.5241,
  "longitude": 22.2021,
  "speed": 31.2,
  "course": 118.0,
  "address": "Ελ. Βενιζέλου 62, Βέροια",
  "valid": true,
  "attributes": { "ignition": true, "odometer": 152340000, "sat": 11 }
}
```

Οι τιμές είναι ενδεικτικές· τα πεδία του `attributes` εξαρτώνται από το μοντέλο και την εγκατάσταση (βλ. Συμβάσεις). Ταχύτητα σε κόμβους, οδόμετρο σε μέτρα.

Μηνιαία σύνοψη στόλου σε XLSX (πολλαπλά οχήματα με επανάληψη του `deviceId`):

```
curl -H "Authorization: Bearer <token>" -H "Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" "https://app.mygps.gr/api/reports/summary?deviceId=12&deviceId=15&from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" -o report.xlsx
```

## Σφάλματα & όρια χρήσης

- **400** — άκυρη παράμετρος ή σώμα αιτήματος (π.χ. λάθος μορφή ημερομηνίας).
- **401** — χωρίς έγκυρη ταυτοποίηση: λείπει, έληξε ή ανακλήθηκε το token.
- **403** — ο λογαριασμός δεν έχει δικαίωμα στο αντικείμενο ή τη λειτουργία (π.χ. περιορισμοί `readonly`, `disableReports`).
- **404** — άγνωστο αντικείμενο ή διαδρομή.

Δεν δημοσιεύονται αριθμητικά rate limits. Για συνεχή δεδομένα χρησιμοποίησε το WebSocket αντί για επαναλαμβανόμενο polling· για συγκεντρωτικά μεγέθη χρησιμοποίησε τα reports (βλ. «Κανόνες για AI agents»).

## Οχήματα

- `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` — δημιουργία προσωρινού συνδέσμου κοινοποίησης οχήματος με χρονικό παράθυρο.

## Εργασίες & δρομολόγηση (Dispatch)

- `GET /api/dispatch/jobs` — λίστα εργασιών· `GET /api/dispatch/jobs/{id}` μία εργασία με στάσεις και ιστορικό.
- `PUT /api/dispatch/jobs/create` — δημιουργία εργασίας με στάσεις.
- `POST /api/dispatch/jobs/{id}/assign` — ανάθεση σε όχημα ή οδηγό.
- `POST /api/dispatch/jobs/{id}/stops` — στάσεις· `/{stopId}/status` για κατάσταση στάσης.
- `GET /api/dispatch/jobs/{id}/proofs` — αποδεικτικά παράδοσης (υπογραφή, φωτογραφία, σημείωση).
- `GET /api/dispatch/jobs/calendar` · `/export` · `/report` — ημερολόγιο και εξαγωγές.
- `POST /api/dispatch/jobs/recurring-rules` — επαναλαμβανόμενες εργασίες.
- `GET /api/dispatch/navigation/route` — υπολογισμός διαδρομής για την πλοήγηση του οδηγού.

## Webhooks & integration keys

Για διασύνδεση εξωτερικού συστήματος (π.χ. ERP) με τις εργασίες. **Ξεχωριστό κλειδί από
το token χρήστη**, με μόνο τα δικαιώματα που χρειάζεται. Header: `X-MyGPS-Dispatch-Key`
(εναλλακτικά `Authorization: Bearer <key>`).

- `POST /api/dispatch/jobs/integrations/api-keys` — δημιουργία integration key.
- `POST /api/dispatch/jobs/public-api/jobs` — δημιουργία εργασίας από εξωτερικό σύστημα. Σώμα: `{"job": {...}, "stops": [{...}]}`.
- `POST /api/dispatch/jobs/integrations/webhooks` — εγγραφή webhook (URL + τύποι συμβάντων).
- `GET /api/dispatch/jobs/integrations/webhook-deliveries` — ιστορικό αποστολών· `/{deliveryId}/retry` για επανάληψη.

Τύποι συμβάντων webhook: `job.created`, `job.updated`, `job.status.changed`,
`stop.status.changed`, `proof.created`, `customer.feedback.created`,
`customer.notification.created`, `control.alert`, `test`.

## Υπόλοιπες λειτουργίες — τεκμηρίωση κατόπιν αιτήματος

Η πλατφόρμα διαθέτει API και για τις υπόλοιπες λειτουργίες της: βιβλία στόλου
(συντηρήσεις, καύσιμα, ΚΤΕΟ, εξοπλισμός, ενοικιάσεις), διαχείριση έργων, driver
scoring, βίντεο και κάμερες, ενδοεπικοινωνία PTT, και Ψηφιακή Διακίνηση ΑΑΔΕ.

**Η τεκμηρίωσή τους δεν δημοσιεύεται.** Δίνεται κατόπιν αιτήματος και σε συνεννόηση
με την τεχνική ομάδα της MyGPS, στους πελάτες που έχουν συγκεκριμένη ανάγκη
διασύνδεσης. Μην υποθέτεις endpoints, παραμέτρους ή δομές δεδομένων γι' αυτά —
παρέπεμψε στην [επικοινωνία](https://www.mygps.gr/#contact) ή στο +30 2331 200 215.

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

- **Διαχειριστικές λειτουργίες server**: ρυθμίσεις (`PUT /api/server`), cache, garbage collection, reboot, στατιστικά, audit log, διαχείριση SIM (`/api/simbase`), εσωτερικά cron/scheduler endpoints. Δεν αφορούν πελάτες.
- **Ο τρόπος υλοποίησης της διασύνδεσης με την Ψηφιακή Διακίνηση της ΑΑΔΕ / myDATA.** Η λειτουργία υπάρχει και δουλεύει, αλλά τη διασύνδεση την αναλαμβάνει το τεχνικό τμήμα της MyGPS σε συνεργασία με τον λογιστή ή τον υπεύθυνο της επιχείρησης. Μην υποθέτεις endpoints γι' αυτό.

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

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