İçeriğe geç

Kimlik doğrulama ve istek imzası

API anahtarı, zaman damgası ve HMAC-SHA256 imzasıyla isteklerin nasıl doğrulandığı; Node.js ve bash örnekleri.

Son güncelleme:

İstek biçimi

Tüm uçlar POST ile çağrılır; içerik application/json (UTF-8) olmalıdır. Uç adresi şu kalıptadır:

Uç adresitext
https://apis.panel.riza.al/integrations/external-consent/{clientKey}/consents

Kimlik doğrulama başlıkları

İstek başlıkları
BaşlıkZorunluDeğer
Authorization: Bearer <apiKey> veya X-Rizaal-Api-Key: <apiKey>Evet (biri)Bağlantınıza ait API anahtarı.
X-Rizaal-TimestampEvetUnix saniye cinsinden zaman. Sunucu saatiyle farkı en çok ±300 saniye olabilir.
X-Rizaal-SignatureEvetv1=<hex> biçimli imza (aşağıya bakın). Secret rotasyonu sırasında boşlukla ayrılmış birden çok v1=... değeri kabul edilir.
Idempotency-KeyHayırTekrar gönderimi güvenli kılan anahtar (bkz. Hata kodları ve idempotency).
Content-Type: application/jsonEvet—

İmzanın hesaplanması

İmza, HMAC-SHA256(webhookSecret, timestamp + "." + hamGövde) değerinin küçük harfli hex gösterimidir ve başına v1= eklenir.

  • İmza, ağa giden ham baytlar üzerindendir. Gövdeyi imzaladıktan sonra yeniden serileştirmeyin, boşluk veya satır sonu eklemeyin.
  • İmzalanan dizgi "<timestamp>." + gövde biçimindedir: nokta dahil, arada boşluk yoktur.
  • Zaman damgası saniye cinsindendir; milisaniye gönderirseniz doğrulama başarısız olur.
  • Sunucu saatinizin NTP ile senkron olduğundan emin olun.

Node.js örneği

Node.js — imzalı istek göndermejs
const crypto = require("crypto");

const BASE = "https://apis.panel.riza.al/integrations/external-consent";
const CLIENT_KEY = process.env.RIZAAL_CLIENT_KEY;
const API_KEY = process.env.RIZAAL_API_KEY;
const SECRET = process.env.RIZAAL_WEBHOOK_SECRET;

async function post(path, payload, idempotencyKey) {
  // Gövdeyi TEK KEZ serileştirin; imzalanan baytlar ağa giden baytlarla aynı olmalı.
  const body = Buffer.from(JSON.stringify(payload), "utf8");
  const ts = Math.floor(Date.now() / 1000);
  const signature =
    "v1=" +
    crypto.createHmac("sha256", SECRET).update(ts + ".", "utf8").update(body).digest("hex");

  const headers = {
    "Content-Type": "application/json",
    Authorization: "Bearer " + API_KEY,
    "X-Rizaal-Timestamp": String(ts),
    "X-Rizaal-Signature": signature,
  };
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;

  const res = await fetch(BASE + "/" + CLIENT_KEY + path, { method: "POST", headers, body });
  return { status: res.status, json: await res.json() };
}

bash / openssl örneği

curl ile imzalı istekbash
# Değerleri kendi bağlantı bilgilerinizle değiştirin (aşağıdakiler örnektir).
SECRET='SECRET_DEGERINIZ'
API_KEY='rzl_ornek_xxxxxxxx'
CLIENT_KEY='ISTEMCI_ANAHTARINIZ'

BODY='{"externalEventId":"evt-ornek-0001","customer":{"externalCustomerId":"musteri-ornek-1"},"contact":{"phone":"+90 555 000 00 00"},"decisions":[{"kind":"KVKK","decision":"ONAY","decidedAt":"2026-10-13T14:05:30+03:00","evidence":{"method":"VOICE_CALL"}}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://apis.panel.riza.al/integrations/external-consent/$CLIENT_KEY/consents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Rizaal-Timestamp: $TS" \
  -H "X-Rizaal-Signature: v1=$SIG" \
  --data-binary "$BODY"

Kimlik doğrulama hataları

Her kimlik hatası (anahtar yok veya yanlış, bağlantı pasif, imza ya da zaman damgası geçersiz) aynı tek tip 401 yanıtını döner; nedeni güvenlik gereği belirtilmez.

401 yanıtıjson
{
  "success": false,
  "statusCode": 401,
  "message": "Kimlik doğrulama başarısız.",
  "data": null
}

401 alırsanız sırasıyla şunları kontrol edin: clientKey ve API anahtarı doğru mu, bağlantı aktif mi, imza webhook secret'ı ile mi hesaplandı, gövde imzadan sonra değişti mi, zaman damgası saniye cinsinden ve saat farkı 300 saniyenin altında mı.

API anahtarınızı ve bağlantınızı yönetmek için panelde Hesabım → Şirket Ayarları → API Erişimi sekmesini kullanın. Hesabım sayfasını aç (giriş yapmanız gerekir).