مرجع واجهة التاجر API v1

{
  "success": true,
  "data": {
    "merchant_id": 12,
    "business_name": "My Shop",
    "plan": { "name": "Gold", "expires_on": "2026-12-01", "active": true },
    "balances": { "recharge": 150.5, "cod_due": 320, "held": 0, "company_due": 0 },
    "currency": "$"
  }
}

{
  "success": true,
  "data": [
    { "id": 13, "name": "Example Delivery", "type": "delivery_company", "pricing_mode": "governorate", "supports_own_account": false, "coverage": null },
    { "id": 16, "name": "Example Carrier", "type": "carrier", "pricing_mode": "carrier_quote", "supports_own_account": true, "coverage": { "SY": [] } }
  ]
}

curl -X POST https://YOUR_DOMAIN/api/v1/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Language: en" \
  -d '{ "company_id": 13, "recipient": { "governorate": "Damascus" }, "weight": 2 }'

{
  "success": true,
  "data": {
    "pricing_mode": "governorate",
    "pricing_label": "Fixed amount per governorate",
    "governorate": "Damascus",
    "distance_km": 0,
    "weight_kg": 2,
    "delivery_fee": 6,
    "platform_fee": 1,
    "charged_now": 7
  }
}

{
  "success": true,
  "data": {
    "id": 5521,
    "tracking_number": "DS261013AB12CD",
    "reference": "ORDER-1001",
    "stage": "processing",
    "status_code": 5,
    "status_label": "Received Warehouse",
    "company_id": 13,
    "company_name": "Example Delivery",
    "external_tracking_number": null,
    "recipient": {
      "name": "Ahmad Mohammad",
      "phone": "0933123456",
      "governorate": "Damascus",
      "address": "Mazzeh, building 4",
      "lat": 33.5021,
      "lng": 36.2489
    },
    "cod_amount": 25,
    "cod_collected": 0,
    "weight_kg": 1.5,
    "charges": { "delivery_fee": 6, "platform_fee": 1 },
    "delivery_attempts": 0,
    "note": "Call before arriving",
    "tracking_url": "https://YOUR_DOMAIN/t/DS261013AB12CD",
    "created_at": "2026-10-13T10:00:00+03:00",
    "updated_at": "2026-10-13T10:00:00+03:00"
  }
}

"events": [
  { "status_code": 1, "stage": "pending", "status_label": "Pending", "note": "Parcel created (api)", "at": "2026-10-13T10:00:00+03:00" },
  { "status_code": 5, "stage": "processing", "status_label": "Received Warehouse", "note": null, "at": "2026-10-13T10:00:01+03:00" }
]

{
  "success": true,
  "data": {
    "period": { "from": "2026-10-01", "to": "2026-10-31" },
    "currency": "USD",
    "wallets": [
      { "wallet": "recharge", "name": "Shipping balance", "opening": 50, "credits": 200, "debits": 132.5, "closing": 117.5, "count": 41 }
    ],
    "by_category": [
      { "category": "parcel_created", "name": "Parcel creation fee", "credits": 0, "debits": 132.5, "count": 38 }
    ],
    "lines": [
      { "id": 9811, "date": "2026-10-02T10:14:00+03:00", "wallet": "recharge", "wallet_name": "Shipping balance",
        "type": "parcel_created", "type_name": "Parcel creation fee", "credit": 0, "debit": 3.5, "balance": 46.5,
        "description": "...", "parcel": "DS261002AB12CD" }
    ]
  },
  "meta": { "page": 1, "per_page": 100, "total": 41, "last_page": 1 }
}

curl -X POST https://YOUR_DOMAIN/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "name": "ERP", "url": "https://example.com/hooks/delivery", "events": ["parcel.delivered", "parcel.returned"] }'

{
  "success": true,
  "data": {
    "id": 7, "name": "ERP", "url": "https://example.com/hooks/delivery",
    "events": ["parcel.delivered", "parcel.returned"], "active": true,
    "disabled_reason": null, "last_status": null, "last_error": null, "last_sent_at": null,
    "secret": "whsec_xxxxxxxxxxxxxxxx"
  }
}

