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
- The merchant switches your company on in Yaqin (Shipping → Settings → Carriers) and adds its account number with you.
- 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.
- You accept it with your tracking number and label link (or reject it with a reason).
- You send every status change: picked up, in transit, out for delivery, failed attempt, delivered with proof of delivery.
- When you pay the collected cash to merchants you report the payout, and the merchant sees it on the shipments.
Getting connected
- Request an account: from the Contact page (topic: Partnership) send your company name, countries, services and contact person.
- Sandbox credentials: we send you a
client_idandclient_secretfor the sandbox; you see only shipments from test companies. - 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.
- Build your connection: use the full reference (OpenAPI 3); you can receive webhooks instead of polling.
- 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
| Code | Meaning |
|---|---|
| PICKUP_SCHEDULED | Pickup planned |
| PICKUP_FAILED | Pickup failed |
| PICKED_UP | Collected from the merchant |
| AT_HUB | At a hub |
| IN_TRANSIT | In transit |
| OUT_FOR_DELIVERY | Out for delivery |
| DELIVERY_ATTEMPT_FAILED | Delivery attempt failed (give the reason) |
| ON_HOLD | On hold |
| DELIVERED | Delivered (with proof of delivery) |
| RETURN_IN_TRANSIT | Coming back to the merchant |
| RETURNED | Returned to the merchant |
| LOST | Lost |
| DAMAGED | Damaged |
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-Keywith 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.createdandshipment.cancelled, signed inX-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