الربط البرمجي

اربط متجرك بالشبكة

واجهة برمجية بنمط REST وصيغة JSON لإنشاء الشحنات وتتبّع كلّ طرد وطلب الالتقاط والاطّلاع على التحويلات، وإشعارات آلية موقَّعة تُعلمك بكلّ جديد، ووحدات للمتاجر الإلكترونية، ونموذج استيراد لكلّ ما تبقّى.

أنشئ مفتاح اختبار نزّل نموذج الاستيراد

ابدأ بثلاث طلبات

تمرّ كلّ الطلبات عبر عنوان الاختبار أدناه، بصيغة JSON وترميز UTF-8. المبالغ بالدينار دون كسور، والتواريخ بتوقيت الجزائر.

العنوان الأساسي: https://algeriaagency.com/api/demos/logistique/v1
المصادقة: يحمل كلّ طلب مفتاحك في الترويسة X-Api-Key. يُنشأ المفتاح في فضاء البائع، قسم الواجهة البرمجية، ويبدأ بـ kh_test_ ولا يُعرض إلّا مرّة واحدة.X-Api-Key: kh_test_••••••••••••••••••••7Q2m
طلبات قابلة للإعادة: أضف الترويسة Idempotency-Key إلى كلّ طلب POST: المفتاح نفسه خلال 24 ساعة يعيد الجواب نفسه دون إنشاء طرد ثانٍ. والترويسة نفسها بمحتوى مختلف تُرفض بالرمز 409.
ما تفعله بيئة الاختبار: في العرض التوضيحي يُستبدل كلّ مستلم عند الاستلام بمستلم تجريبي برقم مخفي، ولا يُحفظ سوى بصمة الرقم. وتُسجَّل الإشعارات الآلية في سجلّ فضائك ولا تُرسل أبدًا إلى الخارج. ويُمحى كلّ شيء بعد 24 ساعة.

أنشئ مفتاح اختبار في فضاء البائع.
اطلب السعر عبر GET /tariffs/quote لعرض كلفة التوصيل في سلّة الشراء.
أنشئ الشحنة عبر POST /shipments حين تُؤكَّد الطلبية، ثمّ اطبع الملصق.
استمع إلى الحدث shipment.status_changed لتحديث الطلبية دون استجواب الواجهة.

نقاط الربط

ستّ نقاط ربط تغطّي مسار الطلبية، من السعر المعروض في السلّة إلى المال المحوَّل.

POST/shipments
GET/shipments/{tracking}
POST/shipments/bulk
GET/tariffs/quote
POST/pickups
GET/payouts

POST/api/demos/logistique/v1/shipments

إنشاء شحنة

تسجّل طردًا وتحسب سعره ونافذة توصيله وخطر رفضه، وتعيد رقم التتبّع والملصق.

يقبل Idempotency-Keyالأخطاء الممكنة :400 · 401 · 409 · 422 · 429

