مرجع واجهة شركة التوصيل API v1

{
  "success": true,
  "data": {
    "company": { "id": 13, "name": "Example Delivery", "phone": "0944000000" },
    "plan": {
      "name": "Pro",
      "expires_at": "2026-12-01 00:00:00",
      "features": [ { "feature": "Company API — 120 per minute / 20,000 per day", "enabled": true } ]
    },
    "usage": [ { "name": "API requests today", "used": 1240, "limit": 20000 } ]
  }
}

{
  "success": true,
  "data": [
    {
      "id": 41, "business_name": "Flower Shop", "contact_name": "Ahmad", "phone": "0933000000", "email": "shop@example.com", "active": true,
      "pickup_locations": [ { "id": 7, "name": "Main branch", "address": "Damascus, Mazzeh", "phone": "0933000000", "default_shop": 1, "default": true } ]
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 12, "last_page": 1 }
}

{
  "success": true,
  "data": [
    { "id": 5, "name": "Samer", "phone": "0944000001", "active": true, "open_parcels": 12, "parcel_limit": 50, "online": true, "available": true }
  ]
}

{ "deliveryman_id": 5, "note": "Call before arriving", "force": false }

{ "action": "partial", "collected": 15, "note": "One item returned" }

{
  "success": true,
  "data": {
    "id": 5521,
    "tracking_number": "DS261013AB12CD",
    "reference": "ORD-1001",
    "stage": "out_for_delivery",
    "status_code": 7,
    "status_label": "Delivery Man Assign",
    "company_id": 13,
    "company_name": "Example Delivery",
    "external_tracking_number": null,
    "recipient": { "name": "Sara", "phone": "0944123456", "governorate": "Damascus", "address": "Mazzeh, building 4", "lat": null, "lng": null },
    "cod_amount": 25,
    "cod_collected": 0,
    "weight_kg": 1,
    "charges": { "delivery_fee": 6, "platform_fee": 0 },
    "delivery_attempts": 0,
    "note": null,
    "tracking_url": "https://YOUR_DOMAIN/t/DS261013AB12CD",
    "created_at": "2026-10-13T10:00:00+03:00",
    "updated_at": "2026-10-13T12:10:00+03:00",
    "merchant": { "id": 41, "name": "Flower Shop" },
    "deliveryman": { "id": 5, "name": "Samer" }
  }
}

curl -X POST https://YOUR_DOMAIN/api/company/v1/parcels \
  -H "Authorization: Bearer YOUR_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "merchant_id": 41,
    "reference": "ORD-1001",
    "recipient": {
      "name": "Sara",
      "phone": "0944123456",
      "governorate": "Damascus",
      "address": "Mazzeh, building 4"
    },
    "cod_amount": 25,
    "weight": 1
  }'

