In-panel API documentation and public helper endpoints

Purpose#

Two pages inside the panels document the platform's public APIs, and a handful of small endpoints answer without any API key. This article shows where the documentation pages are and what each one contains, states the limits and error codes the API applies, and describes the small public helper endpoints with their inputs and responses.

Who can open the documentation pages#

• Merchant page: platform (independent) merchants, from Integration in the merchant menu, then API documentation, or from the API documentation button on Webhook and API. A merchant that belongs to a delivery company has no Integration section; opening the address directly redirects to the dashboard with a warning.
• Company page: the company admin, from Integrations and API (admins only), button API documentation, which opens Company API documentation.
• Opening a page needs no plan feature; the API itself does. Both pages are built when you open them: the Base URL follows the current domain, the webhook event list comes from the code, and the company page reads its limits from the company's plan.
• Each page has a Learn how this works button (Arabic: تعرّف على طريقة العمل) that opens the matching article of this documentation when the documentation module is on.

What each page contains#

Limits and error codes of the API#

These are the rules the API itself enforces. For the details of each endpoint use the Merchant API and Company API reference articles.

• Request limits. Every /api request first passes the general limit of 60 requests per minute per IP address and gets 429 beyond it. The routes also have higher ceilings (/api/v1: 120 per minute, of which 60 for creating a parcel; /api/company/v1: 300 per minute, of which 120 for creating a parcel), but they never raise the general limit of 60 per minute per IP address. Plan limits (per minute and per day) are counted per account and answer 429 with the code rate_limited and a Retry-After header. See the rate limits article.
• Plan requirement. When merchant plans are in force, every /api/v1 call needs a plan with the API feature, otherwise it fails with 403 and plan_feature; a subscription-based delivery company likewise needs a company plan that includes the API feature. A merchant that belongs to a delivery company gets 403 with api_not_allowed from /api/v1.
• Webhook events. When you create or change a webhook link through the API, events accepts * (all events) or the listed names: parcel.created, parcel.status_changed, parcel.out_for_delivery, parcel.delivered, parcel.returning, parcel.returned, parcel.cancelled, parcel.awaiting_funds, wallet.topup and wallet.withdrawal. Any other value, such as a group like parcel.*, gives 422. GET /api/v1/webhooks/events returns the same list.
• Webhook error codes. Creating a webhook link needs the webhooks feature of the plan (403, plan_feature); limit_reached (422) means you already have the maximum number of webhook links, which is 10 or the lower limit of your plan; delivery_failed (422) means the test message was not delivered.
• Currencies. Amounts can be sent in any of the platform's 12 currency codes: USD, SYP, SAR, AED, QAR, KWD, JOD, IQD, EGP, LBP, TRY and EUR (the Company API field is currency). A currency other than USD works only when an exchange rate has been set for it on the platform; otherwise the call fails with a validation error. If the company does not accept the currency, the amounts are converted to one it accepts.
• Governorate. In the Company API, recipient.governorate matters when the company prices by governorate (the platform can also detect the governorate from the address or the coordinates); with the other pricing modes the charge does not depend on it.
• Time zone. Timestamps are in ISO 8601 and the application time zone is UTC, so values end in +00:00.

Public helper endpoints#

These requests need no API key, except the two mobile-app lists marked apiKey, which need the mobile API's apiKey header. Requests under /api pass the general limit of 60 requests per minute per IP address and answer JSON. To show a shipment's progress to a customer, use the public tracking page (see the article on tracking a shipment).

Governorates and prices#

• GET /api/parcel/governorates: no input. data is a list of the active governorates; each item has id, name, shipping_cost and hubs, the governorate's active hubs (id, name, address, hub_lat, hub_long).
• POST /api/parcel/calculateByCity: body name, the exact governorate name as listed above. Success returns data including city and shipping_cost. An unknown or inactive name returns 404 with success false and the message "Sorry, shipping is not available for city: ..." (Arabic by default).
• The Merchant API has its own list, GET /api/v1/governorates (key required): id, name and name_ar.

curl -X POST https://YOUR_DOMAIN/api/parcel/calculateByCity \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"name": "Damascus"}'

shipping_cost is the value stored on the governorate record. The fare charged for a parcel is computed from the delivery company's own pricing, so use the quote endpoints for real prices. To get the hubs of a governorate use GET /api/parcel/governorates, not this response.

Delivery charge table#

• GET /api/delivery-charges: no input. Returns the delivery charge rows of the default company (weight, same_day, next_day, sub_city, outside_city, position), each with its category.

Lists for the mobile apps (apiKey)#

• GET /api/v10/hub: the default company's hubs (id, name, phone, address), 10 per page, newest first (page selects the page).
• GET /api/v10/all-currencies: the active currencies in display order.

Without the header these return 400 with Invalid Api Key. The header's value is fixed in the server configuration; ask the platform operator.

Newsletter and contact#

• POST /api/subscribe: body email. Stores the address for the default company and answers 200 with "Successfully subscribed."; a repeated address answers 200 with success false, "Already subscribed." and exists in data.
• POST /api/contact-us: body name, email, subject, message. Sends an email to the platform's contact address. It needs working mail settings; it answers 200 when the message is sent and 500 when sending fails.

Areas for the individual shipping form#

• GET /ship/areas (web route ship.areas, 60 per minute): company_id and city are required, country is optional (two letters, default SY). Returns {"areas": [...]}; an empty list means free-text entry. The areas come from the delivery company's carrier when it provides them.

Common mistakes#

• Treating shipping_cost as the fare. It is a stored default; the charge depends on the company's pricing mode.
• Sending an Arabic governorate name to calculateByCity. The name must equal the stored one; the default names are English, such as Damascus and Rif Dimashq.
• Calling the mobile lists without apiKey. The answer is 400 with Invalid Api Key.
• Sending more than 60 requests a minute from one IP address. The general limit answers 429, whatever the route limits are.

Limits and permissions#

• Only platform merchants (merchant page) and company admins (company page) can open the documentation pages; merchants of a delivery company are redirected.
• The public helpers need no login. They share the general limit of 60 requests per minute per IP address, so cache lists that rarely change.