متن الطلب
الحقل	النوع	إلزامي	الوصف
`reference`	`string`≤ 40	لا	رقم طلبيتك، يعود كما هو.
`recipient`	`object`	نعم	المستلم.
`recipient.name`	`string`2–80	نعم	اسمه. يُستبدل باسم تجريبي في بيئة الاختبار.
`recipient.phone`	`string`	نعم	هاتف نقّال جزائري. يُخفى ويُستبدل في بيئة الاختبار، ولا تُحفظ سوى بصمته.
`destination`	`object`	نعم	مكان التوصيل.
`destination.wilaya`	`integer`1–69	نعم	رمز الولاية، من 1 إلى 69.
`destination.commune`	`string`2–60	نعم	بلدية من هذه الولاية: معرّفها أو اسمها بالعربية أو بالفرنسية أو بالحروف اللاتينية.
`destination.landmark`	`string`≤ 160	لا	معلم بدل العنوان: «مقابل المسجد»، «خلف مكتب البريد».
`mode`	`stringhomestop-desk`	نعم	`home` (إلى المنزل) أو `stop-desk` (الاستلام من الوكالة).
`agency`	`string`	لا	وكالة الاستلام في حالة نقطة الاستلام، وهي افتراضيًا وكالة الولاية.
`weight_kg`	`number`0.05–70	نعم	الوزن بالكيلوغرام.
`dimensions_cm`	`object`	لا	الأبعاد بالسنتيمتر، لحساب الوزن الحجمي.
`dimensions_cm.length`	`integer`1–300	نعم	الطول.
`dimensions_cm.width`	`integer`1–300	نعم	العرض.
`dimensions_cm.height`	`integer`1–300	نعم	الارتفاع.
`cod_amount`	`integer`0–1000000	نعم	المبلغ المحصَّل عند الباب بالدينار، و0 لطرد مدفوع مسبقًا.
`declared_value`	`integer`0–5000000	لا	القيمة المصرَّح بها للتأمين، وهي افتراضيًا المبلغ المحصَّل.
`product`	`string`2–120	نعم	محتوى الطرد في كلمات قليلة.
`quantity`	`integer`1–99	لا	عدد القطع.
`options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	لا	الخيارات: التأمين، قابل للكسر، الاستبدال، التأكيد، الفتح قبل الدفع، السريع.
`note`	`string`≤ 200	لا	تعليمة لعامل التوصيل.

الجواب 201
الحقل	النوع	إلزامي	الوصف
`tracking_number`	`string`	نعم	رقم التتبّع: `KH` وعشرة أرقام، آخرها رقم تحقّق.
`reference`	`string`	لا	رقم طلبيتك، يعود كما هو.
`state`	`string` القيم (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	نعم	وضع الطرد.
`price`	`object`	نعم	سعر الإرسال.
`price.ht`	`integer`	نعم	دون رسوم.
`price.tva`	`integer`	نعم	الرسم على القيمة المضافة.
`price.ttc`	`integer`	نعم	بكلّ الرسوم.
`price.lines[]`	`array`	نعم	التفصيل سطرًا بسطر.
`price.lines[].key`	`string`	نعم	طبيعة السطر: نقل، رسوم تحصيل، خيار…
`price.lines[].amount`	`integer`	نعم	مبلغه بكلّ الرسوم.
`price.indicative`	`boolean`	نعم	صحيح دائمًا: التعريفة إرشادية.
`sla`	`object`	نعم	نافذة التوصيل الموعودة، بالساعات بعد الالتقاط.
`sla.min_hours`	`integer`	نعم	في أقرب تقدير.
`sla.max_hours`	`integer`	نعم	في أبعد تقدير.
`risk`	`object`	نعم	خطر الرفض المقدَّر، مع أسبابه في فضاء البائع.
`risk.score`	`integer`0–100	نعم	من 0 إلى 100.
`risk.band`	`stringlowmediumhigh`	نعم	منخفض أو متوسّط أو مرتفع.
`label_url`	`string`	نعم	الملصق بمقاس 10 × 15 بصيغة `PDF` (نموذج في العرض التوضيحي).
`tracking_url`	`string`	نعم	صفحة التتبّع التي تُرسل إلى الزبون.
`created_at`	`datetime`	نعم	تاريخ الإنشاء.

الطلب — curl

curl -X POST 'https://algeriaagency.com/api/demos/logistique/v1/shipments' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  -H 'Idempotency-Key: 6f1c2d0e-commande-0412' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "CMD-2026-0412",
    "recipient": {
      "name": "Destinataire démo n° 42",
      "phone": "06 •• •• 48 17"
    },
    "destination": {
      "wilaya": 16,
      "commune": "Bab Ezzouar",
      "landmark": "en face de la mosquée El Feth"
    },
    "mode": "home",
    "weight_kg": 0.8,
    "cod_amount": 2500,
    "product": "Coffret soins visage",
    "options": [
      "confirmation"
    ]
  }'

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/shipments', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reference": "CMD-2026-0412",
    "recipient": {
      "name": "Destinataire démo n° 42",
      "phone": "06 •• •• 48 17"
    },
    "destination": {
      "wilaya": 16,
      "commune": "Bab Ezzouar",
      "landmark": "en face de la mosquée El Feth"
    },
    "mode": "home",
    "weight_kg": 0.8,
    "cod_amount": 2500,
    "product": "Coffret soins visage",
    "options": [
      "confirmation"
    ]
  }),
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/shipments');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
      "reference": "CMD-2026-0412",
      "recipient": {
        "name": "Destinataire démo n° 42",
        "phone": "06 •• •• 48 17"
      },
      "destination": {
        "wilaya": 16,
        "commune": "Bab Ezzouar",
        "landmark": "en face de la mosquée El Feth"
      },
      "mode": "home",
      "weight_kg": 0.8,
      "cod_amount": 2500,
      "product": "Coffret soins visage",
      "options": [
        "confirmation"
      ]
    }',
]);
$data = json_decode(curl_exec($ch), true);

الجواب 201

{
  "tracking_number": "KH4831200573",
  "reference": "CMD-2026-0412",
  "state": "pending-confirmation",
  "price": {
    "ht": 437,
    "tva": 83,
    "ttc": 520,
    "lines": [
      {
        "key": "transport",
        "amount": 400
      },
      {
        "key": "cod-fee",
        "amount": 50
      },
      {
        "key": "confirmation",
        "amount": 70
      }
    ],
    "indicative": true
  },
  "sla": {
    "min_hours": 12,
    "max_hours": 24
  },
  "risk": {
    "score": 21,
    "band": "low"
  },
  "label_url": "/api/demos/logistique/v1/shipments/KH4831200573/label.pdf",
  "tracking_url": "/demos/logistique/suivi/KH4831200573",
  "created_at": "2026-10-19T10:42:00+01:00"
}

GET/api/demos/logistique/v1/shipments/{tracking}

قراءة شحنة

حالة الطرد ومراحله وتحصيله، ونافذة وصوله حين يكون في طريق التوصيل.

الأخطاء الممكنة :401 · 404 · 429

معامل في المسار
الحقل	النوع	إلزامي	الوصف
`tracking`	`string`	نعم	رقم التتبّع: `KH` وعشرة أرقام، آخرها رقم تحقّق.

الجواب 200
الحقل	النوع	إلزامي	الوصف
`tracking_number`	`string`	نعم	رقم التتبّع: `KH` وعشرة أرقام، آخرها رقم تحقّق.
`state`	`string` القيم (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	نعم	وضع الطرد.
`mode`	`stringhomestop-desk`	نعم	`home` (إلى المنزل) أو `stop-desk` (الاستلام من الوكالة).
`destination`	`object`	نعم	مكان التوصيل.
`destination.wilaya`	`integer`1–69	نعم	رمز الولاية، من 1 إلى 69.
`destination.commune`	`string`2–60	نعم	بلدية من هذه الولاية: معرّفها أو اسمها بالعربية أو بالفرنسية أو بالحروف اللاتينية.
`cod_amount`	`integer`	نعم	المبلغ المحصَّل عند الباب بالدينار، و0 لطرد مدفوع مسبقًا.
`cod_state`	`string` القيم (8) `pendingcollectedin-transit-to-hubreconciledpaid-outpartialdisputedrefunded`	نعم	أين وصل المال المحصَّل.
`attempts`	`integer`0–3	نعم	محاولات التوصيل، ثلاث على الأكثر.
`eta`	`object`	لا	نافذة الوصول، حين يكون الطرد في طريق التوصيل.
`eta.earliest`	`datetime`	نعم	بداية النافذة.
`eta.latest`	`datetime`	نعم	نهاية النافذة.
`events[]`	`array`	نعم	المراحل، من الأقدم إلى الأحدث.
`events[].state`	`string` القيم (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	نعم	وضع الطرد.
`events[].at`	`datetime`	نعم	وقت المرحلة.
`events[].place`	`string`	نعم	المكان: البلدية أو رمز مركز الفرز أو الوكالة.
`events[].reason`	`stringabsentrefusedwrong-addressunreachablerescheduled`	لا	في حال الإخفاق، السبب.

الطلب — curl

curl -X GET 'https://algeriaagency.com/api/demos/logistique/v1/shipments/KH4831200573' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  --compressed

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/shipments/KH4831200573', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
  },
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/shipments/KH4831200573');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
    ],
]);
$data = json_decode(curl_exec($ch), true);

الجواب 200

{
  "tracking_number": "KH4831200573",
  "state": "out-for-delivery",
  "mode": "home",
  "destination": {
    "wilaya": 16,
    "commune": "Bab Ezzouar"
  },
  "cod_amount": 2500,
  "cod_state": "pending",
  "attempts": 0,
  "eta": {
    "earliest": "2026-10-20T10:30:00+01:00",
    "latest": "2026-10-20T12:30:00+01:00"
  },
  "events": [
    {
      "state": "picked-up",
      "at": "2026-10-19T15:10:00+01:00",
      "place": "Bab Ezzouar"
    },
    {
      "state": "at-origin-hub",
      "at": "2026-10-19T19:45:00+01:00",
      "place": "RBA"
    },
    {
      "state": "out-for-delivery",
      "at": "2026-10-20T08:20:00+01:00",
      "place": "Bab Ezzouar"
    }
  ]
}

POST/api/demos/logistique/v1/shipments/bulk

إنشاء شحنات دفعة واحدة

حتّى 500 طرد في الطلب الواحد. تُنشأ الأسطر الصحيحة، وتعود الأخرى مع السبب، ومع اقتراحات حين يتعلّق الأمر بمكان.

يقبل Idempotency-Keyالأخطاء الممكنة :400 · 401 · 409 · 413 · 429

متن الطلب
الحقل	النوع	إلزامي	الوصف
`shipments[]`	`array`1–500	نعم	الطرود، بالصيغة نفسها لشحنة واحدة.
`shipments[].reference`	`string`≤ 40	لا	رقم طلبيتك، يعود كما هو.
`shipments[].recipient`	`object`	نعم	المستلم.
`shipments[].recipient.name`	`string`2–80	نعم	اسمه. يُستبدل باسم تجريبي في بيئة الاختبار.
`shipments[].recipient.phone`	`string`	نعم	هاتف نقّال جزائري. يُخفى ويُستبدل في بيئة الاختبار، ولا تُحفظ سوى بصمته.
`shipments[].destination`	`object`	نعم	مكان التوصيل.
`shipments[].destination.wilaya`	`integer`1–69	نعم	رمز الولاية، من 1 إلى 69.
`shipments[].destination.commune`	`string`2–60	نعم	بلدية من هذه الولاية: معرّفها أو اسمها بالعربية أو بالفرنسية أو بالحروف اللاتينية.
`shipments[].destination.landmark`	`string`≤ 160	لا	معلم بدل العنوان: «مقابل المسجد»، «خلف مكتب البريد».
`shipments[].mode`	`stringhomestop-desk`	نعم	`home` (إلى المنزل) أو `stop-desk` (الاستلام من الوكالة).
`shipments[].agency`	`string`	لا	وكالة الاستلام في حالة نقطة الاستلام، وهي افتراضيًا وكالة الولاية.
`shipments[].weight_kg`	`number`0.05–70	نعم	الوزن بالكيلوغرام.
`shipments[].dimensions_cm`	`object`	لا	الأبعاد بالسنتيمتر، لحساب الوزن الحجمي.
`shipments[].dimensions_cm.length`	`integer`1–300	نعم	الطول.
`shipments[].dimensions_cm.width`	`integer`1–300	نعم	العرض.
`shipments[].dimensions_cm.height`	`integer`1–300	نعم	الارتفاع.
`shipments[].cod_amount`	`integer`0–1000000	نعم	المبلغ المحصَّل عند الباب بالدينار، و0 لطرد مدفوع مسبقًا.
`shipments[].declared_value`	`integer`0–5000000	لا	القيمة المصرَّح بها للتأمين، وهي افتراضيًا المبلغ المحصَّل.
`shipments[].product`	`string`2–120	نعم	محتوى الطرد في كلمات قليلة.
`shipments[].quantity`	`integer`1–99	لا	عدد القطع.
`shipments[].options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	لا	الخيارات: التأمين، قابل للكسر، الاستبدال، التأكيد، الفتح قبل الدفع، السريع.
`shipments[].note`	`string`≤ 200	لا	تعليمة لعامل التوصيل.

