Početna / Developeri

Business API · v1

Time Locker unutar vašeg proizvoda.

Time Locker može biti gotova aplikacija ili infrastruktura unutar vaše aplikacije. Povežite korisnike, pakete, uređaje, događaje i logističke procese sa svojim sustavom bez korištenja našeg sučelja.

Zatražite API pristup Pogledajte webhookove

Kako izgleda

REST, JSON, predvidljivo.

Javni API odvojen je od internog API-ja: ima vlastiti prefiks /api/v1, autentikaciju ključem i dokumentaciju. Verzioniranje sprječava da promjene platforme prekinu vašu integraciju.

Autentikacija zaglavljem X-API-KEY
Registracija krajnjih korisnika partnera
Pretraga uređaja po blizini i dohvat vrata
Paketi, povrati i otključavanje
Upravljanje webhook endpointima uz testnu isporuku

# Pronađi paketomate u blizini
GET /api/v1/parcel-machines/nearby?lat=45.55&lng=18.69
X-API-KEY: tl_test_••••••••

200 OK
[
  {
    "publicId": "TL-OS-0142",
    "name": "IT park Osijek",
    "distanceMeters": 180,
    "freeDoors": { "S": 3, "M": 2, "L": 1 }
  }
]

# Kreiraj paket za preuzimanje
POST /api/v1/packages
X-API-KEY: tl_live_••••••••

{
  "parcelMachinePublicId": "TL-OS-0142",
  "doorSize": "M",
  "recipient": { "phone": "+38591xxxxxxx" },
  "externalReference": "ORDER-10492"
}

# kad je paket odložen:
POST /api/v1/packages/{id}/mark-placed

# Zatraži potpisanu autorizaciju za otključavanje
POST /api/v1/locker-access/unlock
X-API-KEY: tl_live_••••••••

# Odgovor je kratkotrajan, potpisan teret koji vaša
# aplikacija prikazuje uređaju kao QR kod.
# Uređaj provjerava potpis lokalno — bez poziva poslužitelju.

Primjeri su ilustrativni; točne sheme zahtjeva i odgovora nalaze se u API dokumentaciji koju partner dobiva uz pristup.

Ključevi i okruženja

Test i produkcija, strogo odvojeni.

Prefiks ključa određuje okruženje, a zahtjev se usmjerava na bazu tog okruženja prije ikakvog pristupa podacima. Testni ključ ne vidi produkcijske podatke i obrnuto.

tl_live_…

Produkcija

Stvarni uređaji, stvarni korisnici i paketi.

tl_test_…

Test

Sigurno okruženje za razvoj i automatizirane testove.

Zaštita ključeva

Pohranjuje se samo sažetak SHA-256 (hash) ključa. Ključevi se prikazuju jedanput i mogu se opozvati.

Resursi

Što možete povezati.

Resurs	Ruta	Što omogućuje
Auth	/api/v1/auth	Registracija, prijava i osvježavanje tokena krajnjih korisnika partnera
Users	/api/v1/users	Kreiranje, dohvat i brisanje korisnika
Parcel Machines	/api/v1/parcel-machines	Modeli, registracija uređaja, popis, pretraga po blizini, vrata
Packages	/api/v1/packages	Paketi za preuzimanje, označavanje odlaganja, povrati
Locker Access	/api/v1/locker-access	Inicijalizacija, otključavanje i ponovno postavljanje pristupa uređaju
Notifications	/api/v1/notifications	Obavijesti prema korisnicima
Webhooks	/api/v1/webhooks	Registracija, popis i brisanje endpointa te testni ping

Webhookovi

Webhookovi šalju promjene statusa vašem sustavu.

Umjesto stalnog provjeravanja, Time Locker šalje događaj vašem sustavu čim se nešto promijeni. Svaka isporuka je potpisana, ima vlastiti ID i punu dijagnostiku.

PackageCreated

Stvoren paket za preuzimanje

PackagePlaced

Paket odložen u uređaj

PackageCollected

Primatelj je preuzeo paket

ReturnCreated

Otvoren povrat

ReturnDeposited

Povrat odložen

UserCreated · Ping

Novi korisnik · test endpointa

X-TimeLocker-Event:     PackagePlaced
X-TimeLocker-Delivery:  5b2e9c14-…
X-TimeLocker-Timestamp: 1790751600
X-TimeLocker-Signature: sha256=<hex>

// potpis = HMAC-SHA256(secret, "{timestamp}.{body}")

const mac = crypto.createHmac('sha256', secret)
  .update(`${ts}.${rawBody}`)
  .digest('hex');

const ok = crypto.timingSafeEqual(
  Buffer.from(`sha256=${mac}`),
  Buffer.from(header));

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var hash = hmac.ComputeHash(
    Encoding.UTF8.GetBytes($"{timestamp}.{body}"));
var expected = "sha256=" +
    Convert.ToHexString(hash).ToLowerInvariant();

bool ok = CryptographicOperations.FixedTimeEquals(
    Encoding.UTF8.GetBytes(expected),
    Encoding.UTF8.GetBytes(signatureHeader));

Ponovni pokušaji s eksponencijalnim odmakom

Pokušaj	Odgoda	Od početka
1	odmah	0 s
2	30 s	30 s
3	60 s	1,5 min
4	120 s	3,5 min
5	240 s	7,5 min

Timeout jednog pokušaja: 15 s. Zadane vrijednosti.

SDK i integracije

Od web-trgovine do vlastite mobilne aplikacije.

SDK za uređaj

Paket bez vanjskih ovisnosti za rad s ormarićem iz vaše mobilne aplikacije — prikaz autorizacije kao QR koda koji uređaj skenira.

Web-trgovina i ERP

Click & Collect narudžbe i povrati izravno iz vašeg sustava narudžbi.

Demonstracija za partnere

Referentna integracija koja prikazuje cijeli postupak od registracije do preuzimanja.

API pristup

Povežite svoj sustav s Time Lockerom.

Ključevi se izdaju partnerima nakon kratkog upoznavanja s vašim slučajem korištenja.

Zatražite API pristup