Programeri

Registrujte isporuku u paketomat jednim REST pozivom

iBOX API omogućava vašoj prodavnici da registruje isporuke u paketomate širom Kosova i pruži kupcu link za praćenje. Registracija je jedan zahtev; sve posle toga dešava se kod nas.

OpenAPI specifikacija

Autentifikacija

Pošaljite svoj ključ kao bearer token. Ključevi se izdaju po organizaciji i ograničavaju svaki zahtev na nju — organizacija se nikada ne uzima iz tela zahteva, pa ključ može doći samo do vaših pošiljki. Ključ se prikazuje samo jednom pri kreiranju i čuva se isključivo kao heš, pa se izgubljeni ključ zamenjuje, a ne vraća.

curl https://api.ibox.ks/api/v1/shipments \
  -H "Authorization: Bearer ibx_live_..."

Registrovanje pošiljke

Dajte nam paketomat, veličinu paketa i za koga je. Dobijate broj za praćenje koji pokazujete kupcu i barkod koji štampamo na nalepnici.

curl -X POST https://api.ibox.ks/api/v1/shipments \
  -H "Authorization: Bearer ibx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination_station_id": "18f10fc3-0e69-44ef-86cd-02148de6ad85",
    "parcel_size": "M",
    "recipient_name": "Arta Krasniqi",
    "recipient_phone": "+383 44 123 456",
    "recipient_language": "sq",
    "merchant_order_reference": "ORD-5501"
  }'

{
  "id": "833613f8-bbb1-4181-ad23-458334291f00",
  "tracking_number": "IBX9806988931",
  "status": "booked",
  "destination": { "cabinet_sn": "IBOX-202606-A1B2C3-01", "slot_no": null },
  ...
}

Krajnje tačke

POST/api/v1/shipments

Kreirajte i registrujte pošiljku jednim pozivom.

GET/api/v1/shipments

Vaše pošiljke, najnovije prve.

GET/api/v1/shipments/{id}

Jedna pošiljka. Pošiljka druge organizacije prijavljuje se kao nepostojeća, ne kao zabranjena.

GET/api/v1/shipments/{id}/label

Termalna nalepnica 100×150mm kao PDF, sa barkodom koji paketomat skenira.

GET/api/v1/track/{trackingNumber}

Status i istorija jedne vaše pošiljke, za vašu stranicu porudžbine. Ograničeno na vašu organizaciju.

O kodovima za preuzimanje

API nikada ne vraća osmocifreni kod za preuzimanje. Vaš kupac ga unosi na ekranu paketomata da otvori svoju pregradu, pa mu ga iBOX šalje direktno SMS-om na njegovom jeziku — albanski, srpski, turski ili engleski — i nigde drugde se ne pojavljuje.

Greške

Greške prate RFC 9457. Oslonite se na `code`, koji je stabilan, a ne na čitljiv naslov. Neuspesi validacije navode tačna polja. Svaka greška nosi correlation id koji vredi navesti ako nas pitate o zahtevu.

{
  "title": "Request body failed validation",
  "status": 422,
  "code": "validation_failed",
  "correlation_id": "f128a508-3e9f-4ff8-a260-ec504850adff",
  "errors": [
    { "field": "recipient_phone", "code": "too_small", "message": "..." }
  ]
}

Autentifikacija

curl https://api.ibox.ks/api/v1/shipments \ -H "Authorization: Bearer ibx_live_..."

Registrovanje pošiljke

Dajte nam paketomat, veličinu paketa i za koga je. Dobijate broj za praćenje koji pokazujete kupcu i barkod koji štampamo na nalepnici.

curl -X POST https://api.ibox.ks/api/v1/shipments \ -H "Authorization: Bearer ibx_live_..." \ -H "Content-Type: application/json" \ -d '{ "destination_station_id": "18f10fc3-0e69-44ef-86cd-02148de6ad85", "parcel_size": "M", "recipient_name": "Arta Krasniqi", "recipient_phone": "+383 44 123 456", "recipient_language": "sq", "merchant_order_reference": "ORD-5501" }'

{ "id": "833613f8-bbb1-4181-ad23-458334291f00", "tracking_number": "IBX9806988931", "status": "booked", "destination": { "cabinet_sn": "IBOX-202606-A1B2C3-01", "slot_no": null }, ... }

Krajnje tačke

POST/api/v1/shipments

Kreirajte i registrujte pošiljku jednim pozivom.

GET/api/v1/shipments

Vaše pošiljke, najnovije prve.

GET/api/v1/shipments/{id}

Jedna pošiljka. Pošiljka druge organizacije prijavljuje se kao nepostojeća, ne kao zabranjena.

GET/api/v1/shipments/{id}/label

Termalna nalepnica 100×150mm kao PDF, sa barkodom koji paketomat skenira.

GET/api/v1/track/{trackingNumber}

Status i istorija jedne vaše pošiljke, za vašu stranicu porudžbine. Ograničeno na vašu organizaciju.

Greške

{ "title": "Request body failed validation", "status": 422, "code": "validation_failed", "correlation_id": "f128a508-3e9f-4ff8-a260-ec504850adff", "errors": [ { "field": "recipient_phone", "code": "too_small", "message": "..." } ] }