الجواب 200
الحقل	النوع	إلزامي	الوصف
`accepted[]`	`array`	نعم	الأسطر التي أُنشئت.
`accepted[].index`	`integer`	نعم	موضع السطر في الدفعة، بدءًا من 0.
`accepted[].tracking_number`	`string`	نعم	رقم التتبّع: `KH` وعشرة أرقام، آخرها رقم تحقّق.
`rejected[]`	`array`	نعم	الأسطر المرفوضة.
`rejected[].index`	`integer`	نعم	موضع السطر في الدفعة، بدءًا من 0.
`rejected[].errors[]`	`array`	نعم	ما ليس على ما يرام.
`rejected[].errors[].path`	`string`	نعم	الحقل المعني.
`rejected[].errors[].code`	`string`	نعم	رمز ثابت.
`rejected[].errors[].suggestions`	`array`	لا	في حالة المكان، أقرب الأسماء.

الطلب — curl

curl -X POST 'https://algeriaagency.com/api/demos/logistique/v1/shipments/bulk' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  -H 'Idempotency-Key: 6f1c2d0e-commande-0412' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipments": [
      {
        "reference": "CMD-2026-0412",
        "recipient": {
          "name": "Destinataire démo n° 42",
          "phone": "06 •• •• 48 17"
        },
        "destination": {
          "wilaya": 16,
          "commune": "Bab Ezzouar",
          "landmark": "en face de la mosquée El Feth"
        },
        "mode": "home",
        "weight_kg": 0.8,
        "cod_amount": 2500,
        "product": "Coffret soins visage",
        "options": [
          "confirmation"
        ]
      },
      {
        "reference": "CMD-2026-0413",
        "recipient": {
          "name": "Destinataire démo n° 42",
          "phone": "06 •• •• 48 17"
        },
        "destination": {
          "wilaya": 31,
          "commune": "Bir Djir"
        },
        "mode": "home",
        "weight_kg": 0.8,
        "cod_amount": 2500,
        "product": "Coffret soins visage",
        "options": [
          "confirmation"
        ]
      }
    ]
  }'

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/shipments/bulk', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "shipments": [
      {
        "reference": "CMD-2026-0412",
        "recipient": {
          "name": "Destinataire démo n° 42",
          "phone": "06 •• •• 48 17"
        },
        "destination": {
          "wilaya": 16,
          "commune": "Bab Ezzouar",
          "landmark": "en face de la mosquée El Feth"
        },
        "mode": "home",
        "weight_kg": 0.8,
        "cod_amount": 2500,
        "product": "Coffret soins visage",
        "options": [
          "confirmation"
        ]
      },
      {
        "reference": "CMD-2026-0413",
        "recipient": {
          "name": "Destinataire démo n° 42",
          "phone": "06 •• •• 48 17"
        },
        "destination": {
          "wilaya": 31,
          "commune": "Bir Djir"
        },
        "mode": "home",
        "weight_kg": 0.8,
        "cod_amount": 2500,
        "product": "Coffret soins visage",
        "options": [
          "confirmation"
        ]
      }
    ]
  }),
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/shipments/bulk');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
      "shipments": [
        {
          "reference": "CMD-2026-0412",
          "recipient": {
            "name": "Destinataire démo n° 42",
            "phone": "06 •• •• 48 17"
          },
          "destination": {
            "wilaya": 16,
            "commune": "Bab Ezzouar",
            "landmark": "en face de la mosquée El Feth"
          },
          "mode": "home",
          "weight_kg": 0.8,
          "cod_amount": 2500,
          "product": "Coffret soins visage",
          "options": [
            "confirmation"
          ]
        },
        {
          "reference": "CMD-2026-0413",
          "recipient": {
            "name": "Destinataire démo n° 42",
            "phone": "06 •• •• 48 17"
          },
          "destination": {
            "wilaya": 31,
            "commune": "Bir Djir"
          },
          "mode": "home",
          "weight_kg": 0.8,
          "cod_amount": 2500,
          "product": "Coffret soins visage",
          "options": [
            "confirmation"
          ]
        }
      ]
    }',
]);
$data = json_decode(curl_exec($ch), true);

