Gaarsii API v1Gaarsii API v1

Book a delivery from your own checkout Isku xirka rarka iyo iibsiga

Quote a delivery, book it at the quoted price, and follow it to the door — from your shop, your ERP, or whatever you already run. A REST API over HTTPS, JSON in and out, with signed webhooks so you never poll for a delivery that already arrived.

Qiimee gaarsiin, ku dalbo qiimaha la sheegay, kuna raac ilaa albaabka — ku dhex isticmaal nidaamka dukaankaaga. API ku shaqeeya HTTPS, JSON gal iyo bax, iyo webhooks amaan ah.

Getting a keyHelitaanka fure

You generate your own keys in the portal, as many as five at a time. What a person still checks is whether you are a merchant at all — ask once, and after that the keys are yours to make and revoke.

Furayaasha adigaa ka samaysanaya portal-ka, ilaa shan mar kasta. Waxa qof weli hubiyo waa inaad tahay ganacsade — hal mar codso, kadibna furayaashu waa kuwaaga oo aad samayn iyo burburin karto.

1. Ask for merchant access, onceCodso, adigoo isticmaalaya foomka hoose

   Tell us the business, where deliveries will start from, and roughly how many a day. Sandbox requests are turned around fastest.

   Noo sheeg ganacsiga, meesha gaarsiintu ka bilaabmayso, iyo tiro qiyaastii ah maalintii. Codsiyada sandbox-ka ayaa si dhaqso ah loo farsameeyaa.

2. Generate keys yourselfWaxaad heshaa hal fure, hal mar

   In the portal, name a key and press generate. It looks like gsk_<client-id>.<secret> and is shown once — only an Argon2id hash is kept, so nobody can show it to you again. Lost one? Revoke it and generate another.

   Wuxuu u eg yahay gsk_<client-id>.<secret>. Client id-gu waa qaybta dadweynaha oo ku aqoonsanaysa; qaybta sirta ah waxaa loo kaydiyaa oo keliya sida Argon2id hash, sidaas darteed mar labaad kuma tusi karno. Kaydso marka aad hesho.

3. Build against the sandboxKu dhis sandbox-ka

   Same endpoints, same payloads, same webhooks. When you are ready we issue a live key; nothing in your integration changes but the key and the base URL.

   Isla meelaha, isla xogta, isla webhooks. Marka aad diyaar tahay waxaan ku siinaynaa fure toos ah; waxba isku-xidhkaaga kama beddelmayaan furaha iyo URL-ka mooyaane.

AuthenticationXaqiijinta

Send the key in a header on every request. There is no session, no OAuth dance and no token to refresh.

Ku dir furaha madax kasta oo codsi ah. Ma jiro fadhi, ma jiro OAuth, ma jiro token dib loo cusboonaysiiyo.

X-Gaarsii-API-Key: gsk_01J5YQWDSX5MA3N31GYZ32NJQM.<secret>
Content-Type: application/json

Keys are bound to one tenant and to a set of scopes. A key that may quote and book cannot read another merchant's orders, and a request for something outside its scope is refused rather than filtered.

Furayaashu waxay ku xidhan yihiin hal ganacsi iyo koox ogolaansho. Wixii ka baxsan ogolaanshaha waa la diidayaa.

IdempotencySifo aan isbeddelin

Every call that creates or changes something requires an Idempotency-Key. Networks fail after the server has already acted, and a retry must not book a second delivery or take a second payment.

Codsi kasta oo wax abuura ama wax beddela waa inuu hal mar oo kaliya sameeyo nidaamka, xitaa haddii dib loo diro.

Use something unique per logical operation — a ULID or UUID is ideal. 16 to 128 characters, letters, digits and . _ : -.

Hawl kasta oo gaar ah isticmaal aqoonsi (ID) u gaar ah. ULID ama UUID ayaa ku habboon. ID-gu waa inuu ka koobnaadaa 16 ilaa 128 xaraf, waxaana la isticmaali karaa xarfaha, tirooyinka iyo calaamadaha.

QuickstartBilow degdeg ah

Three calls: ask the price, accept it, then follow the parcel. The quote holds the price — booking it is what commits you.

Waxaa jira saddex codsi: marka hore qiimaha weydii, kadib qiimaha aqbal, ugu dambayntiina xirmada la soco. Xigashadu waxay haysaa qiimaha lagu siiyay; dalabku waa tallaabada xaqiijinaysa.

1. Quote a delivery1. Qiimee gaarsiin

