Integrations

Plug your shop into the network

A REST API in JSON to create shipments, track every parcel, book a pick-up and read your payouts; signed webhooks to be told; modules for online shops; an import template for everything else.

Create a test key Download the import template

Start in three calls

Everything goes through the test address below, as UTF-8 JSON. Amounts are whole dinars; dates are Algiers time.

Base address: https://algeriaagency.com/api/demos/logistique/v1
Authentication: Every request carries your key in the X-Api-Key header. Keys are created in the seller space, under API; they start with kh_test_ and are shown once.X-Api-Key: kh_test_••••••••••••••••••••7Q2m
Safe retries: Add an Idempotency-Key header to every POST: the same key within 24 hours returns the same answer without creating a second parcel. The same header with a different body is refused with 409.
What the sandbox does: In the demonstration every recipient is replaced on arrival by a demo recipient with a masked number, and only a hash of the number is kept. Webhooks are written to your space’s log, never sent out. Everything is erased after 24 hours.

Create a test key in the seller space.
Ask for a price with GET /tariffs/quote to show delivery in your basket.
Create the shipment with POST /shipments when the order is confirmed, then print the label.
Listen for shipment.status_changed to update the order without polling the API.

Endpoints

Six endpoints cover an order’s journey, from the price shown in the basket to the money paid out.

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

POST/api/demos/logistique/v1/shipments

Create a shipment

Records a parcel, works out its price, delivery window and refusal risk, and returns the tracking number and the label.

Accepts Idempotency-KeyPossible errors :400 · 401 · 409 · 422 · 429