curl -X POST https://YOUR_DOMAIN/api/v1/parcels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "company_id": 13,
    "reference": "ORDER-1001",
    "recipient": {
      "name": "Ahmad Mohammad",
      "phone": "0933123456",
      "governorate": "Damascus",
      "address": "Mazzeh, next to the mosque, building 4",
      "lat": 33.5021,
      "lng": 36.2489
    },
    "cod_amount": 25,
    "weight": 1.5,
    "note": "Call before arriving"
  }'

async function createParcel() {
  const res = await fetch("https://YOUR_DOMAIN/api/v1/parcels", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.DS_API_KEY}`,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({
      company_id: 13,
      reference: "ORDER-1001",
      recipient: {
        name: "Ahmad Mohammad",
        phone: "0933123456",
        governorate: "Damascus",
        address: "Mazzeh, building 4",
      },
      cod_amount: 25,
      weight: 1.5,
    }),
  });
  const json = await res.json();
  if (!json.success) {
    throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
  }
  console.log(json.data.tracking_number, json.data.tracking_url, json.duplicate === true);
}

createParcel();

<?php
$payload = [
    'company_id' => 13,
    'reference'  => 'ORDER-1001',
    'recipient'  => [
        'name'        => 'Ahmad Mohammad',
        'phone'       => '0933123456',
        'governorate' => 'Damascus',
        'address'     => 'Mazzeh, building 4',
    ],
    'cod_amount' => 25,
    'weight'     => 1.5,
];

$ch = curl_init('https://YOUR_DOMAIN/api/v1/parcels');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('DS_API_KEY'),
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body['success'] ?? false)) {
    throw new RuntimeException("$status {$body['error']['code']}: {$body['error']['message']}");
}
echo $body['data']['tracking_number'], "\n";

import os
import requests

BASE = "https://YOUR_DOMAIN/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
    "Accept": "application/json",
}

payload = {
    "company_id": 13,
    "reference": "ORDER-1001",
    "recipient": {
        "name": "Ahmad Mohammad",
        "phone": "0933123456",
        "governorate": "Damascus",
        "address": "Mazzeh, building 4",
    },
    "cod_amount": 25,
    "weight": 1.5,
}

r = requests.post(f"{BASE}/parcels", json=payload, headers=HEADERS, timeout=30)
body = r.json()
if not body["success"]:
    raise RuntimeError(f"{r.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"]["tracking_number"], body.get("duplicate", False))

curl "https://YOUR_DOMAIN/api/v1/parcels?stage=out_for_delivery&per_page=50&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json"

curl "https://YOUR_DOMAIN/api/v1/parcels/ORDER-1001" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json"

async function listAndTrack() {
  const base = "https://YOUR_DOMAIN/api/v1";
  const headers = { Authorization: `Bearer ${process.env.DS_API_KEY}`, Accept: "application/json" };

  const list = await (await fetch(`${base}/parcels?stage=out_for_delivery&per_page=50`, { headers })).json();
  console.log(list.meta.total, list.data.map((p) => p.tracking_number));

  const one = await (await fetch(`${base}/parcels/ORDER-1001`, { headers })).json();
  if (one.success) {
    console.log(one.data.stage, one.data.events.map((e) => e.status_label));
  } else if (one.error.code === "not_found") {
    console.log("No parcel with this number or reference");
  }
}

listAndTrack();

<?php
function ds_get(string $path): array
{
    $ch = curl_init('https://YOUR_DOMAIN/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('DS_API_KEY'), 'Accept: application/json'],
    ]);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $body;
}

$list = ds_get('/parcels?' . http_build_query(['stage' => 'out_for_delivery', 'per_page' => 50]));
echo $list['meta']['total'], "\n";

$one = ds_get('/parcels/ORDER-1001');
if ($one['success']) {
    echo $one['data']['stage'], "\n";
}

import os
import requests

BASE = "https://YOUR_DOMAIN/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['DS_API_KEY']}", "Accept": "application/json"}

page = requests.get(f"{BASE}/parcels", params={"stage": "out_for_delivery", "per_page": 50}, headers=HEADERS, timeout=30).json()
print(page["meta"]["total"], [p["tracking_number"] for p in page["data"]])

one = requests.get(f"{BASE}/parcels/ORDER-1001", headers=HEADERS, timeout=30).json()
if one["success"]:
    print(one["data"]["stage"], [e["status_label"] for e in one["data"]["events"]])