الجواب 200

{
  "accepted": [
    {
      "index": 0,
      "tracking_number": "KH4831200573"
    }
  ],
  "rejected": [
    {
      "index": 1,
      "errors": [
        {
          "path": "destination.commune",
          "code": "commune-unknown",
          "suggestions": [
            "Bir el-Djir"
          ]
        }
      ]
    }
  ]
}

GET/api/demos/logistique/v1/tariffs/quote

حساب تعريفة

السعر بكلّ الرسوم ونافذة التوصيل بين ولايتين، مع الخيارات. التعريفة إرشادية وتتبع جدول الإدارة.

الأخطاء الممكنة :400 · 401 · 422 · 429

معاملات الطلب
الحقل	النوع	إلزامي	الوصف
`from_wilaya`	`integer`1–69	نعم	ولاية الانطلاق.
`to_wilaya`	`integer`1–69	نعم	ولاية الوصول.
`to_commune`	`string`	لا	بلدية الوصول، للتمييز داخل المدينة نفسها.
`weight_kg`	`number`0.05–70	نعم	الوزن بالكيلوغرام.
`mode`	`stringhomestop-desk`	نعم	`home` (إلى المنزل) أو `stop-desk` (الاستلام من الوكالة).
`cod_amount`	`integer`0≥	لا	المبلغ المحصَّل عند الباب بالدينار، و0 لطرد مدفوع مسبقًا.
`options`	`string`	لا	الخيارات نفسها، تفصل بينها فواصل.