Request body
Field	Type	Required	Description
`reference`	`string`≤ 40	no	Your order number, returned as is.
`recipient`	`object`	yes	The recipient.
`recipient.name`	`string`2–80	yes	Their name. Replaced by a demo name in the sandbox.
`recipient.phone`	`string`	yes	An Algerian mobile. Masked and replaced in the sandbox; only a hash is kept.
`destination`	`object`	yes	Where to deliver.
`destination.wilaya`	`integer`1–69	yes	The wilaya code, 1 to 69.
`destination.commune`	`string`2–60	yes	A commune of that wilaya: its id or its name, in Arabic, French or Latin letters.
`destination.landmark`	`string`≤ 160	no	A landmark rather than an address: « opposite the mosque », « behind the post office ».
`mode`	`stringhomestop-desk`	yes	`home` or `stop-desk` (collected at an agency).
`agency`	`string`	no	The pick-up agency for a stop-desk; by default the wilaya’s own.
`weight_kg`	`number`0.05–70	yes	Weight in kilograms.
`dimensions_cm`	`object`	no	Dimensions in centimetres, for the volumetric weight.
`dimensions_cm.length`	`integer`1–300	yes	Length.
`dimensions_cm.width`	`integer`1–300	yes	Width.
`dimensions_cm.height`	`integer`1–300	yes	Height.
`cod_amount`	`integer`0–1000000	yes	Cash to collect at the door, in dinars; 0 for a prepaid parcel.
`declared_value`	`integer`0–5000000	no	Declared value for insurance; by default the amount collected.
`product`	`string`2–120	yes	What the parcel holds, in a few words.
`quantity`	`integer`1–99	no	Number of items.
`options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	no	Options: insurance, fragile, exchange, confirmation, open before paying, express.
`note`	`string`≤ 200	no	An instruction for the courier.

Response 201
Field	Type	Required	Description
`tracking_number`	`string`	yes	Tracking number: `KH` and ten digits, the last a check digit.
`reference`	`string`	no	Your order number, returned as is.
`state`	`string` Values (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	yes	The parcel’s state.
`price`	`object`	yes	The shipment’s price.
`price.ht`	`integer`	yes	Before tax.
`price.tva`	`integer`	yes	VAT.
`price.ttc`	`integer`	yes	Including tax.
`price.lines[]`	`array`	yes	The breakdown, line by line.
`price.lines[].key`	`string`	yes	What the line is: transport, collection fee, an option…
`price.lines[].amount`	`integer`	yes	Its amount including tax.
`price.indicative`	`boolean`	yes	Always true: the rate is indicative.
`sla`	`object`	yes	The promised delivery window, in hours after pick-up.
`sla.min_hours`	`integer`	yes	At the earliest.
`sla.max_hours`	`integer`	yes	At the latest.
`risk`	`object`	yes	The estimated refusal risk, with its reasons in the seller space.
`risk.score`	`integer`0–100	yes	0 to 100.
`risk.band`	`stringlowmediumhigh`	yes	Low, medium or high.
`label_url`	`string`	yes	The 10 × 15 label as a PDF (a specimen in the demonstration).
`tracking_url`	`string`	yes	The tracking page to send the buyer.
`created_at`	`datetime`	yes	When it was created.

Request — 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"
    ]
  }'

Request — 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()

Request — 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);

Response 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}

Read a shipment

A parcel’s state, its steps, its cash collection and, once out for delivery, its arrival window.

Possible errors :401 · 404 · 429

Path parameter
Field	Type	Required	Description
`tracking`	`string`	yes	Tracking number: `KH` and ten digits, the last a check digit.

Response 200
Field	Type	Required	Description
`tracking_number`	`string`	yes	Tracking number: `KH` and ten digits, the last a check digit.
`state`	`string` Values (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	yes	The parcel’s state.
`mode`	`stringhomestop-desk`	yes	`home` or `stop-desk` (collected at an agency).
`destination`	`object`	yes	Where to deliver.
`destination.wilaya`	`integer`1–69	yes	The wilaya code, 1 to 69.
`destination.commune`	`string`2–60	yes	A commune of that wilaya: its id or its name, in Arabic, French or Latin letters.
`cod_amount`	`integer`	yes	Cash to collect at the door, in dinars; 0 for a prepaid parcel.
`cod_state`	`string` Values (8) `pendingcollectedin-transit-to-hubreconciledpaid-outpartialdisputedrefunded`	yes	Where the collected cash stands.
`attempts`	`integer`0–3	yes	Delivery attempts, three at most.
`eta`	`object`	no	The arrival window, once the parcel is out for delivery.
`eta.earliest`	`datetime`	yes	Window start.
`eta.latest`	`datetime`	yes	Window end.
`events[]`	`array`	yes	The steps, oldest first.
`events[].state`	`string` Values (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	yes	The parcel’s state.
`events[].at`	`datetime`	yes	When the step happened.
`events[].place`	`string`	yes	Where: commune, hub code or agency.
`events[].reason`	`stringabsentrefusedwrong-addressunreachablerescheduled`	no	For a failure, the reason.

Request — curl

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

Request — 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()

Request — 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);

Response 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

Create shipments in bulk

Up to 500 parcels per call. Valid rows are created; the rest come back with the reason and, for a place, suggestions.

Accepts Idempotency-KeyPossible errors :400 · 401 · 409 · 413 · 429

Request body
Field	Type	Required	Description
`shipments[]`	`array`1–500	yes	The parcels, in the same shape as a single shipment.
`shipments[].reference`	`string`≤ 40	no	Your order number, returned as is.
`shipments[].recipient`	`object`	yes	The recipient.
`shipments[].recipient.name`	`string`2–80	yes	Their name. Replaced by a demo name in the sandbox.
`shipments[].recipient.phone`	`string`	yes	An Algerian mobile. Masked and replaced in the sandbox; only a hash is kept.
`shipments[].destination`	`object`	yes	Where to deliver.
`shipments[].destination.wilaya`	`integer`1–69	yes	The wilaya code, 1 to 69.
`shipments[].destination.commune`	`string`2–60	yes	A commune of that wilaya: its id or its name, in Arabic, French or Latin letters.
`shipments[].destination.landmark`	`string`≤ 160	no	A landmark rather than an address: « opposite the mosque », « behind the post office ».
`shipments[].mode`	`stringhomestop-desk`	yes	`home` or `stop-desk` (collected at an agency).
`shipments[].agency`	`string`	no	The pick-up agency for a stop-desk; by default the wilaya’s own.
`shipments[].weight_kg`	`number`0.05–70	yes	Weight in kilograms.
`shipments[].dimensions_cm`	`object`	no	Dimensions in centimetres, for the volumetric weight.
`shipments[].dimensions_cm.length`	`integer`1–300	yes	Length.
`shipments[].dimensions_cm.width`	`integer`1–300	yes	Width.
`shipments[].dimensions_cm.height`	`integer`1–300	yes	Height.
`shipments[].cod_amount`	`integer`0–1000000	yes	Cash to collect at the door, in dinars; 0 for a prepaid parcel.
`shipments[].declared_value`	`integer`0–5000000	no	Declared value for insurance; by default the amount collected.
`shipments[].product`	`string`2–120	yes	What the parcel holds, in a few words.
`shipments[].quantity`	`integer`1–99	no	Number of items.
`shipments[].options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	no	Options: insurance, fragile, exchange, confirmation, open before paying, express.
`shipments[].note`	`string`≤ 200	no	An instruction for the courier.

