Yaqin Carrier API for shipping companies

Connect your shipping or delivery company to Yaqin once: you receive the shipments of every merchant who switches you on, and their statuses go back to them automatically.

Who is it for?

Shipping and delivery companies (domestic, international, same-day, cash on delivery) that want to receive shipments from merchants using Yaqin in Saudi Arabia, Egypt and the region, without connecting each merchant one by one.

How it works

  1. The merchant switches your company on in Yaqin (Shipping → Settings → Carriers) and adds its account number with you.
  2. When shipping an order the merchant presses "Send to …": the shipment appears in your list as "new", with sender, recipient (with map pin), parcels and the cash to collect.
  3. You accept it with your tracking number and label link (or reject it with a reason).
  4. You send every status change: picked up, in transit, out for delivery, failed attempt, delivered with proof of delivery.
  5. When you pay the collected cash to merchants you report the payout, and the merchant sees it on the shipments.

Getting connected

  1. Request an account: from the Contact page (topic: Partnership) send your company name, countries, services and contact person.
  2. Sandbox credentials: we send you a client_id and client_secret for the sandbox; you see only shipments from test companies.
  3. Try it in Postman: download the collection and the environment, paste the credentials, then run the requests in order: sign in, new shipments, accept, statuses, cash on delivery. The collection signs in by itself.
  4. Build your connection: use the full reference (OpenAPI 3); you can receive webhooks instead of polling.
  5. Go live: after we review the connection we move your account to live and send live credentials; merchants in your countries then see your name.

Quick example

1) Get an access token (valid one hour):

curl -X POST https://app.yaqinerp.com/api/shipping/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"yq_test_…","client_secret":"yqs_…"}'

2) New shipments:

curl "https://app.yaqinerp.com/api/shipping/v1/shipments?state=new" \
  -H "Authorization: Bearer $TOKEN"

3) Accept a shipment:

curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/accept \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number":"FX100234","label_url":"https://…/FX100234.pdf"}'

4) Send a status:

curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/events \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status":"DELIVERED","proof_of_delivery":{"receiver_name":"Mohammed"}}'

Statuses

CodeMeaning
PICKUP_SCHEDULEDPickup planned
PICKUP_FAILEDPickup failed
PICKED_UPCollected from the merchant
AT_HUBAt a hub
IN_TRANSITIn transit
OUT_FOR_DELIVERYOut for delivery
DELIVERY_ATTEMPT_FAILEDDelivery attempt failed (give the reason)
ON_HOLDOn hold
DELIVEREDDelivered (with proof of delivery)
RETURN_IN_TRANSITComing back to the merchant
RETURNEDReturned to the merchant
LOSTLost
DAMAGEDDamaged

Rules

  • JSON everywhere; times in ISO 8601 with time zone.
  • Send Authorization: Bearer <access_token> on every call; get a new token when it expires.
  • Send a unique Idempotency-Key with every POST, so a retry never does the work twice.
  • 120 calls a minute per client; lists are paged with next_cursor.
  • Errors look like {"error": {"code", "message", "details"}} with 400, 401, 403, 404, 409, 422, 429.
  • Webhooks (optional): we POST shipment.created and shipment.cancelled, signed in X-Yaqin-Signature (HMAC-SHA256).

Links

Ready to connect?

Send us your request and we send sandbox credentials within one working day.

Request a test account