الجواب 200
الحقل	النوع	إلزامي	الوصف
`band`	`string`	نعم	شريحة التعريفة: المدينة نفسها أو الولاية نفسها أو زوج من المناطق.
`price`	`object`	نعم	سعر الإرسال.
`price.ht`	`integer`	نعم	دون رسوم.
`price.tva`	`integer`	نعم	الرسم على القيمة المضافة.
`price.ttc`	`integer`	نعم	بكلّ الرسوم.
`price.lines[]`	`array`	نعم	التفصيل سطرًا بسطر.
`price.lines[].key`	`string`	نعم	طبيعة السطر: نقل، رسوم تحصيل، خيار…
`price.lines[].amount`	`integer`	نعم	مبلغه بكلّ الرسوم.
`price.indicative`	`boolean`	نعم	صحيح دائمًا: التعريفة إرشادية.
`sla`	`object`	نعم	نافذة التوصيل الموعودة، بالساعات بعد الالتقاط.
`sla.min_hours`	`integer`	نعم	في أقرب تقدير.
`sla.max_hours`	`integer`	نعم	في أبعد تقدير.
`unavailable`	`array`	نعم	الخيارات المطلوبة غير المتاحة على هذا المسار.

الطلب — curl

curl -X GET 'https://algeriaagency.com/api/demos/logistique/v1/tariffs/quote?from_wilaya=16&to_wilaya=31&weight_kg=1.2&mode=home&cod_amount=3500&options=insurance,fragile' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  --compressed

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/tariffs/quote?from_wilaya=16&to_wilaya=31&weight_kg=1.2&mode=home&cod_amount=3500&options=insurance,fragile', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
  },
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/tariffs/quote?from_wilaya=16&to_wilaya=31&weight_kg=1.2&mode=home&cod_amount=3500&options=insurance,fragile');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
    ],
]);
$data = json_decode(curl_exec($ch), true);

الجواب 200

