Për zhvilluesit

Lidhni flotën me sistemin tuaj.

API REST dhe webhooks për të marrë pozicionet, udhëtimet dhe alarmet në sistemin tuaj të qirasë, logjistikës ose kontabilitetit.

Krijoni një çelës API Na kontaktoni

API v1 është aktive.

Versioni 1 është i qëndrueshëm: shtojmë vetëm fusha dhe adresa të reja. Ndryshimet që prishin përputhshmërinë shkojnë te /api/v2. Së shpejti: alarmet, zonat, shoferët, komandat dhe qiratë.

Bazat

Një API e thjeshtë, e qëndrueshme dhe e dokumentuar.

REST dhe JSON
Adresa nën /api/v1, kohë në ISO-8601 UTC, shpejtësi në km/h, distanca në metra dhe km.
Token me leje
Bearer token të krijuar nga paneli, secili vetëm me lejet që zgjidhni, me listë IP opsionale dhe skadencë.
Webhooks
Ngjarjet dërgohen te adresa juaj HTTPS, të nënshkruara me HMAC-SHA256, me riprovime deri në 24 orë.
Gabime të qarta
Çdo gabim vjen si application/problem+json (RFC 9457), me status dhe përshkrim të lexueshëm.
Faqosje me kursor
Listat kthejnë next_cursor; dërgojeni sërish si ?cursor, me ?limit deri në 100.
Kufij të qartë
Kufi kërkesash për organizatë (60 në minutë si parazgjedhje, më shumë në paketat më të larta) me headers X-RateLimit-*.

Autentikimi

Bearer token me leje

Pronarët dhe administratorët krijojnë tokena te Paneli > Integrimet. Tokeni shfaqet vetëm një herë. Çdo kërkesë e dërgon si Authorization: Bearer. Tokeni ndalon së punuari kur anulohet, skadon, ose kur pronari i tij humbet lejen përkatëse.

vehicles:readLista dhe të dhënat e automjeteve
vehicles:writeNdryshimi i emrit, targës, grupit dhe kufirit të shpejtësisë
positions:readGjendja live e një ose të gjitha automjeteve
history:readHistoriku i pozicioneve dhe rrugët GPX
reports:readUdhëtimet, ndalesat dhe përmbledhjet
webhooks:manageKrijimi, lista dhe fshirja e webhooks
alerts:readAlarmet (adresat vijnë së shpejti)
geofences:writeZonat (adresat vijnë së shpejti)
commands:writeKomandat te pajisja (adresat vijnë së shpejti)

Shembull: lista e automjeteve

curl "https://gps.appalbania.com/api/v1/vehicles?limit=2" \
  -H "Authorization: Bearer $GPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": 42,
      "name": "Iveco Daily",
      "plate": "AA 123 BB",
      "type": "van",
      "speed_limit_kmh": 90,
      "group": { "id": 3, "name": "Tirana" },
      "device": { "id": 17, "unique_id": "356307042441013", "model": "Teltonika FMB920", "status": "active" },
      "archived": false,
      "updated_at": "2026-10-06T09:41:12Z"
    }
  ],
  "next_cursor": "eyJ2ZWhpY2xlcy5pZCI6NDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "prev_cursor": null,
  "has_more": true,
  "limit": 2
}

Adresat

URL bazë https://gps.appalbania.com/api/v1. Kohët në ISO-8601 UTC. Periudhat e historikut: deri në 7 ditë për pozicionet, 31 ditë për raportet.

