Kimlik doğrulama

İstekler kısa ömürlü bir token ile doğrulanır. Gizli anahtar yalnızca token almak için kullanılır ve normal isteklerde iletilmez.

Neden sabit anahtar kullanılmıyor

Sabit API anahtarı her istekte ağ üzerinden taşınır. Anahtarın ele geçirilmesi hâlinde, durum fark edilip anahtar iptal edilene kadar erişim sürer. Token yöntemi bu riskin iki boyutunu da sınırlar: anahtar saatte yalnızca bir kez iletilir, ele geçirilen token ise en geç bir saat içinde geçersiz olur.

Token alma

POST /api/vendor/v1/token
Content-Type: application/json

{
  "clientId": "istemci-kimliginiz",
  "clientSecret": "hzl_live_..."
}

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

Diğer tüm çağrılarda aşağıdaki başlık gönderilir:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token'ı saklayın, süresi dolmadan yenileyin

Teslimat kaybına yol açan başlıca hata

Sipariş gönderimi sırasında token'ın süresi dolarsa istek 401 ile sonuçlanır ve Hızlıyo bu isteği yeniden denemez. Sorunun kaynağı araştırılırken paket beklemede kalır.

Token'ı, geçerlilik süresi dolmadan beş dakika önce yenileyin. 401 yanıtının gelmesini beklemeyin.

Her siparişten önce yeni token alınması gereksiz bir gidiş-dönüş oluşturur ve saatte 60 isteklik limite takılmanıza yol açar. Bu limite yaklaşıyorsanız token saklanmıyor demektir.

401 yanıtının değerlendirilmesi

İki farklı sorun aynı HTTP kodunu döndürür. WWW-Authenticate başlığı ve errorCode alanı hangisinin geçerli olduğunu belirtir.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="expired"

errorCode	Anlamı	Yapılması gereken
TOKEN_EXPIRED	Token'ın süresi dolmuş	Yeni token alın, isteği bir kez daha gönderin
INVALID_CREDENTIALS	Anahtar hatalı, iptal edilmiş ya da hesap kapalı	İşlemi durdurun. Yeniden deneme sonuç vermez, bizimle iletişime geçin

TOKEN_EXPIRED sonrasında isteğin yeniden gönderilmesi doğrudur ve bu karar size aittir. Bu durum, Hızlıyo'nun başarısız bir siparişi arka planda yeniden denemesiyle karıştırılmamalıdır; Hızlıyo böyle bir deneme yapmaz.

Anahtarın korunması

• Anahtarı mobil uygulamada, tarayıcı tarafında çalışan kodda veya sizin denetiminizde olmayan bir cihazda tutmayın. Anahtarın yeri sunucudur.
• POS yazılımınızı kullanan restoranlarla paylaşmayın.
• Ele geçirildiğinden şüpheleniyorsanız anahtarı yenileyin. Yenileme sonrasında elinizdeki token bir saat daha geçerli kalır; hizmet kesintisi oluşmaz.
• Şüphe oluştuğu anda, en geç 24 saat içinde bize bildirin. Anahtar ivedilikle kapatılır.

Ortamlar

Ortam	Anahtar ön eki	Adres
Test	hzl_test_	https://gw-dev.hizliyo.com/api/vendor/v1
Canlı	hzl_live_	https://gw.hizliyo.com/api/vendor/v1

Önce test anahtarı tanımlanır. Canlı anahtar, kontrol listesi tamamlandıktan sonra verilir.

Bağlantı güvenliği

TLS 1.2 ve üzeri zorunludur. Daha eski bir sürümle kurulan bağlantı, istek işlenmeden önce kesilir. HTTP yanıtı alınmadan kopan bağlantılarda ilk kontrol edilmesi gereken nokta TLS yapılandırmasıdır.