Autentifikasiya

Partnyor sorğuları istifadəçi tokeni ilə yox, API açarı ilə autentifikasiya olunur. Açar tam etimadnamədir: onu əlində saxlayan sizin adınızdan hərəkət edə bilər, ona görə açar serverinizdə və sirr menecerinizdə olmalıdır — heç vaxt brauzerdə, mobil tətbiqdə və ya git repozitoriyasında yox.

Başlıq

Açarı hər sorğuda X-Api-Key başlığında göndərin. Açarlar esk_live_ və ya esk_sandbox_ prefiksi ilə başlayır və 32 simvolla davam edir, ona görə mühit dərhal görünür.

http

X-Api-Key: esk_live_a1b2c3d4e5f60718293a4b5c6d7e8f90

Açarların yaradılması və saxlanması

Açarları bu portalın API açarları səhifəsində yaradın. Açar mətn şəklində yalnız bir dəfə — yaradılarkən göstərilir: biz yalnız onun SHA-256 heşini saxlayırıq və onu yenidən göstərə bilmirik. İtirsəniz, açarı rotasiya edin.

/keys · 10 max

Rotasiya

Rotasiya dərhal yeni açar verir və köhnəsini 24 saat işlək saxlayır. Yeni açarı bu pəncərə ərzində deploy edin; sonra köhnə açar ERR_API_KEY_REVOKED ilə rədd edilir. Ləğv etmə isə dərhal qüvvəyə minir.

grace = 24 h

Scope-lar

Hər açar bir sıra scope daşıyır. Onlardan kənar sorğu ERR_API_KEY_SCOPE ilə rədd edilir — 404 yox, 403, ona görə çatışmayan icazəni tapılmayan sifarişdən ayıra bilirsiniz.

Scope-lar
scope	Mənası
`orders:read`	Sizə təyin olunmuş sifarişləri oxumaq: məhsullar, məbləğlər, vaxt aralığı, zona və status xronologiyası.
`orders:pii`	Əlavə olaraq müştərinin adı, telefonu və çatdırılma ünvanı. Yalnız real çatdırırsınızsa verin.
`logistics:write`	Öz sifarişlərinizdə çatdırılma hadisələrini (PICKED_UP, EN_ROUTE, DELIVERED, FAILED) bildirmək.
`webhooks:manage`	Bu açar üçün vebhuk endpointləri yaratmaq və redaktə etmək.
`payments:read`	Üzləşdirmə üçün ödəniş niyyətlərini və statuslarını oxumaq.

Mühitlər

Hər açar yalnız bir mühitə aiddir. Canlı API yalnız canlı açarları, sandbox isə yalnız sandbox açarlarını qəbul edir; səhv olanı, açar özü etibarlı olsa da, ERR_API_KEY_ENVIRONMENT ilə rədd edilir.

base urls

live     https://api.turanyol.com
sandbox  http://localhost:3050

Sürət limitləri

Hər açarın dəqiqədə sorğu sayı üzrə öz limiti var və sürüşən pəncərə ilə tətbiq olunur. Limit aşılanda API 429 və ERR_RATE_LIMITED ilə, saniyələrlə Retry-After başlığı verir — dərhal təkrar etmək əvəzinə həmin qədər gözləyin.

http

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "statusCode": 429, "code": "ERR_RATE_LIMITED", "message": "rate limit exceeded" }

İstifadə sayğacları

Hər açar üzrə gündəlik sorğuları, 4xx və 5xx sayını hesablayır və 35 gün saxlayırıq. Rəqəmlər API açarları səhifəsindədir, GET /v1/partner/me isə açarınızın scope-larını, sürət limitini və son yeddi günün trafikini qaytarır.

İlk sorğu

bash

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"

Nə səhv gedə bilər

Hər uğursuzluq sabit kodlu JSON zərfidir. İlk qarşılaşacağınız dördü:

ERR_API_KEY_INVALID

X-Api-Key başlığı yoxdur və ya heç bir açara uyğun gəlmir.

ERR_API_KEY_SCOPE

Açar etibarlıdır, lakin bu endpointin tələb etdiyi scope-u daşımır.

ERR_API_KEY_ENVIRONMENT

Sandbox açarı canlı API-yə göndərilib və ya əksinə.

ERR_RATE_LIMITED

Bu açar üçün çox sorğu. Retry-After-dakı saniyə qədər gözləyin.

Qalanları üçün tam xəta kataloquna baxın.