{
  "band": "north>north",
  "price": {
    "ht": 882,
    "tva": 168,
    "ttc": 1050,
    "lines": [
      {
        "key": "transport",
        "amount": 750
      },
      {
        "key": "cod-fee",
        "amount": 50
      },
      {
        "key": "insurance",
        "amount": 100
      },
      {
        "key": "fragile",
        "amount": 150
      }
    ],
    "indicative": true
  },
  "sla": {
    "min_hours": 24,
    "max_hours": 48
  },
  "unavailable": []
}

POST/api/demos/logistique/v1/pickups

طلب التقاط

يمرّ عامل توصيل عندك في يوم العمل الذي تختاره، صباحًا أو بعد الظهر. بعد الساعة 14:00 لا يُضمن الالتقاط في اليوم نفسه.

يقبل Idempotency-Keyالأخطاء الممكنة :400 · 401 · 409 · 422 · 429

متن الطلب
الحقل	النوع	إلزامي	الوصف
`date`	`date`	نعم	يوم عمل: لا جمعة ولا عطلة رسمية.
`slot`	`stringmorningafternoon`	نعم	صباحًا أو بعد الظهر.
`parcels`	`integer`1–500	نعم	عدد الطرود المنتظرة.
`tracking_numbers`	`array`≤ 500	لا	الأرقام المعنية، إن كانت لديك.
`location`	`object`	نعم	مكان المرور، مع معلم.
`location.wilaya`	`integer`1–69	نعم	رمز الولاية، من 1 إلى 69.
`location.commune`	`string`2–60	نعم	بلدية من هذه الولاية: معرّفها أو اسمها بالعربية أو بالفرنسية أو بالحروف اللاتينية.
`location.landmark`	`string`≤ 160	لا	معلم بدل العنوان: «مقابل المسجد»، «خلف مكتب البريد».

الجواب 201
الحقل	النوع	إلزامي	الوصف
`pickup_ref`	`string`	نعم	مرجع الالتقاط.
`date`	`date`	نعم	يوم عمل: لا جمعة ولا عطلة رسمية.
`slot`	`stringmorningafternoon`	نعم	صباحًا أو بعد الظهر.
`state`	`stringscheduledcollectedmissedcancelled`	نعم	مبرمج أو منفَّذ أو فائت أو ملغى.

الطلب — curl

curl -X POST 'https://algeriaagency.com/api/demos/logistique/v1/pickups' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  -H 'Idempotency-Key: 6f1c2d0e-commande-0412' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "2026-10-20",
    "slot": "morning",
    "parcels": 14,
    "location": {
      "wilaya": 16,
      "commune": "Bab Ezzouar",
      "landmark": "à côté de la pharmacie de nuit"
    }
  }'

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/pickups', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "date": "2026-10-20",
    "slot": "morning",
    "parcels": 14,
    "location": {
      "wilaya": 16,
      "commune": "Bab Ezzouar",
      "landmark": "à côté de la pharmacie de nuit"
    }
  }),
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/pickups');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
      "date": "2026-10-20",
      "slot": "morning",
      "parcels": 14,
      "location": {
        "wilaya": 16,
        "commune": "Bab Ezzouar",
        "landmark": "à côté de la pharmacie de nuit"
      }
    }',
]);
$data = json_decode(curl_exec($ch), true);

الجواب 201

{
  "pickup_ref": "KH-DEMO-RAM-01877",
  "date": "2026-10-20",
  "slot": "morning",
  "state": "scheduled"
}

GET/api/demos/logistique/v1/payouts

قائمة التحويلات

تحويلات المبالغ المحصَّلة، بتحويل مصرفي أو بريدي، مع تفصيل الرسوم المقتطعة وموعد التحويل القادم.

الأخطاء الممكنة :400 · 401 · 429

معاملات الطلب
الحقل	النوع	إلزامي	الوصف
`from`	`date`	لا	ابتداءً من هذا التاريخ.
`to`	`date`	لا	إلى هذا التاريخ.
`state`	`stringscheduledsent`	لا	مبرمج أو مُرسَل.
`page`	`integer`1≥	لا	رقم الصفحة.
`per_page`	`integer`1–100	لا	عدد الأسطر في الصفحة.

الجواب 200
الحقل	النوع	إلزامي	الوصف
`payouts[]`	`array`	نعم	التحويلات، من الأحدث إلى الأقدم.
`payouts[].ref`	`string`	نعم	كشف التحويل.
`payouts[].scheduled_for`	`date`	نعم	اليوم المبرمج.
`payouts[].sent_at`	`datetime`	لا	وقت الإرسال.
`payouts[].method`	`stringbankccp`	نعم	تحويل مصرفي أو بريدي.
`payouts[].parcels`	`integer`	نعم	الطرود المشمولة بالتحويل.
`payouts[].collected`	`integer`	نعم	مجموع المحصَّل.
`payouts[].fees`	`integer`	نعم	الرسوم المقتطعة: التوصيل والتحصيل والخيارات والمرتجعات.
`payouts[].net`	`integer`	نعم	المبلغ المحوَّل.
`payouts[].state`	`stringscheduledsent`	نعم	مبرمج أو مُرسَل.
`next_payout_day`	`date`	نعم	يوم التحويل القادم.
`next_page`	`integer`	لا	الصفحة التالية، أو لا شيء.

