واجهة المطورينDeveloper API

اربط متجرك بمسار: اطلب الأسعار، أنشئ الشحنة، واطبع البوليصة من نظامك.Connect your store to Masar: ask for prices, create the shipment and print the waybill from your own system.

نسخة أولية: العنوان الأساسي الحقيقي يظهر في صفحة "ربط المتجر" داخل حسابك بعد التفعيل. الأسعار نهائية بالريال وقبل ضريبة القيمة المضافة.Preview: the real base address appears on the "Store connection" page inside your account once it is active. Prices are final, in SAR, before VAT.

المصادقةAuthentication

أنشئ مفتاح الربط من صفحة "ربط المتجر" في حسابك وأرسله في كل طلب بالترويسة x-api-key. الحساب يجب أن يكون مفعّلًا. لا تضع المفتاح في كود يراه الزوار.Create the key on the "Store connection" page in your account and send it in every request in the x-api-key header. The account must be active. Never put the key in code that visitors can read.

curl https://YOUR-MASAR-ADDRESS/v1/wallet -H "x-api-key: YOUR_KEY"

{ "balance": 962 }

الطلبات المتاحةEndpoints

الطريقةMethod	المسارPath	الوصفWhat it does
`GET`	`/v1/wallet`	رصيد المحفظة بالريال.Wallet balance in SAR.
`GET`	`/v1/cities`	قائمة المدن المقبولة.The cities we accept.
`POST`	`/v1/rates`	الأسعار وأوقات التوصيل لكل شركة، مرتبة من الأرخص.Prices and delivery times per courier, cheapest first.
`POST`	`/v1/shipments`	إنشاء شحنة وخصم سعرها من المحفظة. التكرار بنفس المرجع آمن ولا يخصم مرتين.Create a shipment and take its price from the wallet. Repeating the same reference is safe and never charges twice.
`GET`	`/v1/shipments`	آخر 100 شحنة.Your latest 100 shipments.
`GET`	`/v1/shipments/{id}`	شحنة واحدة بحالتها ورقم التتبع.One shipment with its status and tracking number.
`POST`	`/v1/shipments/{id}/cancel`	إلغاء قبل الاستلام واسترداد المبلغ كاملًا.Cancel before pickup and get the full amount back.
`POST`	`/v1/shipments/{id}/label-link`	رابط مؤقت (5 دقائق) لطباعة بوليصة الشركة.A temporary link (5 minutes) to print the courier waybill.
`GET`	`/v1/shipments/{id}/label`	ملف PDF للبوليصة كما أصدرتها الشركة.The waybill PDF exactly as the courier made it.

مثال: الأسعارExample: prices

POST /v1/rates
{
  "from_city": "Riyadh",
  "to_city": "Jeddah",
  "boxes": [ { "weight_kg": 1.5, "length_cm": 30, "width_cm": 20, "height_cm": 10 } ]
}

[ { "carrier": "aramex", "service": "Express", "eta_days": "2-4",
    "price": 19, "billable_weight_kg": 1.5, "pieces": 1 } ]

مثال: إنشاء شحنةExample: create a shipment

POST /v1/shipments
{
  "carrier": "aramex", "service": "Express",
  "reference": "SO-10025",
  "description": "Clothes",
  "from": { "name": "My Store", "phone": "+966500000000", "city": "Riyadh", "line1": "King Fahd Road" },
  "to": { "name": "Sara Al-Qahtani", "phone": "+966551234567", "city": "Jeddah",
          "district": "Al Rawdah", "street": "Prince Sultan Road",
          "building_no": "1234", "postal_code": "23433", "short_code": "JEDA2929" },
  "boxes": [ { "weight_kg": 1.5, "length_cm": 30, "width_cm": 20, "height_cm": 10 } ]
}

201 Created  { "id": 12, "reference": "SO-10025", "status": "CREATED",
  "tracking_number": "...", "price": 19, "has_label": true }

قواعد مهمةRules that matter

المرجع (reference) رقم طلبك أنت، ولا يتكرر. إعادة الإرسال بنفس المرجع ترجع الشحنة نفسها.The reference is your own order number and is unique. Sending it again returns the same shipment.
الأسعار نهائية بالريال، ويُحتسب الوزن الأكبر بين الفعلي ووزن الحجم (الطول × العرض × الارتفاع ÷ 4000). قد يُعدَّل الفرق بعد الاستلام.Prices are final, in SAR. The larger of the real and size weight (length × width × height ÷ 4000) is used. A difference found after pickup is settled automatically.
الأخطاء ترجع بصيغة {"error": "..."} مع رمز HTTP: 400 بيانات خاطئة، 401 مفتاح غير صالح، 402 رصيد غير كافٍ، 403 حساب غير مفعّل، 404 غير موجود.Errors come back as {"error": "..."} with an HTTP code: 400 bad data, 401 invalid key, 402 not enough balance, 403 account not active, 404 not found.
الدفع عند الاستلام غير متاح بعد، فأرسل cod_amount صفرًا.Cash on delivery is not available yet, so send cod_amount as 0.
العنوان: المدينة والحي والشارع مطلوبة، ورقم المبنى والرمز البريدي والعنوان المختصر اختيارية لكنها تسرّع التوصيل.Address: city, district and street are required; building number, postal code and short address are optional but make delivery faster.

جاهز تبدأ؟Ready to start?

افتح حسابك اليوم، وأرسل أول شحنة بعد تفعيل الحساب.Open your account today and send your first shipment once it is activated.

إنشاء حساب مجانيCreate a free account