TelDel API للتجار

curl -X POST "https://api.teldel.app/api/merchant/orders" \
  -H "X-Api-Key: tdk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "reference": "WEB-100234",
    "description": "2 x T-shirt",
    "recipient": { "name": "Ahmed Al Balushi", "phone": "91234567" },
    "deliveryAddress": {
      "wilayaCode": "5000",
      "street": "Sohar, Al Hambar, Way 1203, House 7",
      "landmark": "Behind Sohar Hospital"
    },
    "orderAmount": 12.5,
    "cashOnDelivery": true,
    "weight": 1.2,
    "notes": "Call before arriving"
  }'

{
  "code": 201,
  "response": {
    "existing": false,
    "order": {
      "id": "6f1c2a7e-0b8d-4f3e-9a51-2c7d8e9f0a1b",
      "orderNumber": "ORD-2026-0815",
      "reference": "WEB-100234",
      "status": "READY_FOR_DELIVERY",
      "deliveryType": "NATIONAL",
      "isExpress": false,
      "expressFee": null,
      "shippingCompany": { "id": "b2d4…", "name": "Dalilee" },
      "trackingCode": null,
      "trackingUrl": "https://teldel.om/track/ORD-2026-0815",
      "deliveryFee": 2.5,
      "orderAmount": 12.5,
      "amountToCollect": 15,
      "isPaid": false,
      "awaitingRecipient": true,
      "recipientPaymentUrl": "https://teldel.om/order-details/6f1c2a7e-0b8d-4f3e-9a51-2c7d8e9f0a1b?t=Qm9x…",
      "cancelReason": null,
      "createdAt": "2026-10-28T09:12:44.120Z",
      "updatedAt": "2026-10-28T09:12:45.003Z"
    }
  },
  "timestamp": "2026-10-28T09:12:45.010Z"
}

curl "https://api.teldel.app/api/merchant/orders/WEB-100234" \
  -H "X-Api-Key: tdk_your_key"

curl -X POST "https://api.teldel.app/api/merchant/orders/WEB-100234/cancel" \
  -H "X-Api-Key: tdk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer cancelled" }'

{
  "code": 200,
  "response": [
    {
      "id": "0b9a6c2e-4c1f-4b8e-9d0a-1f2e3d4c5b6a",
      "code": "5000",
      "nameAr": "صحار",
      "nameEn": "Sohar",
      "areas": [
        { "id": "4e8f…", "nameAr": "الهمبار", "nameEn": "Al Hambar" }
      ]
    }
  ],
  "timestamp": "2026-10-28T09:00:00.000Z"
}

{
  "code": 200,
  "response": {
    "enabled": true,
    "availableNow": true,
    "startHour": 8,
    "endHour": 22,
    "fee": 1,
    "promise": "Within 3 hours",
    "national": { "enabled": true, "fee": 3, "promise": "Same day" }
  },
  "timestamp": "2026-10-29T09:00:00.000Z"
}

POST /teldel/webhook HTTP/1.1
Content-Type: application/json
User-Agent: TelDel-Webhooks/1
X-TelDel-Event: order.status_changed
X-TelDel-Delivery: 9a0e5c1b-…
X-TelDel-Timestamp: 1761643965
X-TelDel-Signature: sha256=5d41402abc4b2a76b9719d911017c592…

{
  "id": "9a0e5c1b-…",
  "event": "order.status_changed",
  "createdAt": "2026-10-28T10:32:45.000Z",
  "data": {
    "id": "6f1c2a7e-0b8d-4f3e-9a51-2c7d8e9f0a1b",
    "orderNumber": "ORD-2026-0815",
    "reference": "WEB-100234",
    "status": "IN_TRANSIT",
    "trackingCode": "A9658145",
    "…": "same fields as GET /orders/{ref}"
  }
}

// Node.js (Express) - use the raw body, not a re-serialized object
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.TELDEL_WEBHOOK_SECRET; // whsec_...

app.post("/teldel/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-TelDel-Timestamp");
  const signature = req.header("X-TelDel-Signature") ?? "";
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", SECRET).update(`${timestamp}.${req.body}`).digest("hex");

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  // Reject old deliveries (replays)
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  if (!valid || !fresh) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // event.id is unique per delivery - ignore ids you already handled
  // update your order event.data.reference with event.data.status ...
  res.sendStatus(200);
});

<?php
// PHP (Laravel, WooCommerce, plain PHP...)
$secret    = getenv('TELDEL_WEBHOOK_SECRET');
$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TELDEL_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_TELDEL_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (!hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// update your order $event['data']['reference'] with $event['data']['status'] ...
http_response_code(200);

{
  "statusCode": 400,
  "timestamp": "2026-10-28T09:12:45.010Z",
  "path": "/api/merchant/orders",
  "method": "POST",
  "requestId": "c1d2e3…",
  "message": "Unknown wilaya: send a cityId or wilayaCode from the wilayas list.",
  "code": "errors.merchant_api_unknown_wilaya"
}