Intégrations

Branchez votre boutique sur le réseau

Une API REST en JSON pour créer des expéditions, suivre chaque colis, demander un ramassage et lire vos reversements ; des webhooks signés pour être prévenu ; des modules pour les boutiques en ligne ; un modèle d’import pour tout le reste.

Créer une clé de test Télécharger le modèle d’import

Démarrer en trois appels

Tout passe par l’adresse de test ci-dessous, en JSON encodé en UTF-8. Les montants sont des dinars entiers, les dates suivent l’heure d’Alger.

Adresse de base: https://algeriaagency.com/api/demos/logistique/v1
Authentification: Chaque requête porte votre clé dans l’en-tête X-Api-Key. Une clé se crée dans l’espace vendeur, rubrique API ; elle commence par kh_test_ et elle est affichée une seule fois.X-Api-Key: kh_test_••••••••••••••••••••7Q2m
Requêtes rejouables: Ajoutez un en-tête Idempotency-Key à chaque POST : la même clé renvoyée dans les 24 heures rend la même réponse, sans créer un second colis. Le même en-tête avec un autre contenu est refusé en 409.
Ce que fait le bac à sable: Dans la démonstration, chaque destinataire est remplacé à la réception par un destinataire démo au numéro masqué, et seul un condensé du numéro est conservé. Les webhooks sont inscrits dans le journal de votre espace, jamais envoyés vers l’extérieur. Tout est effacé après 24 heures.

Créez une clé de test dans l’espace vendeur.
Demandez un prix avec GET /tariffs/quote pour afficher la livraison dans votre panier.
Créez l’expédition avec POST /shipments quand la commande est validée, puis imprimez l’étiquette.
Écoutez shipment.status_changed pour mettre à jour la commande sans interroger l’API.

Points d’entrée

Six points d’entrée couvrent le parcours d’une commande, du prix affiché au panier jusqu’à l’argent reversé.

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

POST/api/demos/logistique/v1/shipments

Créer une expédition

Enregistre un colis, calcule son prix, sa fenêtre de livraison et son risque de refus, et renvoie le numéro de suivi et l’étiquette.

Accepte Idempotency-KeyErreurs possibles :400 · 401 · 409 · 422 · 429