# Prices the job. Nothing is booked and nobody is charged.
curl -X POST https://api.gaarsii.net/api/v1/merchant/quotes \
  -H "X-Gaarsii-API-Key: $GAARSII_KEY" \
  -H "Idempotency-Key: 01J5YQWDSX5MA3N31GYZ32NJQM" \
  -H "Content-Type: application/json" \
  -d '{
    "route": {
      "pickup":  { "label": "Bakaara, Muqdisho", "latitude": 2.0469, "longitude": 45.3182 },
      "dropoff": { "label": "Hamarweyne, Muqdisho", "latitude": 2.0369, "longitude": 45.3382 }
    },
    "item": {
      "category": "PARCEL",
      "description": "Phone case",
      "declaredWeightKg": 0.4
    },
    "currency": "USD"
  }'

2. Book it at that price2. Ku dalbo qiimahaas

curl -X POST https://api.gaarsii.net/api/v1/merchant/orders \
  -H "X-Gaarsii-API-Key: $GAARSII_KEY" \
  -H "Idempotency-Key: 01J5YQX8N2K7RD4T0PBM9WQ1ZE" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "qte_01J5YQWE…" }'

The order starts at AWAITING_PAYMENT. A courier is dispatched only once payment has cleared — we do not put someone on the road against money that has not arrived.

Dalabku wuxuu ku bilaabmaa xaalad lacag-bixin la sugayo. Qaadaha waxaa la diraa oo keliya marka lacagtu si rasmi ah u soo gasho. Qof looma dirayo iyadoo lacagtu aanay weli iman.

3. Follow it3. Raac

curl https://api.gaarsii.net/api/v1/merchant/orders/{orderId}/tracking \
  -H "X-Gaarsii-API-Key: $GAARSII_KEY"

Polling works, but webhooks are better — see below. Poll only as a safety net.

Polling wuu shaqayn karaa, laakiin webhooks ayaa ka fiican. Polling-ka u isticmaal oo keliya sidii hab kayd ah.

EndpointsDhammaadka

All paths are relative to https://api.gaarsii.net/api/v1. Everything here is scoped to your own merchant account.

Dhammaan path-yadu waxay ka bilaabmaan https://api.gaarsii.net/api/v1. Dhammaan xogta iyo hawlaha halkan ku jira waxay ku koobtan yihiin akoonkaaga ganacsi.

Order lifecycleWareega dalabka

An order moves forward through these states. It never skips and never goes back — if you see a state, everything before it has happened.

Dalabku wuxuu u gudbaa xaaladaha si isku xigta. Ma boodo, dibna ugama noqdo. Haddii aad aragto xaalad gaar ah, waxay ka dhigan tahay in dhammaan kuwii ka horreeyay ay hore u dhaceen.

AWAITING_PAYMENT   → booked, money not yet cleared
READY_TO_DISPATCH  → paid; safe to look for a courier
DISPATCHING        → being offered to couriers
ASSIGNED           → a courier accepted
EN_ROUTE_TO_PICKUP → on the way to you
PICKED_UP          → your reference shown, parcel handed over
AT_DROPOFF         → at the recipient's door
DELIVERED          → recipient's code accepted. Final.

WebhooksOgeysiis toos ah

Register a URL and we post every state change to it, signed. Reply 2xx quickly and do your work afterwards; we retry with backoff, and anything you miss can be redelivered.

URL-kaaga diiwaangeli, kadib isbeddel kasta oo dalabka ku yimaada waxaan kuugu soo dirnaa, fariinta oo la saxiixay. Si degdeg ah ugu jawaab 2xx, kadibna shaqadaada kale samee. Haddii jawaabtu fashilanto, waan dib u soo dirnaa annagoo kordhinayna waqtiga u dhexeeya. Wixii kaa maqnaada dib ayaa laguugu soo diri karaa.

Errors and limitsKhaladaadka iyo xaddidaadaha

Errors are JSON with a stable machine-readable code. Branch on the code, never on the message — messages get clearer over time, codes do not change.

Khaladaadku waxay ku yimaadaan qaab JSON ah, waxaana ku jira code joogto ah oo kombiyuutarku fahmi karo. Go'aanka ku salee code-ka, hana ku salayn fariinta, maxaa yeelay fariimaha khaladku way is beddeli karaan. Code-yadu isma beddelaan.

{ "error": { "code": "IDEMPOTENCY_KEY_REUSED",
            "message": "That key was used with a different request body." } }

Retry 429 and 503 with exponential backoff, reusing the same Idempotency-Key so a retry cannot double-book. Never retry 400 or 403 unchanged.

Dib u isku day 429 iyo 503, adigoo isticmaalaya isla Idempotency-Key si dib-u-isku-daygu labanlaab u dalbin. Waligaa ha ku celin 400 ama 403 iyagoo aan beddelmin.