Metoda	Adresa	Leja	Përshkrimi
`GET`	`/me`	çdo token	Tokeni, pronari dhe organizata
`GET`	`/usage`	çdo token	Kufiri i kërkesave, kërkesat, automjetet dhe webhooks
`GET`	`/vehicles`	`vehicles:read`	Lista e automjeteve (?q, ?group_id, ?archived, ?cursor, ?limit)
`GET`	`/vehicles/{id}`	`vehicles:read`	Një automjet
`PATCH`	`/vehicles/{id}`	`vehicles:write`	Ndryshon name, plate, group_id, speed_limit_kmh
`GET`	`/states`	`positions:read`	Gjendja live e të gjitha automjeteve
`GET`	`/vehicles/{id}/state`	`positions:read`	Gjendja live: lat, lng, speed_kmh, course, ignition, status
`GET`	`/vehicles/{id}/positions`	`history:read`	Pozicionet mes ?from dhe ?to
`GET`	`/vehicles/{id}/route.gpx`	`history:read`	E njëjta rrugë si skedar GPX
`GET`	`/vehicles/{id}/trips`	`reports:read`	Udhëtimet mes ?from dhe ?to
`GET`	`/vehicles/{id}/stops`	`reports:read`	Ndalesat mes ?from dhe ?to
`GET`	`/vehicles/{id}/summary`	`reports:read`	Distanca, shpejtësitë dhe orët e motorit për një periudhë
`GET`	`/webhooks`	`webhooks:manage`	Lista e webhooks
`POST`	`/webhooks`	`webhooks:manage`	Krijon një webhook (sekreti kthehet vetëm një herë)
`DELETE`	`/webhooks/{id}`	`webhooks:manage`	Fshin një webhook
`GET`	`/webhooks/{id}/deliveries`	`webhooks:manage`	Regjistri i dërgesave, më të rejat në krye
`GET`	`/devices/catalog`	asnjë	Modelet e mbështetura dhe aftësitë e tyre (pa token)

Gjendja live

Një status për çdo automjet

status është moving mbi 5 km/h, parked me motor të fikur, idle në rastet e tjera, dhe offline kur pozicioni i fundit është më i vjetër se 10 minuta. Shihni vetëm të dhëna nga momenti kur pajisja iu caktua organizatës suaj.

Shembull: GET /vehicles/42/state

{
  "data": {
    "vehicle_id": 42,
    "status": "moving",
    "lat": 41.3275,
    "lng": 19.8187,
    "speed_kmh": 54.2,
    "course": 128,
    "altitude": 112.0,
    "ignition": true,
    "fix_time": "2026-10-06T09:41:12Z",
    "device_time": "2026-10-06T09:41:12Z"
  }
}

Gabimet, faqet dhe kufijtë

Përgjigje të parashikueshme

Gabimet vijnë si application/problem+json. ID-të e organizatave të tjera përgjigjen 404, kurrë 403.

401Token që mungon, i gabuar, i skaduar ose i anuluar
403Tokeni nuk ka lejen (shih "ability"), ose IP-ja nuk lejohet
404Nuk u gjet, ose nuk është juaji
422Fusha të pavlefshme (shih "errors"), ose periudhë shumë e gjatë
423Organizata është vetëm për lexim (pezulluar): punon vetëm GET
429U arrit kufiri: prisni sa sekonda thotë Retry-After
503Të dhënat e gjurmimit përkohësisht të padisponueshme: riprovoni pas pak

Faqosja, kufijtë, riprovimet

Listat përgjigjen {"data": [...], "next_cursor": "…", "has_more": true}. Dërgoni next_cursor si ?cursor derisa të jetë null.
X-RateLimit-Limit dhe X-RateLimit-Remaining në çdo përgjigje; kufiri është për organizatë, i përbashkët për të gjithë tokenat e saj.
Dërgoni header Idempotency-Key te POST: i njëjti çelës dhe e njëjta përmbajtje brenda 24 orësh kthen përgjigjen e parë (Idempotent-Replayed: true).

Shembull: mungon leja

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://gps.appalbania.com/en/developers#error-forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not have the history:read ability.",
  "instance": "/api/v1/vehicles/42/positions",
  "ability": "history:read"
}

curl -X POST "https://gps.appalbania.com/api/v1/webhooks" \
  -H "Authorization: Bearer $GPS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-erp-setup" \
  -d '{"url":"https://erp.example.com/gps","events":["alert.created","trip.ended"]}'