Response 200
Field	Type	Required	Description
`accepted[]`	`array`	yes	The rows created.
`accepted[].index`	`integer`	yes	The row’s position in the batch, from 0.
`accepted[].tracking_number`	`string`	yes	Tracking number: `KH` and ten digits, the last a check digit.
`rejected[]`	`array`	yes	The rows refused.
`rejected[].index`	`integer`	yes	The row’s position in the batch, from 0.
`rejected[].errors[]`	`array`	yes	What is wrong.
`rejected[].errors[].path`	`string`	yes	The field at fault.
`rejected[].errors[].code`	`string`	yes	A stable code.
`rejected[].errors[].suggestions`	`array`	no	For a place, the closest names.

Request — 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"
        ]
      }
    ]
  }'

Request — 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()

Request — 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);

Response 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

Get a rate

The all-in price and the delivery window between two wilayas, with options. The rate is indicative and follows management’s grid.

Possible errors :400 · 401 · 422 · 429

Query parameters
Field	Type	Required	Description
`from_wilaya`	`integer`1–69	yes	Origin wilaya.
`to_wilaya`	`integer`1–69	yes	Destination wilaya.
`to_commune`	`string`	no	Destination commune, to tell parts of one city apart.
`weight_kg`	`number`0.05–70	yes	Weight in kilograms.
`mode`	`stringhomestop-desk`	yes	`home` or `stop-desk` (collected at an agency).
`cod_amount`	`integer`0≥	no	Cash to collect at the door, in dinars; 0 for a prepaid parcel.
`options`	`string`	no	The same options, comma-separated.

Response 200
Field	Type	Required	Description
`band`	`string`	yes	The rate band: same city, same wilaya or a pair of zones.
`price`	`object`	yes	The shipment’s price.
`price.ht`	`integer`	yes	Before tax.
`price.tva`	`integer`	yes	VAT.
`price.ttc`	`integer`	yes	Including tax.
`price.lines[]`	`array`	yes	The breakdown, line by line.
`price.lines[].key`	`string`	yes	What the line is: transport, collection fee, an option…
`price.lines[].amount`	`integer`	yes	Its amount including tax.
`price.indicative`	`boolean`	yes	Always true: the rate is indicative.
`sla`	`object`	yes	The promised delivery window, in hours after pick-up.
`sla.min_hours`	`integer`	yes	At the earliest.
`sla.max_hours`	`integer`	yes	At the latest.
`unavailable`	`array`	yes	Requested options not offered on this route.

Request — 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

Request — 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()

Request — 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);

Response 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

Book a pick-up

A courier calls at your place on the working day you choose, morning or afternoon. After 2 p.m. a same-day pick-up is no longer guaranteed.

Accepts Idempotency-KeyPossible errors :400 · 401 · 409 · 422 · 429

Request body
Field	Type	Required	Description
`date`	`date`	yes	A working day: not a Friday, not a public holiday.
`slot`	`stringmorningafternoon`	yes	Morning or afternoon.
`parcels`	`integer`1–500	yes	How many parcels are waiting.
`tracking_numbers`	`array`≤ 500	no	Their numbers, if you have them.
`location`	`object`	yes	Where to call, with a landmark.
`location.wilaya`	`integer`1–69	yes	The wilaya code, 1 to 69.
`location.commune`	`string`2–60	yes	A commune of that wilaya: its id or its name, in Arabic, French or Latin letters.
`location.landmark`	`string`≤ 160	no	A landmark rather than an address: « opposite the mosque », « behind the post office ».

Response 201
Field	Type	Required	Description
`pickup_ref`	`string`	yes	The pick-up’s reference.
`date`	`date`	yes	A working day: not a Friday, not a public holiday.
`slot`	`stringmorningafternoon`	yes	Morning or afternoon.
`state`	`stringscheduledcollectedmissedcancelled`	yes	Scheduled, collected, missed or cancelled.

Request — 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"
    }
  }'

Request — 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()

Request — 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);

Response 201

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

GET/api/demos/logistique/v1/payouts

List payouts

Payouts of the cash collected, by bank or postal (CCP) transfer, with the fees withheld and the next payout day.

Possible errors :400 · 401 · 429

Query parameters
Field	Type	Required	Description
`from`	`date`	no	From this date.
`to`	`date`	no	Up to this date.
`state`	`stringscheduledsent`	no	Scheduled or sent.
`page`	`integer`1≥	no	Page number.
`per_page`	`integer`1–100	no	Rows per page.