const BASE = "https://YOUR_DOMAIN/api/company/v1";

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${process.env.DS_COMPANY_KEY}`,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!json.success) {
    throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
  }
  return json.data;
}

async function createParcel() {
  const parcel = await call("POST", "/parcels", {
    merchant_id: 41,
    reference: "ORD-1001",
    recipient: { name: "Sara", phone: "0944123456", governorate: "Damascus", address: "Mazzeh, building 4" },
    cod_amount: 25,
    weight: 1,
  });
  console.log(parcel.tracking_number, parcel.stage, parcel.merchant.name);
}

createParcel();

<?php
function ds_call(string $method, string $path, ?array $body = null): array
{
    $options = [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('DS_COMPANY_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
    ];
    if ($body !== null) {
        $options[CURLOPT_POSTFIELDS] = json_encode($body);
    }
    $ch = curl_init('https://YOUR_DOMAIN/api/company/v1' . $path);
    curl_setopt_array($ch, $options);
    $res    = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if (!($res['success'] ?? false)) {
        throw new RuntimeException("$status {$res['error']['code']}: {$res['error']['message']}");
    }

    return $res['data'];
}

$parcel = ds_call('POST', '/parcels', [
    'merchant_id' => 41,
    'reference'   => 'ORD-1001',
    'recipient'   => ['name' => 'Sara', 'phone' => '0944123456', 'governorate' => 'Damascus', 'address' => 'Mazzeh, building 4'],
    'cod_amount'  => 25,
    'weight'      => 1,
]);
echo $parcel['tracking_number'], "\n";

import os
import requests

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


def call(method, path, body=None):
    r = requests.request(method, BASE + path, json=body, headers=HEADERS, timeout=30)
    data = r.json()
    if not data["success"]:
        raise RuntimeError(f"{r.status_code} {data['error']['code']}: {data['error']['message']}")
    return data["data"]


parcel = call("POST", "/parcels", {
    "merchant_id": 41,
    "reference": "ORD-1001",
    "recipient": {"name": "Sara", "phone": "0944123456", "governorate": "Damascus", "address": "Mazzeh, building 4"},
    "cod_amount": 25,
    "weight": 1,
})
print(parcel["tracking_number"], parcel["stage"])

curl "https://YOUR_DOMAIN/api/company/v1/parcels?stage=processing&per_page=100" \
  -H "Authorization: Bearer YOUR_COMPANY_API_KEY" -H "Accept: application/json"

curl -X POST https://YOUR_DOMAIN/api/company/v1/parcels/DS261013AB12CD/assign \
  -H "Authorization: Bearer YOUR_COMPANY_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{ "deliveryman_id": 5, "note": "Call before arriving" }'

curl -X POST https://YOUR_DOMAIN/api/company/v1/parcels/DS261013AB12CD/status \
  -H "Authorization: Bearer YOUR_COMPANY_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{ "action": "deliver", "note": "Received by the family" }'

const BASE = "https://YOUR_DOMAIN/api/company/v1";
const HEADERS = {
  "Authorization": `Bearer ${process.env.DS_COMPANY_KEY}`,
  "Content-Type": "application/json",
  "Accept": "application/json",
};

async function call(method, path, body) {
  const res = await fetch(BASE + path, { method, headers: HEADERS, body: body ? JSON.stringify(body) : undefined });
  const json = await res.json();
  if (!json.success) {
    throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

async function dispatchAndDeliver() {
  const list = await call("GET", "/parcels?stage=processing&per_page=100");
  // assign only parcels at the warehouse (5) or hub (19)
  for (const p of list.data.filter((x) => [5, 19].includes(x.status_code))) {
    try {
      await call("POST", `/parcels/${p.tracking_number}/assign`, { deliveryman_id: 5 });
    } catch (e) {
      console.error(p.tracking_number, e.message); // for example 409 deliveryman_full
    }
  }
  const done = await call("POST", "/parcels/DS261013AB12CD/status", { action: "deliver", note: "Received by the family" });
  console.log(done.data.stage, done.data.deliveryman);
}

dispatchAndDeliver();

<?php
function ds_call(string $method, string $path, ?array $body = null): array
{
    $options = [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('DS_COMPANY_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
    ];
    if ($body !== null) {
        $options[CURLOPT_POSTFIELDS] = json_encode($body);
    }
    $ch = curl_init('https://YOUR_DOMAIN/api/company/v1' . $path);
    curl_setopt_array($ch, $options);
    $res    = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if (!($res['success'] ?? false)) {
        throw new RuntimeException("$status {$res['error']['code']}: {$res['error']['message']}");
    }

    return $res;
}

$list = ds_call('GET', '/parcels?stage=processing&per_page=100');
foreach ($list['data'] as $p) {
    if (!in_array($p['status_code'], [5, 19], true)) {
        continue; // assign only parcels at the warehouse (5) or hub (19)
    }
    try {
        ds_call('POST', "/parcels/{$p['tracking_number']}/assign", ['deliveryman_id' => 5]);
    } catch (RuntimeException $e) {
        echo $e->getMessage(), "\n"; // for example 409 deliveryman_full
    }
}
$done = ds_call('POST', '/parcels/DS261013AB12CD/status', ['action' => 'deliver', 'note' => 'Received by the family']);
echo $done['data']['stage'], "\n";

import os
import requests

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


def call(method, path, body=None, params=None):
    r = requests.request(method, BASE + path, json=body, params=params, headers=HEADERS, timeout=30)
    data = r.json()
    if not data["success"]:
        raise RuntimeError(f"{r.status_code} {data['error']['code']}: {data['error']['message']}")
    return data


parcels = call("GET", "/parcels", params={"stage": "processing", "per_page": 100})["data"]
for p in parcels:
    if p["status_code"] not in (5, 19):
        continue  # assign only parcels at the warehouse (5) or hub (19)
    try:
        call("POST", f"/parcels/{p['tracking_number']}/assign", {"deliveryman_id": 5})
    except RuntimeError as e:
        print(e)  # for example 409 deliveryman_full

done = call("POST", "/parcels/DS261013AB12CD/status", {"action": "deliver", "note": "Received by the family"})
print(done["data"]["stage"], done["data"]["deliveryman"])