Connect your platform
to your customers’ stores

POST https://elmatajer.com/oauth/token
Content-Type: application/json

{
  "grant_type":    "authorization_code",
  "client_id":     "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code":          "THE_CODE_FROM_THE_REDIRECT",
  "redirect_uri":  "https://your-app.com/callback",
  "code_verifier": "THE_ORIGINAL_VERIFIER"
}

→ 200 OK
{
  "access_token":   "17|xxxxxxxxxxxxxxxx",
  "token_type":     "Bearer",
  "scope":          "orders.read orders.write webhooks",
  "store":          { "vendor_id": 42, "name": "..." },
  "webhook_secret": "store this — it signs your webhooks",
  "api_base":       "https://elmatajer.com/api/v1/vendor"
}

→ 401 { "error": "invalid_client" }   wrong client_id / client_secret, or the app is not approved
→ 400 { "error": "invalid_grant", "error_description": "code_expired" }
       error_description: code_expired · code_already_used · redirect_uri_mismatch · invalid_code_verifier

GET https://elmatajer.com/api/v1/vendor/orders
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

→ 200 OK
{
  "status": "ok",
  "data": [ {
    "id": 1042, "order_number": "AB1234",
    "status": 1, "status_type": 1, "status_label": "...",
    "payment_status": 1, "payment_type": "cod",
    "customer": { "name": "...", "email": "...", "mobile": "..." },
    "totals": { "sub_total": 1200, "delivery_charge": 50, "discount_amount": 0,
                "grand_total": 1250, "currency": "...", "currency_code": "EGP" },
    "items": [ ... ], "created_at": "2026-10-08T12:00:00+03:00"
  } ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 20, "total": 52, "has_more": true }
}

→ 403 if the merchant did not grant that scope
{ "code": "insufficient_scope", "required_scope": "orders.read" }

POST https://your-app.com/webhook
X-Elmatajer-Event: order.created
X-Elmatajer-Event-Id: 9f1c...            // use it to de-duplicate
X-Elmatajer-Signature: sha256=<hmac>

{ "event": "order.created", "event_id": "9f1c...", "vendor_id": 42,
  "created_at": "2026-10-08T12:00:00+03:00", "data": { ... } }

// Verify before trusting anything — PHP
$expected = hash_hmac('sha256', $rawBody, $webhookSecret);
if (!hash_equals($expected, str_replace('sha256=', '', $header))) abort(401);

// 1 — receive the merchant's credentials (your callback_url)
POST /elmatajer/callback

$body = json_decode(file_get_contents('php://input'), true);

saveStore([
    'store_id'       => $body['store_id'],        // unique per merchant
    'api_key'        => $body['api_key'],         // use as Bearer token
    'webhook_secret' => $body['webhook_secret'],  // verifies their events
]);

http_response_code(200);  // answer 2xx or we treat it as failed


// 2 — call the API for that store
$res = $http->get('https://elmatajer.com/api/v1/vendor/orders', [
    'headers' => [
        'Authorization' => 'Bearer ' . $store['api_key'],
        'Accept'        => 'application/json',
    ],
]);
// no store_id in the request — the token already identifies the store


// 3 — receive events (your webhook_url)
POST /elmatajer/webhook

$raw = file_get_contents('php://input');
$sig = str_replace('sha256=', '', $_SERVER['HTTP_X_ELMATAJER_SIGNATURE'] ?? '');

$store = findStoreById(json_decode($raw, true)['vendor_id']);

// VERIFY FIRST — never trust the body before this passes
if (!hash_equals(hash_hmac('sha256', $raw, $store['webhook_secret']), $sig)) {
    http_response_code(401); exit;
}

$event = json_decode($raw, true);

// de-duplicate: retries resend the same event_id
if (alreadyHandled($_SERVER['HTTP_X_ELMATAJER_EVENT_ID'])) { http_response_code(200); exit; }

match ($event['event']) {
    'order.created'        => onNewOrder($event['data']),
    'order.status_changed' => onStatusChange($event['data']),
    default                => null,
};

http_response_code(200);