الطلب — curl

curl -X GET 'https://algeriaagency.com/api/demos/logistique/v1/payouts?from=2026-10-01&state=sent' \
  -H 'X-Api-Key: kh_test_••••••••••••••••••••7Q2m' \
  --compressed

الطلب — JavaScript

const response = await fetch('https://algeriaagency.com/api/demos/logistique/v1/payouts?from=2026-10-01&state=sent', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.KHATT_API_KEY, // kh_test_••••••••••••••••••••7Q2m
  },
})
if (!response.ok) throw new Error((await response.json()).error.code)
const data = await response.json()

الطلب — PHP

<?php
$ch = curl_init('https://algeriaagency.com/api/demos/logistique/v1/payouts?from=2026-10-01&state=sent');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('KHATT_API_KEY'), // kh_test_••••••••••••••••••••7Q2m
    ],
]);
$data = json_decode(curl_exec($ch), true);

الجواب 200

{
  "payouts": [
    {
      "ref": "KH-DEMO-REL-00318",
      "scheduled_for": "2026-10-18",
      "sent_at": "2026-10-18T10:05:00+01:00",
      "method": "ccp",
      "parcels": 37,
      "collected": 112400,
      "fees": 18620,
      "net": 93780,
      "state": "sent"
    }
  ],
  "next_payout_day": "2026-10-21",
  "next_page": null
}

إشعارات آلية موقَّعة

صرّح بعنوان في فضاء البائع واختر الأحداث. يحمل كلّ إرسال توقيعًا تتحقّق منه قبل أن تثق في محتواه.

الأحداث

`shipment.status_changed`

يتغيّر وضع الطرد: التُقط، في مركز الفرز، قيد التوصيل، سُلّم، المستلم غائب، رُفض، أُرجع.

محتوى الحدث

{
  "id": "evt_7Hc2Qm8LxP0aR4tN9kDz",
  "type": "shipment.status_changed",
  "created_at": "2026-10-20T11:02:13+01:00",
  "data": {
    "tracking_number": "KH4831200573",
    "reference": "CMD-2026-0412",
    "from": "out-for-delivery",
    "to": "delivered",
    "at": "2026-10-20T11:02:10+01:00",
    "place": "Bab Ezzouar"
  }
}

`cod.collected`

حصّل عامل التوصيل المبلغ عند الباب، كاملًا أو جزئيًا.

محتوى الحدث

{
  "id": "evt_7Hc2Qm8LxP0aR4tN9kDz",
  "type": "cod.collected",
  "created_at": "2026-10-20T11:02:13+01:00",
  "data": {
    "tracking_number": "KH4831200573",
    "amount": 2500,
    "collected_at": "2026-10-20T11:02:10+01:00",
    "partial": false
  }
}

`payout.sent`

انطلق تحويل نحو حسابك المصرفي أو البريدي.

محتوى الحدث

{
  "id": "evt_7Hc2Qm8LxP0aR4tN9kDz",
  "type": "payout.sent",
  "created_at": "2026-10-20T11:02:13+01:00",
  "data": {
    "ref": "KH-DEMO-REL-00318",
    "net": 93780,
    "method": "ccp",
    "parcels": 37,
    "sent_at": "2026-10-18T10:05:00+01:00"
  }
}

التحقّق من التوقيع

تحمل الترويسة X-Khatt-Signature القيمة t= (وقت الإرسال بالثواني) والقيمة v1= (بصمة HMAC-SHA256 بالنظام الست عشري لـ t ونقطة والمتن الخام، محسوبة بسرّ العنوان). أعد حسابها، وقارن في زمن ثابت، وارفض كلّ إرسال مضى عليه أكثر من خمس دقائق.

X-Khatt-Signature: t=1760954533,v1=5f0c…e21a

التحقّق بلغة JavaScript

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (!parts.t || !parts.v1 || age > 300) return false
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

التحقّق بلغة PHP

