If a carrier charges more than you declared, we refund the difference to your wallet.0850 840 15 46
Developers

API reference

Connect your own software to Shipzone: get quotes, create shipments, manage your address book.

Base URL

https://api.shipzone.app

Authentication

You create a key in the panel and its value is shown ONLY ONCE — we do not store it, only its hash. Never put your panel password in a script; avoiding exactly that is why keys exist.

Panel → API keys

Both headers are accepted:

X-API-Key: sz_live_a1b2c3d4_...
Authorization: Bearer sz_live_a1b2c3d4_...

Endpoints

GET/v1/api/account

Which account the key belongs to and what it may do. This is the first endpoint to call: it confirms your key works without creating a real shipment.

GET/v1/api/carriers

Carriers that can produce a price for you. Your own contract appears in this list too.

POST/v1/api/quotes

Every carrier's price for the same shipment, cheapest first. Quoting needs no approval and costs nothing.

Body
{
  "origin_city": "İstanbul",
  "dest_city": "Ankara",
  "packages": [
    { "weight_kg": "1.5", "length_cm": "30",
      "width_cm": "20", "height_cm": "15" }
  ]
}
GET/v1/api/addresses

Your address book. Filter with `?kind=sender` or `?kind=recipient`.

POST/v1/api/addresses

Adds an entry to the address book. Shipments reference addresses by id, so they are written here first.

Body
{
  "kind": "recipient",
  "title": "Müşteri deposu",
  "contact_name": "Ayşe Yılmaz",
  "phone": "05320000000",
  "city": "Ankara",
  "district": "Çankaya",
  "address_line": "Örnek Mah. 1. Cad. No 5"
}
POST/v1/api/shipments

Saves the shipment and freezes its price. REQUIRES APPROVAL: this endpoint returns 403 until your application is approved. The fee is taken from your wallet at this moment.

Body
{
  "carrier_slug": "aras_kargo",
  "sender_address_id": "<adres kimliği>",
  "recipient_address_id": "<adres kimliği>",
  "packages": [
    { "weight_kg": "1.5", "length_cm": "30",
      "width_cm": "20", "height_cm": "15" }
  ]
}

Errors

Errors come back as `{ "detail": { "code", "message" } }` alongside the HTTP status. `code` is STABLE and is what you branch on; `message` is for humans and may change.

401Invalid API keyWrong key, revoked key or closed account. All three return the SAME response, so which one it is does not leak.
403Application not approvedCreating shipments requires approval. Quote endpoints are unaffected.
402Insufficient balanceThe fee is taken when the shipment is saved; if the balance is short, the shipment is NOT created.
422Invalid bodyA missing or malformed field. The message names it.

Want event notifications?

We call your URL whenever a shipment status changes, so you do not have to keep asking.

Webhook guide