Zhvilluesit

Regjistroni një dërgesë në kabinet me një thirrje REST

API-ja e iBOX-it i lejon dyqanit tuaj të regjistrojë dërgesa në kabinete anembanë Kosovës dhe t'i japë klientit një lidhje gjurmimi. Regjistrimi është një kërkesë e vetme; gjithçka pas saj ndodh nga ana jonë.

Specifikimi OpenAPI

Autentikimi

Dërgojeni çelësin tuaj si token bearer. Çelësat lëshohen për secilën organizatë dhe e kufizojnë çdo kërkesë brenda saj — organizata nuk merret kurrë nga trupi i kërkesës, prandaj një çelës arrin vetëm te dërgesat tuaja. Çelësi shfaqet vetëm një herë kur krijohet dhe ruhet vetëm si hash, prandaj një çelës i humbur zëvendësohet, nuk rikuperohet.

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

Regjistrimi i një dërgese

Na jepni kabinetin, madhësinë e pakos dhe për kë është. Merrni një numër gjurmimi për klientin tuaj dhe një barkod që e printojmë në etiketë.

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 },
  ...
}

Pikat e API-t

POST/api/v1/shipments

Krijoni dhe regjistroni një dërgesë me një thirrje.

GET/api/v1/shipments

Dërgesat tuaja, më të rejat në fillim.

GET/api/v1/shipments/{id}

Një dërgesë. Dërgesa e një organizate tjetër raportohet si inekzistente, jo e ndaluar.

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

Etiketa termike 100×150mm si PDF, me barkodin që lexon kabineti.

GET/api/v1/track/{trackingNumber}

Statusi dhe historiku i një pakoje tuajën, për faqen tuaj të porosive. I kufizuar në organizatën tuaj.

Rreth kodeve të tërheqjes

API-ja nuk e kthen kurrë kodin tetëshifror të tërheqjes. Klienti juaj e shkruan atë në ekranin e kabinetit për të hapur ndarjen e vet, prandaj iBOX ia dërgon drejtpërdrejt me SMS në gjuhën e tij — shqip, serbisht, turqisht ose anglisht — dhe nuk shfaqet askund tjetër.

Gabimet

Gabimet ndjekin RFC 9457. Bazohuni te `code`, i cili është i qëndrueshëm, jo te titulli i lexueshëm. Dështimet e validimit i listojnë fushat e sakta. Çdo gabim mbart një correlation id që ia vlen ta citoni nëse na pyetni për një kërkesë.

{
  "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": "..." }
  ]
}

Autentikimi

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

Regjistrimi i një dërgese

Na jepni kabinetin, madhësinë e pakos dhe për kë është. Merrni një numër gjurmimi për klientin tuaj dhe një barkod që e printojmë në etiketë.

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 }, ... }

Pikat e API-t

POST/api/v1/shipments

Krijoni dhe regjistroni një dërgesë me një thirrje.

GET/api/v1/shipments

Dërgesat tuaja, më të rejat në fillim.

GET/api/v1/shipments/{id}

Një dërgesë. Dërgesa e një organizate tjetër raportohet si inekzistente, jo e ndaluar.

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

Etiketa termike 100×150mm si PDF, me barkodin që lexon kabineti.

GET/api/v1/track/{trackingNumber}

Statusi dhe historiku i një pakoje tuajën, për faqen tuaj të porosive. I kufizuar në organizatën tuaj.

Gabimet

{ "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": "..." } ] }