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:
https://apis.panel.riza.al/integrations/external-consent/{clientKey}/consentsKimlik doğrulama başlıkları
| Başlık | Zorunlu | Değer |
|---|---|---|
Authorization: Bearer <apiKey> veya X-Rizaal-Api-Key: <apiKey> | Evet (biri) | Bağlantınıza ait API anahtarı. |
X-Rizaal-Timestamp | Evet | Unix saniye cinsinden zaman. Sunucu saatiyle farkı en çok ±300 saniye olabilir. |
X-Rizaal-Signature | Evet | v1=<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-Key | Hayır | Tekrar gönderimi güvenli kılan anahtar (bkz. Hata kodları ve idempotency). |
Content-Type: application/json | Evet | — |
İ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övdebiç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
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
# 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.
{
"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).