Webhooks

Ngjarjet vijnë te ju

Në vend që të pyesni vazhdimisht, regjistroni një URL HTTPS. Dërgojmë me POST {id, type, created_at, tenant_id, data} dhe presim përgjigje 2xx brenda 10 sekondave.

Header X-GPS-Signature: t=<unix>,v1=<HMAC-SHA256 hex i t + "." + body>, me sekretin tuaj
Refuzoni vula kohore më të vjetra se 5 minuta; përdorni id-në e ngjarjes për të shmangur dublikatat
Dërgesat e dështuara riprovohen me pritje në rritje deri në 24 orë
Pas 20 dështimesh radhazi webhook-u çaktivizohet dhe pronari njoftohet me email
Adresat private, lokale dhe link-local refuzohen

Ngjarjet

alert.createdAlarm i ri
ignition.onU ndez motori
ignition.offU fik motori
trip.startedFilloi udhëtimi
trip.endedMbaroi udhëtimi
geofence.enterHyri në zonë
geofence.exitDoli nga zona
vehicle.status_changedNdryshim statusi
device.onlinePajisja në linjë
device.offlinePajisja jashtë linje
command.resultRezultati i komandës
position.updatedPozicion i ri (me zgjedhje, maksimumi çdo 30 s për automjet)

Verifikimi i nënshkrimit: PHP

// Header: X-GPS-Signature: t=1791279672,v1=5f2b…
[$t, $v1] = sscanf($_SERVER['HTTP_X_GPS_SIGNATURE'] ?? '', 't=%d,v1=%s');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('GPS_WEBHOOK_SECRET'));

if (! $v1 || ! hash_equals($expected, $v1) || abs(time() - $t) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true); // $event['type'], $event['data']
http_response_code(204);

Verifikimi i nënshkrimit: Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/gps/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries((req.get('X-GPS-Signature') || '')
    .split(',').map((pair) => pair.split('=')));
  const t = Number(parts.t);
  const expected = crypto.createHmac('sha256', process.env.GPS_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  const valid = typeof parts.v1 === 'string' && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
    && Math.abs(Date.now() / 1000 - t) <= 300;

  if (!valid) return res.sendStatus(401);
  const event = JSON.parse(req.body); // event.type, event.data
  res.sendStatus(204);
});

Verifikimi i nënshkrimit: cURL + OpenSSL

# body.json = the raw request body, t and v1 from X-GPS-Signature
t=1791279672
expected=$(printf '%s.%s' "$t" "$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$GPS_WEBHOOK_SECRET" | sed 's/^.* //')
[ "$expected" = "$v1" ] && echo valid || echo invalid

# Replay a captured delivery against your endpoint
curl -X POST https://erp.example.com/gps \
  -H "Content-Type: application/json" \
  -H "X-GPS-Signature: t=$t,v1=$expected" \
  --data-binary @body.json

Recetë për sistemet e qirasë

Si ta lidhni sot platformën me programin tuaj të rent-a-car.

1
Lidhni makinat
GET /v1/vehicles?q=<targa ose VIN> një herë dhe ruani id-në e automjetit në sistemin tuaj.
2
Ndiqni qiranë
Abonohuni te ignition.on, trip.ended dhe alert.created, ose pyesni GET /v1/states për pozicionin live.
3
Mbyllni me shifrat
Në kthim, GET /v1/vehicles/{id}/summary?from=<marrja>&to=<kthimi> jep distancën dhe kilometrat.

Ju duhet një adresë tjetër?

Na tregoni çfarë sistemi përdorni dhe çfarë të dhënash ju duhen.

WhatsApp +355 67 496 3486 Na shkruani

Lidhni flotën me sistemin tuaj.

Bazat

REST dhe JSON

Token me leje

Webhooks

Gabime të qarta

Faqosje me kursor

Kufij të qartë