Corps de la requête
Champ	Type	Obligatoire	Description
`reference`	`string`≤ 40	non	Votre numéro de commande, rendu tel quel.
`recipient`	`object`	oui	Le destinataire.
`recipient.name`	`string`2–80	oui	Son nom. Remplacé par un nom démo dans le bac à sable.
`recipient.phone`	`string`	oui	Un mobile algérien. Masqué et remplacé dans le bac à sable ; seul un condensé est gardé.
`destination`	`object`	oui	Où livrer.
`destination.wilaya`	`integer`1–69	oui	Code de la wilaya, de 1 à 69.
`destination.commune`	`string`2–60	oui	Commune de cette wilaya : son identifiant ou son nom, en arabe, en français ou en latin.
`destination.landmark`	`string`≤ 160	non	Un repère plutôt qu’une adresse : « en face de la mosquée », « derrière la poste ».
`mode`	`stringhomestop-desk`	oui	`home` (à domicile) ou `stop-desk` (retrait en agence).
`agency`	`string`	non	L’agence de retrait pour un stop-desk, par défaut celle de la wilaya.
`weight_kg`	`number`0.05–70	oui	Poids en kilogrammes.
`dimensions_cm`	`object`	non	Dimensions en centimètres, pour le poids volumétrique.
`dimensions_cm.length`	`integer`1–300	oui	Longueur.
`dimensions_cm.width`	`integer`1–300	oui	Largeur.
`dimensions_cm.height`	`integer`1–300	oui	Hauteur.
`cod_amount`	`integer`0–1000000	oui	Montant à encaisser à la porte, en dinars ; 0 pour un colis prépayé.
`declared_value`	`integer`0–5000000	non	Valeur déclarée pour l’assurance ; par défaut le montant encaissé.
`product`	`string`2–120	oui	Ce que contient le colis, en quelques mots.
`quantity`	`integer`1–99	non	Nombre d’articles.
`options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	non	Options : assurance, fragile, échange, confirmation, ouverture avant paiement, express.
`note`	`string`≤ 200	non	Une consigne pour le livreur.

Réponse 201
Champ	Type	Obligatoire	Description
`tracking_number`	`string`	oui	Numéro de suivi : `KH` et dix chiffres, le dernier étant une clé de contrôle.
`reference`	`string`	non	Votre numéro de commande, rendu tel quel.
`state`	`string` Valeurs (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	oui	L’état du colis.
`price`	`object`	oui	Le prix de l’envoi.
`price.ht`	`integer`	oui	Hors taxes.
`price.tva`	`integer`	oui	TVA.
`price.ttc`	`integer`	oui	Toutes taxes comprises.
`price.lines[]`	`array`	oui	Le détail, ligne par ligne.
`price.lines[].key`	`string`	oui	La nature de la ligne : transport, frais d’encaissement, option…
`price.lines[].amount`	`integer`	oui	Son montant TTC.
`price.indicative`	`boolean`	oui	Toujours vrai : le tarif est indicatif.
`sla`	`object`	oui	La fenêtre de livraison promise, en heures après le ramassage.
`sla.min_hours`	`integer`	oui	Au plus tôt.
`sla.max_hours`	`integer`	oui	Au plus tard.
`risk`	`object`	oui	Le risque de refus estimé, avec ses raisons dans l’espace vendeur.
`risk.score`	`integer`0–100	oui	De 0 à 100.
`risk.band`	`stringlowmediumhigh`	oui	Faible, moyen ou élevé.
`label_url`	`string`	oui	L’étiquette 10 × 15 en PDF (spécimen dans la démonstration).
`tracking_url`	`string`	oui	La page de suivi à envoyer au client.
`created_at`	`datetime`	oui	Date de création.

Requête — 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"
    ]
  }'

Requête — 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()

Requête — 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);

Réponse 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}

Lire une expédition

L’état d’un colis, ses étapes, son encaissement et, en cours de livraison, sa fenêtre d’arrivée.

Erreurs possibles :401 · 404 · 429

Paramètre dans le chemin
Champ	Type	Obligatoire	Description
`tracking`	`string`	oui	Numéro de suivi : `KH` et dix chiffres, le dernier étant une clé de contrôle.

Réponse 200
Champ	Type	Obligatoire	Description
`tracking_number`	`string`	oui	Numéro de suivi : `KH` et dix chiffres, le dernier étant une clé de contrôle.
`state`	`string` Valeurs (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	oui	L’état du colis.
`mode`	`stringhomestop-desk`	oui	`home` (à domicile) ou `stop-desk` (retrait en agence).
`destination`	`object`	oui	Où livrer.
`destination.wilaya`	`integer`1–69	oui	Code de la wilaya, de 1 à 69.
`destination.commune`	`string`2–60	oui	Commune de cette wilaya : son identifiant ou son nom, en arabe, en français ou en latin.
`cod_amount`	`integer`	oui	Montant à encaisser à la porte, en dinars ; 0 pour un colis prépayé.
`cod_state`	`string` Valeurs (8) `pendingcollectedin-transit-to-hubreconciledpaid-outpartialdisputedrefunded`	oui	Où en est l’argent encaissé.
`attempts`	`integer`0–3	oui	Tentatives de livraison, trois au plus.
`eta`	`object`	non	La fenêtre d’arrivée, une fois le colis en livraison.
`eta.earliest`	`datetime`	oui	Début de la fenêtre.
`eta.latest`	`datetime`	oui	Fin de la fenêtre.
`events[]`	`array`	oui	Les étapes, de la plus ancienne à la plus récente.
`events[].state`	`string` Valeurs (19) `pending-confirmationconfirmedawaiting-pickuppicked-upat-origin-hubin-line-haulat-destination-hubout-for-deliverydeliveredattempt-failedrescheduledat-stop-deskcollected-from-stop-deskrefusedreturn-in-transitreturnedexchangelostcancelled`	oui	L’état du colis.
`events[].at`	`datetime`	oui	Heure de l’étape.
`events[].place`	`string`	oui	Lieu : commune, code du hub ou agence.
`events[].reason`	`stringabsentrefusedwrong-addressunreachablerescheduled`	non	Pour un échec, la raison.

Requête — curl

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

Requête — 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()

Requête — 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);

Réponse 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

Créer des expéditions en lot

Jusqu’à 500 colis par appel. Les lignes valides sont créées, les autres reviennent avec la raison et, pour un lieu, des suggestions.

Accepte Idempotency-KeyErreurs possibles :400 · 401 · 409 · 413 · 429

Corps de la requête
Champ	Type	Obligatoire	Description
`shipments[]`	`array`1–500	oui	Les colis, au même format qu’une expédition seule.
`shipments[].reference`	`string`≤ 40	non	Votre numéro de commande, rendu tel quel.
`shipments[].recipient`	`object`	oui	Le destinataire.
`shipments[].recipient.name`	`string`2–80	oui	Son nom. Remplacé par un nom démo dans le bac à sable.
`shipments[].recipient.phone`	`string`	oui	Un mobile algérien. Masqué et remplacé dans le bac à sable ; seul un condensé est gardé.
`shipments[].destination`	`object`	oui	Où livrer.
`shipments[].destination.wilaya`	`integer`1–69	oui	Code de la wilaya, de 1 à 69.
`shipments[].destination.commune`	`string`2–60	oui	Commune de cette wilaya : son identifiant ou son nom, en arabe, en français ou en latin.
`shipments[].destination.landmark`	`string`≤ 160	non	Un repère plutôt qu’une adresse : « en face de la mosquée », « derrière la poste ».
`shipments[].mode`	`stringhomestop-desk`	oui	`home` (à domicile) ou `stop-desk` (retrait en agence).
`shipments[].agency`	`string`	non	L’agence de retrait pour un stop-desk, par défaut celle de la wilaya.
`shipments[].weight_kg`	`number`0.05–70	oui	Poids en kilogrammes.
`shipments[].dimensions_cm`	`object`	non	Dimensions en centimètres, pour le poids volumétrique.
`shipments[].dimensions_cm.length`	`integer`1–300	oui	Longueur.
`shipments[].dimensions_cm.width`	`integer`1–300	oui	Largeur.
`shipments[].dimensions_cm.height`	`integer`1–300	oui	Hauteur.
`shipments[].cod_amount`	`integer`0–1000000	oui	Montant à encaisser à la porte, en dinars ; 0 pour un colis prépayé.
`shipments[].declared_value`	`integer`0–5000000	non	Valeur déclarée pour l’assurance ; par défaut le montant encaissé.
`shipments[].product`	`string`2–120	oui	Ce que contient le colis, en quelques mots.
`shipments[].quantity`	`integer`1–99	non	Nombre d’articles.
`shipments[].options`	`array`≤ 6`insurancefragileexchangeconfirmationopen-on-deliveryexpress`	non	Options : assurance, fragile, échange, confirmation, ouverture avant paiement, express.
`shipments[].note`	`string`≤ 200	non	Une consigne pour le livreur.

Réponse 200
Champ	Type	Obligatoire	Description
`accepted[]`	`array`	oui	Les lignes créées.
`accepted[].index`	`integer`	oui	Position de la ligne dans le lot, à partir de 0.
`accepted[].tracking_number`	`string`	oui	Numéro de suivi : `KH` et dix chiffres, le dernier étant une clé de contrôle.
`rejected[]`	`array`	oui	Les lignes refusées.
`rejected[].index`	`integer`	oui	Position de la ligne dans le lot, à partir de 0.
`rejected[].errors[]`	`array`	oui	Ce qui ne va pas.
`rejected[].errors[].path`	`string`	oui	Le champ en cause.
`rejected[].errors[].code`	`string`	oui	Un code stable.
`rejected[].errors[].suggestions`	`array`	non	Pour un lieu, les noms les plus proches.

Requête — 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"
        ]
      }
    ]
  }'

Requête — 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()

Requête — 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);

Réponse 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

Calculer un tarif

Le prix toutes taxes et la fenêtre de livraison entre deux wilayas, avec les options. Le tarif est indicatif et suit la grille de la direction.

Erreurs possibles :400 · 401 · 422 · 429

Paramètres de la requête
Champ	Type	Obligatoire	Description
`from_wilaya`	`integer`1–69	oui	Wilaya de départ.
`to_wilaya`	`integer`1–69	oui	Wilaya d’arrivée.
`to_commune`	`string`	non	Commune d’arrivée, pour distinguer la même ville.
`weight_kg`	`number`0.05–70	oui	Poids en kilogrammes.
`mode`	`stringhomestop-desk`	oui	`home` (à domicile) ou `stop-desk` (retrait en agence).
`cod_amount`	`integer`0≥	non	Montant à encaisser à la porte, en dinars ; 0 pour un colis prépayé.
`options`	`string`	non	Les mêmes options, séparées par des virgules.

Réponse 200
Champ	Type	Obligatoire	Description
`band`	`string`	oui	La bande tarifaire : même ville, même wilaya ou paire de zones.
`price`	`object`	oui	Le prix de l’envoi.
`price.ht`	`integer`	oui	Hors taxes.
`price.tva`	`integer`	oui	TVA.
`price.ttc`	`integer`	oui	Toutes taxes comprises.
`price.lines[]`	`array`	oui	Le détail, ligne par ligne.
`price.lines[].key`	`string`	oui	La nature de la ligne : transport, frais d’encaissement, option…
`price.lines[].amount`	`integer`	oui	Son montant TTC.
`price.indicative`	`boolean`	oui	Toujours vrai : le tarif est indicatif.
`sla`	`object`	oui	La fenêtre de livraison promise, en heures après le ramassage.
`sla.min_hours`	`integer`	oui	Au plus tôt.
`sla.max_hours`	`integer`	oui	Au plus tard.
`unavailable`	`array`	oui	Les options demandées qui ne sont pas proposées sur ce trajet.

Requête — 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

Requête — 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()

Requête — 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);

Réponse 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

Demander un ramassage

Un livreur passe chez vous le jour ouvré choisi, le matin ou l’après-midi. Après 14 h, le ramassage du jour même n’est plus garanti.

Accepte Idempotency-KeyErreurs possibles :400 · 401 · 409 · 422 · 429

Corps de la requête
Champ	Type	Obligatoire	Description
`date`	`date`	oui	Un jour ouvré : ni vendredi ni jour férié.
`slot`	`stringmorningafternoon`	oui	Matin ou après-midi.
`parcels`	`integer`1–500	oui	Combien de colis attendent.
`tracking_numbers`	`array`≤ 500	non	Les numéros concernés, si vous les avez.
`location`	`object`	oui	Où passer, avec un repère.
`location.wilaya`	`integer`1–69	oui	Code de la wilaya, de 1 à 69.
`location.commune`	`string`2–60	oui	Commune de cette wilaya : son identifiant ou son nom, en arabe, en français ou en latin.
`location.landmark`	`string`≤ 160	non	Un repère plutôt qu’une adresse : « en face de la mosquée », « derrière la poste ».

Réponse 201
Champ	Type	Obligatoire	Description
`pickup_ref`	`string`	oui	La référence du ramassage.
`date`	`date`	oui	Un jour ouvré : ni vendredi ni jour férié.
`slot`	`stringmorningafternoon`	oui	Matin ou après-midi.
`state`	`stringscheduledcollectedmissedcancelled`	oui	Prévu, effectué, manqué ou annulé.

Requête — 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"
    }
  }'

Requête — 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()

Requête — 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);

Réponse 201

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

GET/api/demos/logistique/v1/payouts

Lister les reversements

Les reversements des encaissements, par virement bancaire ou CCP, avec le détail des frais retenus et le prochain jour de reversement.

Erreurs possibles :400 · 401 · 429

Paramètres de la requête
Champ	Type	Obligatoire	Description
`from`	`date`	non	Depuis cette date.
`to`	`date`	non	Jusqu’à cette date.
`state`	`stringscheduledsent`	non	Prévu ou envoyé.
`page`	`integer`1≥	non	Numéro de page.
`per_page`	`integer`1–100	non	Lignes par page.

Réponse 200
Champ	Type	Obligatoire	Description
`payouts[]`	`array`	oui	Les reversements, du plus récent au plus ancien.
`payouts[].ref`	`string`	oui	Le relevé du reversement.
`payouts[].scheduled_for`	`date`	oui	Jour prévu.
`payouts[].sent_at`	`datetime`	non	Heure d’envoi.
`payouts[].method`	`stringbankccp`	oui	Virement bancaire ou CCP.
`payouts[].parcels`	`integer`	oui	Colis compris dans le reversement.
`payouts[].collected`	`integer`	oui	Total encaissé.
`payouts[].fees`	`integer`	oui	Frais retenus : livraison, encaissement, options, retours.
`payouts[].net`	`integer`	oui	Montant versé.
`payouts[].state`	`stringscheduledsent`	oui	Prévu ou envoyé.
`next_payout_day`	`date`	oui	Le prochain jour de reversement.
`next_page`	`integer`	non	La page suivante, ou rien.

Requête — 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

Requête — 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()

Requête — 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);

Réponse 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
}

Webhooks signés

Déclarez une adresse dans l’espace vendeur et choisissez les événements. Chaque envoi porte une signature que vous vérifiez avant de faire confiance au contenu.

Événements

`shipment.status_changed`

Un colis change d’état : ramassé, au hub, en livraison, livré, absent, refusé, retourné.

Contenu de l’événement

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

Le livreur a encaissé le montant à la porte, en totalité ou en partie.

Contenu de l’événement

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

Un reversement est parti vers votre compte bancaire ou CCP.

Contenu de l’événement

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

Vérifier une signature

L’en-tête X-Khatt-Signature contient t= (l’heure d’envoi en secondes) et v1= (le HMAC-SHA256, en hexadécimal, de t, d’un point et du corps brut, calculé avec le secret de l’adresse). Recalculez-le, comparez en temps constant et refusez un envoi de plus de cinq minutes.

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

Vérification en 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))
}

Vérification en 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']);
}

Répondez par un code 2xx en moins de dix secondes. Sinon l’envoi est retenté après 1 min, 5 min, 30 min, 2 h puis 6 h, et marqué en échec dans le journal.
Le bouton « Envoyer un test » de l’espace vendeur (ou POST /webhooks/test) produit un exemple de chaque événement.

Limites et erreurs

Au plus 300 requêtes par heure et par clé. Les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset disent où vous en êtes ; au-delà, la réponse est 429 avec Retry-After.
Un lot compte pour une requête et prend au plus 500 colis. Une liste est paginée par 100 lignes au plus.
Une erreur a toujours la même forme : un code stable, un message lisible et, pour un champ, son chemin et sa raison.

422

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

HTTP	code	Description
400	`invalid_request`	Requête illisible : JSON invalide ou paramètre manquant.
401	`unauthorized`	Clé absente, inconnue ou révoquée.
403	`forbidden`	La clé n’a pas accès à cette ressource.
404	`not_found`	Aucun colis ou reversement à ce numéro pour ce compte.
409	`conflict`	`Idempotency-Key` déjà utilisée avec un autre contenu.
413	`too_large`	Lot de plus de 500 colis.
422	`unprocessable`	Contenu valide mais refusé : wilaya inconnue, commune d’une autre wilaya, poids hors limites.
429	`rate_limited`	Trop de requêtes : attendez la durée indiquée.
500	`internal`	Erreur de notre côté : réessayez avec la même `Idempotency-Key`.

Pour les boutiques en ligne

Pas d’API à écrire : un module installe le tarif au panier, crée l’expédition à la validation et met la commande à jour à chaque étape.

Boutiques sous CMS open source
Un module à installer depuis l’administration de la boutique : tarif par wilaya au panier, choix domicile ou stop-desk, étiquette depuis la commande.
Démonstration
Boutiques hébergées
Une application à connecter en deux clics avec votre clé : les commandes arrivent dans l’espace vendeur, prêtes à être confirmées et étiquetées.
Démonstration
Places de marché
Un connecteur qui lit les commandes des places de marché où vous vendez et renvoie le numéro de suivi au client final.
Démonstration
Ventes par messages
Vous vendez en messages privés ? Collez la commande dans l’espace vendeur : l’adresse et le montant sont reconnus, vous confirmez chaque champ.
Démonstration

Import CSV et Excel

Pour envoyer une journée de commandes d’un coup, sans API : un fichier, une ligne par colis, jusqu’à 500 lignes.

Colonnes reconnues

L’ordre ne compte pas et les en-têtes en arabe ou en anglais sont reconnus aussi. Le nom, le téléphone, la wilaya, la commune et le montant sont obligatoires.

À l’import, chaque ligne est vérifiée : une commune qui n’est pas dans sa wilaya est signalée avec les communes proches, un poids vide vaut 1 kg.

Dans la démonstration, les noms et les numéros du fichier sont remplacés par des valeurs démo dès l’import. Les numéros du modèle sont masqués.

Télécharger le modèle (CSV)

Nom	Obligatoire
`Nom`	oui
`Téléphone`	oui
`Wilaya`	oui
`Commune`	oui
`Adresse`	non
`Poids`	non
`Montant`	oui
`Produit`	non
`Remarque`	non
`Quantité`	non
`Mode`	non

Démarrer en trois appels

Points d’entrée

Webhooks signés

Événements

shipment.status_changed

cod.collected

payout.sent

Vérifier une signature

Limites et erreurs

Pour les boutiques en ligne

Boutiques sous CMS open source

Boutiques hébergées

Places de marché

Ventes par messages

Import CSV et Excel

Colonnes reconnues

`shipment.status_changed`

`cod.collected`

`payout.sent`