<?php
function khatt_verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (empty($parts['t']) || empty($parts['v1'])) return false;
    if (abs(time() - (int) $parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

أجب برمز من فئة 2xx في أقلّ من عشر ثوانٍ. وإلّا يُعاد الإرسال بعد دقيقة، ثمّ 5 دقائق، ثمّ 30 دقيقة، ثمّ ساعتين، ثمّ 6 ساعات، ثمّ يُسجَّل فاشلًا.
يُنتج زرّ «إرسال تجربة» في فضاء البائع (أو الطلب POST /webhooks/test) مثالًا عن كلّ حدث.

الحدود والأخطاء

300 طلبًا في الساعة كحدّ أقصى لكلّ مفتاح. تبيّن الترويستان X-RateLimit-Remaining وX-RateLimit-Reset موقعك من الحدّ، وما زاد عليه يُجاب بالرمز 429 مع Retry-After.
تُحسب الدفعة طلبًا واحدًا وتضمّ 500 طرد على الأكثر. وتُقسَّم القوائم إلى صفحات من 100 سطر على الأكثر.
للخطأ دائمًا الشكل نفسه: رمز ثابت، ورسالة مقروءة، ولكلّ حقل مساره وسببه.

422

{
  "error": {
    "code": "unprocessable",
    "message": "…",
    "fields": [
      {
        "path": "destination.commune",
        "code": "commune-other-wilaya"
      }
    ]
  }
}

HTTP	code	الوصف
400	`invalid_request`	طلب غير مقروء: صيغة غير صالحة أو معامل ناقص.
401	`unauthorized`	مفتاح غائب أو مجهول أو ملغى.
403	`forbidden`	لا يملك المفتاح حقّ الوصول إلى هذا المورد.
404	`not_found`	لا طرد ولا تحويل بهذا الرقم لهذا الحساب.
409	`conflict`	سبق استعمال `Idempotency-Key` بمحتوى مختلف.
413	`too_large`	دفعة تتجاوز 500 طرد.
422	`unprocessable`	محتوى صالح لكنّه مرفوض: ولاية مجهولة، أو بلدية من ولاية أخرى، أو وزن خارج الحدود.
429	`rate_limited`	طلبات كثيرة: انتظر المدّة المبيَّنة.
500	`internal`	خطأ من جهتنا: أعد المحاولة بالمفتاح `Idempotency-Key` نفسه.

للمتاجر الإلكترونية

لا حاجة إلى كتابة أيّ سطر: وحدة جاهزة تضع التعريفة في السلّة، وتنشئ الشحنة عند تأكيد الطلبية، وتحدّث الطلبية في كلّ مرحلة.

متاجر على أنظمة إدارة محتوى مفتوحة المصدر
وحدة تُثبَّت من لوحة إدارة المتجر: التعريفة حسب الولاية في السلّة، والاختيار بين المنزل ونقطة الاستلام، والملصق من الطلبية مباشرة.
عرض توضيحي
متاجر مستضافة
تطبيق يُربط بنقرتين بمفتاحك: تصل الطلبيات إلى فضاء البائع جاهزة للتأكيد ووضع الملصقات.
عرض توضيحي
الأسواق الإلكترونية
موصل يقرأ طلبيات الأسواق الإلكترونية التي تبيع فيها، ويعيد رقم التتبّع إلى الزبون.
عرض توضيحي
البيع عبر الرسائل
تبيع عبر الرسائل الخاصّة؟ الصق الطلبية في فضاء البائع: يُتعرَّف على العنوان والمبلغ، وتؤكّد أنت كلّ حقل.
عرض توضيحي

الاستيراد من ملف جدول

لإرسال طلبيات يوم كامل دفعة واحدة دون واجهة برمجية: ملف واحد، وسطر لكلّ طرد، حتّى 500 سطر.

الأعمدة المعروفة

لا يهمّ الترتيب، وتُعرف العناوين بالعربية والإنجليزية أيضًا. الاسم والهاتف والولاية والبلدية والمبلغ حقول إلزامية.

يُفحص كلّ سطر عند الاستيراد: البلدية التي لا تنتمي إلى ولايتها يُنبَّه إليها مع البلديات القريبة، والوزن الفارغ يُحسب كيلوغرامًا واحدًا.

في العرض التوضيحي تُستبدل الأسماء والأرقام الواردة في الملف بقيم تجريبية منذ الاستيراد. أرقام النموذج مخفية.

نزّل النموذج (CSV)

العمود	إلزامي
`Nom`	نعم
`Téléphone`	نعم
`Wilaya`	نعم
`Commune`	نعم
`Adresse`	لا
`Poids`	لا
`Montant`	نعم
`Produit`	لا
`Remarque`	لا
`Quantité`	لا
`Mode`	لا

ابدأ بثلاث طلبات

نقاط الربط

إشعارات آلية موقَّعة

الأحداث

shipment.status_changed

cod.collected

payout.sent

التحقّق من التوقيع

الحدود والأخطاء

للمتاجر الإلكترونية

متاجر على أنظمة إدارة محتوى مفتوحة المصدر

متاجر مستضافة

الأسواق الإلكترونية

البيع عبر الرسائل

الاستيراد من ملف جدول

الأعمدة المعروفة

`shipment.status_changed`

`cod.collected`

`payout.sent`