Response 200
Field	Type	Required	Description
`payouts[]`	`array`	yes	Payouts, newest first.
`payouts[].ref`	`string`	yes	The payout statement.
`payouts[].scheduled_for`	`date`	yes	The day planned.
`payouts[].sent_at`	`datetime`	no	When it was sent.
`payouts[].method`	`stringbankccp`	yes	Bank or CCP transfer.
`payouts[].parcels`	`integer`	yes	Parcels in the payout.
`payouts[].collected`	`integer`	yes	Total collected.
`payouts[].fees`	`integer`	yes	Fees withheld: delivery, collection, options, returns.
`payouts[].net`	`integer`	yes	Amount paid.
`payouts[].state`	`stringscheduledsent`	yes	Scheduled or sent.
`next_payout_day`	`date`	yes	The next payout day.
`next_page`	`integer`	no	The next page, or nothing.

Request — 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

Request — 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()

Request — 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);

Response 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
}

Signed webhooks

Register an address in the seller space and pick the events. Every delivery carries a signature you check before trusting its content.

Events

`shipment.status_changed`

A parcel changes state: picked up, at the hub, out for delivery, delivered, recipient absent, refused, returned.

Event payload

{
  "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`

The courier collected the amount at the door, in full or in part.

Event payload

{
  "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`

A payout left for your bank or CCP account.

Event payload

{
  "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"
  }
}

Checking a signature

The X-Khatt-Signature header holds t= (the send time in seconds) and v1= (the hex HMAC-SHA256 of t, a dot and the raw body, keyed with the address’s secret). Recompute it, compare in constant time and refuse anything older than five minutes.

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

Verification in 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))
}

Verification in 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']);
}

Answer with a 2xx within ten seconds. Otherwise the delivery is retried after 1 min, 5 min, 30 min, 2 h and 6 h, then marked failed in the log.
The « Send a test » button in the seller space (or POST /webhooks/test) produces a sample of every event.

Limits and errors

At most 300 requests an hour per key. The X-RateLimit-Remaining and X-RateLimit-Reset headers tell you where you stand; beyond it the answer is 429 with Retry-After.
A bulk call counts as one request and takes at most 500 parcels. Lists are paged by 100 rows at most.
An error always has the same shape: a stable code, a readable message and, for a field, its path and reason.

422

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

HTTP	code	Description
400	`invalid_request`	Unreadable request: invalid JSON or a missing parameter.
401	`unauthorized`	Key missing, unknown or revoked.
403	`forbidden`	The key has no access to this resource.
404	`not_found`	No parcel or payout with that number for this account.
409	`conflict`	`Idempotency-Key` already used with a different body.
413	`too_large`	A bulk call of more than 500 parcels.
422	`unprocessable`	Valid but refused: unknown wilaya, a commune from another wilaya, weight out of bounds.
429	`rate_limited`	Too many requests: wait for the time given.
500	`internal`	Our error: retry with the same `Idempotency-Key`.

For online shops

No API to write: a module puts the rate in the basket, creates the shipment when the order is confirmed and updates the order at every step.

Shops on open-source CMSs
A module installed from the shop’s admin: the rate by wilaya in the basket, home or stop-desk, the label straight from the order.
Demonstration
Hosted shops
An app you connect in two clicks with your key: orders land in the seller space, ready to confirm and label.
Demonstration
Marketplaces
A connector that reads orders from the marketplaces you sell on and sends the tracking number back to the buyer.
Demonstration
Selling by message
Selling in direct messages? Paste the order into the seller space: the address and amount are recognised, and you confirm every field.
Demonstration

CSV and Excel import

To send a day of orders in one go, without the API: one file, one row per parcel, up to 500 rows.

Recognised columns

Order does not matter, and Arabic or English headers are recognised too. Name, phone, wilaya, commune and amount are required.

Each row is checked on import: a commune that is not in its wilaya is flagged with the nearby communes, and a blank weight counts as 1 kg.

In the demonstration the names and numbers in the file are replaced with demo values on import. The template’s numbers are masked.

Download the template (CSV)

Column	Required
`Nom`	yes
`Téléphone`	yes
`Wilaya`	yes
`Commune`	yes
`Adresse`	no
`Poids`	no
`Montant`	yes
`Produit`	no
`Remarque`	no
`Quantité`	no
`Mode`	no

Start in three calls

Endpoints

Signed webhooks

Events

shipment.status_changed

cod.collected

payout.sent

Checking a signature

Limits and errors

For online shops

Shops on open-source CMSs

Hosted shops

Marketplaces

Selling by message

CSV and Excel import

Recognised columns

`shipment.status_changed`

`cod.collected`

`payout.sent`