Partnyor API
Yükü, pulu və sifarişləri Sadarakdan keçirin
Versiyalanmış REST API (/v1) və mənbə kimi OpenAPI: sizə təyin olunmuş sifarişləri oxuyun, çatdırılma hadisələrini bildirin və imzalanmış vebhuklar alın. Çatdırılma zamanı nağd ödəniş tam hüquqlu üsuldur və bütün məbləğlər tam ədəd qəpikdir.
Partnyor API nə verir
Sifarişlərin oxunması
Sizə təyin olunmuş sifarişləri məhsullar, vaxt aralığı, zona, nağd məbləğ və tam status xronologiyası ilə alın. Müştərinin adı, telefonu və ünvanı yalnız orders:pii scope-u ilə gəlir.
Logistika hadisələri
PICKED_UP, EN_ROUTE, DELIVERED və FAILED hadisələrini bizə bildirin. Hubda PACKED sifarişi təhvil alırsınız; hər hadisə sifariş vəziyyət maşınından keçir, ona görə mümkün olmayan keçid sifarişi pozmaq əvəzinə rədd edilir.
Vebhuklar
order.placed, order.status_changed, order.delivered, order.cancelled, batch.completed və order.assigned_to_partner — hər biri HMAC-SHA256 ilə imzalanır və 12 saata qədər geri çəkilmə ilə təkrarlanır.
Sandbox
Öz seed bazası və öz açarları olan ikinci API. Sandbox açarı heç vaxt canlı məlumatlarda, canlı açar isə heç vaxt sandbox-da işləmir.
Baza URL-lər
https://api.turanyol.comhttp://localhost:3050Açarlar bir mühitə bağlıdır. Canlı API-yə göndərilən sandbox açarı ERR_API_KEY_ENVIRONMENT ilə rədd edilir.
Sürətli başlanğıc
İki şeyi düzgün edin: hər sorğuda açarı göndərin və hər vebhukda imzanı yoxlayın.
1. Sorğunu autentifikasiya edin
Açarınızı X-Api-Key başlığında göndərin. OAuth mərhələsi və bearer token yoxdur — açar özü etimadnamədir, ona görə onu serverdə saxlayın.
curl -sS "https://api.turanyol.com/v1/partner/orders?status=EN_ROUTE&page=1" \
-H "X-Api-Key: $ESADARAK_API_KEY" \
-H "Accept: application/json"2. Çatdırılma hadisəsi bildirin
logistics:write scope-u və sizə təyin olunmuş sifariş tələb olunur. Pul tam ədəd qəpikdir: 4750 = 47,50 ₼.
curl -sS -X POST "https://api.turanyol.com/v1/partner/orders/ES-1042/events" \
-H "X-Api-Key: $ESADARAK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"DELIVERED","codCollectedQepik":4750}'3. Vebhuk imzasını yoxlayın
Timestamp, nöqtə və xam sorğu gövdəsi üzərində HMAC-SHA256. Sabit vaxtda müqayisə edin və beş dəqiqədən köhnə olanı rədd edin.
import crypto from "node:crypto";
const SECRET = process.env.ESADARAK_WEBHOOK_SECRET;
const TOLERANCE_SEC = 300;
/** rawBody MUST be the exact bytes we sent (express: express.raw({ type: "application/json" })). */
export function verify(rawBody, signatureHeader) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.trim().split("=", 2)),
);
const t = Number(parts.t);
if (!Number.isInteger(t)) return false;
if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SEC) return false; // replay window
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${t}.${rawBody}`)
.digest("hex");
const received = Buffer.from(parts.v1 ?? "", "hex");
const digest = Buffer.from(expected, "hex");
return received.length === digest.length && crypto.timingSafeEqual(received, digest);
}Qaydalar
- Bütün məbləğlər tam ədəd qəpikdir (AZN kiçik vahidi) və sahə adı Qepik ilə bitir. Heç vaxt float deyil.
- Xətalar sabit kodlu (ERR_*) JSON-dur və heç vaxt tərcümə olunmur — kodu öz mətnlərinizə uyğunlaşdırın.
- Məhsul və kateqoriya adları az, ru və en sahələri olan obyektdir. Dili UI tərəfində seçin.
- Telefon nömrələri E.164 (+994XXXXXXXXX), tarixlər ISO-8601 UTC, id-lər UUID, kodlar ES-1042 / B-2081 formatındadır.
- Siyahı endpointləri items massivi ilə birlikdə page, pageSize və total qaytarır və pageSize-ı 50 ilə məhdudlaşdırır.
Növbəti addımlar
Açarlar yaradılarkən bir dəfə göstərilir. Rotasiya zamanı köhnə açar 24 saat işləməyə davam edir ki, fasiləsiz deploy edə biləsiniz.
Hər açar üçün beşə qədər endpoint, hər birinin öz sirri və təkrar göndərə biləcəyiniz tam çatdırılma jurnalı var.
API-nin qaytara biləcəyi bütün ERR_* kodları, sahələr üzrə qruplaşdırılıb.
{
"statusCode": 403,
"code": "ERR_API_KEY_SCOPE",
"message": "key is missing scope logistics:write",
"details": { "required": "logistics:write" }
}