المصادقة
كل نقطة نهاية عدا POST /auth/login و POST /auth/refresh تحتاج اعتماداً، وتُرسل إحدى طريقتين مع كل طلب. تصلان إلى نقاط النهاية نفسها؛ الفرق في من تكون وما المسموح لك به.
أرسل نوعاً واحداً فقط في كل طلب. الطلب الذي يحمل ترويسة
Authorization: BearerوترويسةX-API-Keyمعاً يُرفض بـ400 ambiguous_credentials. وغالباً يعني أن وسيطاً أو عميل HTTP يضيف ترويسة لم تقصدها.
يُنشئ مدير الشركة المفتاح من لوحة التحكم (تفعيل الواجهة). ترسل ترويستين مع كل طلب:
| الترويسة | القيمة |
|---|---|
X-API-Key |
المفتاح، ويبدأ بـ lmc_live_ |
X-API-Secret |
السر الذي ظهر مرة واحدة عند إنشاء المفتاح |
curl "https://api.goldrock.live/api/public/v1/auth/me" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/auth/me", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/me';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/auth/me",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())- الترويستان مطلوبتان معاً. المفتاح بلا سر يرد بـ
401 unauthorized، وكذلك السر الخاطئ أو المفتاح الملغى أو المنتهي. وتوضح الرسالة السبب. - ما يستطيع المفتاح فعله تحدده نطاقاته (Scopes). استدعاء ما هو خارجها يرد بـ
403 forbiddenومعهdetails.requiredScope. - الطلبات محدودة المعدل لكل مفتاح، راجع الاصطلاحات.
- حالة الشركة (موقوفة أو منتهية) تُفحص مع كل طلب: مفتاح أو رمز صالح لشركة محجوبة يرد بـ
403 tenant_blockedحتى تُعاد الشركة إلى العمل. - المفتاح يعرّف تكاملاً لا شخصاً. يعمل باسم الشركة، ولأي تاجر من تجارها.
يسجّل مستخدم لوحة التحكم الدخول فيحصل على زوج رموز. ومنه حساب التاجر: مستخدم يتبع تاجراً واحداً من تجار شركتك.
curl -X POST "https://api.goldrock.live/api/public/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "ahmed@your-company.example",
"password": "YOUR_PASSWORD"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/auth/login", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
"username": "ahmed@your-company.example",
"password": "YOUR_PASSWORD"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/login';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'username' => 'ahmed@your-company.example',
'password' => 'YOUR_PASSWORD',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/auth/login",
json={
"username": "ahmed@your-company.example",
"password": "YOUR_PASSWORD",
},
timeout=30,
)
print(response.status_code, response.json()){
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "q3kZ0m8w...",
"tokenType": "Bearer",
"expiresIn": 900
}accessTokenرمز JWT. أرسله بالشكلAuthorization: Bearer <accessToken>حتى تمرexpiresInثانية.refreshTokenيُستخدم مرة واحدة. عند استخدامه تحصل على زوج جديد ويتوقف القديم عن العمل. احفظ الجديد دائماً.usernameاسم مستخدم لوحة التحكم أو بريده الإلكتروني.- ما يستطيع المستخدم فعله تحدده صلاحياته في لوحة التحكم. ويعرض
GET /auth/meالنطاقات التي تغطيها تلك الصلاحيات. - في عمليات كتابة الشحنات تُفحص الصلاحية بالضبط:
POST /shipmentsيحتاجorders:create، وPUT /shipments/{trackingNumber}يحتاجorders:update، وPOST /shipments/{trackingNumber}/cancelيحتاجorders:cancel. لا تكفي صلاحية أخرى من المجال نفسه، والرد403 forbidden. أما مفتاح الـ API فمختلف: نطاقه وحده يقرر (shipments:writeيشمل الثلاثة).
curl "https://api.goldrock.live/api/public/v1/auth/me" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"const response = await fetch("https://api.goldrock.live/api/public/v1/auth/me", {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/me';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_ACCESS_TOKEN',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/auth/me",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
},
timeout=30,
)
print(response.status_code, response.json()){
"authMethod": "password",
"company": {
"id": "0f8fad5b-d9cb-469f-a165-70867728950e",
"name": "Fast Express",
"slug": "fast-express"
},
"user": {
"id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"name": "Ahmed Ali"
},
"apiKey": null,
"scopes": [
"geography:read",
"merchants:read",
"pricing:read",
"shipments:read"
],
"permissions": [
"merchants:view",
"orders:read"
]
}حين يقترب رمز الوصول من الانتهاء (أو يرد طلب بـ 401)، بدّل رمز التجديد. نفّذ ذلك على خادمك وبشكل متسلسل: إن جدّد طلبان بالرمز نفسه في اللحظة نفسها فينجح أحدهما فقط.
curl -X POST "https://api.goldrock.live/api/public/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "YOUR_REFRESH_TOKEN"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/auth/refresh", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
"refreshToken": "YOUR_REFRESH_TOKEN"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/refresh';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'refreshToken' => 'YOUR_REFRESH_TOKEN',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/auth/refresh",
json={
"refreshToken": "YOUR_REFRESH_TOKEN",
},
timeout=30,
)
print(response.status_code, response.json())إن رُفض رمز التجديد (401 auth.invalid_refresh_token) فقد انتهت الجلسة: اطلب من المستخدم تسجيل الدخول من جديد.
// Server-side token manager for the password login (Node.js 18+).
// Keeps one session, refreshes it shortly before it expires, and never refreshes twice at the same time.
const API = `${process.env.LASTMILE_API_URL}/api/public/v1`;
let session = null; // { accessToken, refreshToken, expiresAt }
let inflight = null; // the refresh or login that is currently running
async function post(path, body) {
const response = await fetch(`${API}${path}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const data = await response.json();
if (!response.ok) throw Object.assign(new Error(data.message), { code: data.code, status: response.status });
return data;
}
function store(tokens) {
// Refresh one minute early. The refresh token is single use: always keep the new one.
session = {
accessToken: tokens.accessToken,
refreshToken: tokens.refreshToken,
expiresAt: Date.now() + (tokens.expiresIn - 60) * 1000,
};
return session.accessToken;
}
async function signIn() {
return store(await post("/auth/login", { username: process.env.LASTMILE_USER, password: process.env.LASTMILE_PASSWORD }));
}
export async function getAccessToken() {
if (session && Date.now() < session.expiresAt) return session.accessToken;
inflight ??= (async () => {
try {
if (session) {
try {
return store(await post("/auth/refresh", { refreshToken: session.refreshToken }));
} catch (error) {
if (error.status !== 401) throw error; // the session is over: sign in again below
}
}
return await signIn();
} finally {
inflight = null;
}
})();
return inflight;
}
export async function lastmile(path, options = {}) {
const token = await getAccessToken();
return fetch(`${API}${path}`, {
...options,
headers: { ...options.headers, Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
});
}حساب التاجر لا يرى ولا يحجز إلا شحنات تاجره هو، ويقرأ سجل تاجره وعناوينه، ويعرض الأسعار. لا يستطيع تعديل الشحنات أو إلغاءها ولا إدارة التجار ولا قراءة تجار آخرين: هذه ترد بـ 403 أو 404. وحين ينشئ شحنة فهو يرسلها دائماً باسم تاجره، ولا يمكنه استخدام مرسل مخصص. لهذا هو الأداة المناسبة لبوابة التجار.
محاولات الدخول الفاشلة تُحسب ضمن قفل الحساب وتحديد المعدل لكل شبكة كما في لوحة التحكم. التكرار يرد بـ 429 auth.login_temporarily_blocked أو 403 auth.account_locked. الحد لـ login هو 30 طلباً في الدقيقة لكل عنوان IP، ولـ refresh عشرة. ويجب أن تكون قناة الـ API مفعّلة للشركة وإلا رد الدخول بـ 403 channel_disabled ولا يصدر أي رمز.
| ما تبنيه | الأنسب |
|---|---|
| موقع شركة أو متجر يتتبع الشحنات ويسعّرها ويحجزها | مفتاح API من خادمك |
| تكامل داخلي أو سكربت أو أتمتة جدول بيانات | مفتاح API |
| بوابة يرى فيها كل تاجر شحناته فقط | تسجيل الدخول بحسابات التجار |
| شيء يجب أن يعمل باسم مستخدم محدد في لوحة التحكم | تسجيل الدخول |
القاعدة: إن لم يكتب إنسان بيانات الاعتماد في نظامك فاستخدم مفتاحاً. وإن كتبها إنسان وتريد أن تقرر المنصة ما يراه فاستخدم تسجيل الدخول.
- لا تضع المفتاح أو السر في شيفرة المتصفح أو الجوال أبداً. أي شيء يُشحن إلى جهاز يمكن قراءته. استدعِ الـ API من خادمك ودع المتصفح يستدعي خادمك. يعرض شرح بناء الموقع النمط كاملاً. كما أن استدعاءات المتصفح للـ API تخضع لـ CORS، وهذا سبب آخر للمرور عبر خادم.
- مفتاح لكل تكامل. سمِّه باسم ما يستخدمه. بذلك تلغي واحداً دون كسر الباقي، وتعرف أي تكامل يستدعي.
- أقل نطاقات ممكنة. صفحة التتبع تحتاج
shipments:readفقط. وحاسبة الأسعار تحتاجpricing:readوgeography:read. لا تحدد كل شيء. - خزّن الأسرار كأسرار. متغيرات بيئة أو مدير أسرار، لا مستودع الشيفرة ولا السجلات ولا تذاكر الدعم. أخفِها في السجلات.
- دوّر وألغِ. ضع تاريخ انتهاء للمفاتيح متى أمكن، وأنشئ بديلاً قبل انتهاء القديم، وألغِ أي مفتاح قد يكون تسرّب. المفتاح الملغى يتوقف فوراً.
- لا تخزّن كلمات المرور. احتفظ برموز التجديد في جلسة مشفرة على الخادم لا في
localStorage. - تحقق من الـ Webhooks. افحص توقيع كل إرسال، راجع الـ Webhooks.