Kimlik Doğrulama ve İmza
Her istek üç başlıkla kimlik doğrular:
X-Api-Key: key_...
X-Timestamp: 1790932530
X-Signature: <imza, küçük harf hex>
Content-Type: application/json
| Başlık | Değer |
|---|---|
X-Api-Key | Çalışma alanının API anahtarı. |
X-Timestamp | İmzanın atıldığı an, Unix saniyesi (yalnızca rakam). Sunucu saatinden en fazla 5 dakika uzak olabilir. |
X-Signature | İmzalanan metnin gizli anahtarla alınan HMAC-SHA256 özeti; küçük harfli hex. |
Content-Type | application/json (gövdeli isteklerde). |
İmza
imzalanan_metin = "{timestamp}\n{METOT}\n{yol}\n{gövde}"
X-Signature = lowercase_hex( HMAC_SHA256( key = gizli_anahtar, message = imzalanan_metin ) )
| Parça | Değer |
|---|---|
timestamp | X-Timestamp başlığında gönderilen değerin aynısı. |
METOT | Büyük harfle HTTP metodu. Gateway uçlarının hepsi POST'tur. |
yol | Adresin / ile başlayan, sorgu dizesi olmayan yolu: /api/4829301756/gateway/regular-payment. Alan adı dahil edilmez. |
gövde | Gönderilen gövdenin ham metni, byte byte. Alanı olmayan bir istekte (ör. son 7 günü soran retrieve-*) {} gönderilir ve imzalanır. |
- Parçalar tek bir satır sonuyla (
\n) birleştirilir; sonda fazladan satır sonu yoktur. - Gövdeyi bir kez metne çevirin; aynı metni hem imzalayın hem gönderin. İmzadan sonra gövdeyi yeniden kodlayan bir katman (boşluk, alan sırası, Unicode ya da
/kaçışı) imzayı bozar. Alan sırası ve boşluk, imzalanan ve gönderilen metin aynı olduğu sürece önemli değildir. - İmza yol ve metodu kapsadığı için bir uç için imzalanmış istek başka bir uca gönderilemez; zaman damgası 5 dakikadan eski istek kabul edilmez.
Test vektörü:
| Gizli anahtar | Zaman damgası | Metot | Yol | Gövde | İmza |
|---|---|---|---|---|---|
secret_test | 1700000000 | POST | /api/1000000001/gateway/regular-payment | {"a":1} | 4d6225c9dd46837418b40dd8140d76a24cd7520d81ff3b280bf98da8da6a8771 |
İsteği imzalamak
SDK'lar bu adımı kendileri yapar. SDK kullanmadan:
- PHP
- Node.js
- Python
- Java
- cURL
$path = '/api/'.getenv('ODEMEHUB_TEAM').'/gateway/regular-payment';
$body = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$signature = hash_hmac('sha256', "{$timestamp}\nPOST\n{$path}\n{$body}", getenv('ODEMEHUB_API_SECRET'));
// $body'yi olduğu gibi gönderin; X-Timestamp: $timestamp, X-Signature: $signature
import { createHmac } from 'node:crypto';
const path = `/api/${process.env.ODEMEHUB_TEAM}/gateway/regular-payment`;
const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac('sha256', process.env.ODEMEHUB_API_SECRET!)
.update(`${timestamp}\nPOST\n${path}\n${body}`)
.digest('hex');
// body'yi olduğu gibi gönderin; X-Timestamp: timestamp, X-Signature: signature
import hashlib
import hmac
import json
import os
import time
path = f"/api/{os.environ['ODEMEHUB_TEAM']}/gateway/regular-payment"
body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
text = f"{timestamp}\nPOST\n{path}\n".encode() + body
signature = hmac.new(os.environ["ODEMEHUB_API_SECRET"].encode(), text, hashlib.sha256).hexdigest()
# body'yi olduğu gibi gönderin; X-Timestamp: timestamp, X-Signature: signature
import com.odemehub.Signature;
String path = "/api/" + System.getenv("ODEMEHUB_TEAM") + "/gateway/regular-payment";
byte[] body = objectMapper.writeValueAsBytes(payload);
long timestamp = System.currentTimeMillis() / 1000;
String signature = new Signature(System.getenv("ODEMEHUB_API_SECRET")).sign("POST", path, body, timestamp);
// body'yi olduğu gibi gönderin; X-Timestamp: timestamp, X-Signature: signature
URI_PATH="/api/$ODEMEHUB_TEAM/gateway/retrieve-payments"
BODY='{"token":"0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')
curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $ODEMEHUB_API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"
İmzalanan metin printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" ile kurulur; $BODY gönderilen metnin aynısıdır.
Yanıtın imzasını doğrulamak
Gateway'in 200, 403, 404, 422, 429 ve 500 yanıtları imzalıdır (401 ve çalışma alanı bulunamadığında dönen 404 imzasızdır). Yanıt kendi X-Timestamp ve X-Signature başlıklarıyla gelir; imzalanan metin, isteğin metodu ve yolu ile yanıtın ham gövdesinden kurulur:
"{yanıtın X-Timestamp değeri}\n{isteğin METODU}\n{isteğin yolu}\n{yanıtın ham gövdesi}"
Gövdeyi ham hâliyle okuyun, imzayı hesaplayın ve X-Signature başlığıyla sabit zamanlı karşılaştırın. Tutmuyorsa yanıtı işlemeyin.
Gateway yanıt gövdesinde / karakterini \/ olarak kaçışlar (ör. "https:\/\/..."). İmza bu ham metin üzerinden hesaplanır; gövdeyi ayrıştırıp yeniden yazmadan doğrulayın.
- PHP
- Node.js
- Python
- Java
- cURL
use Gurmehub\Odemehub\Signature;
// SDK her yanıtı kendisi doğrular; tutmazsa SignatureException atar.
$valid = (new Signature(getenv('ODEMEHUB_API_SECRET')))->verify(
'POST', $path, $rawResponseBody, $responseTimestampHeader, $responseSignatureHeader,
);
import { Signature } from '@odemehub/node-sdk';
// SDK her yanıtı kendisi doğrular; tutmazsa SignatureError atar.
const valid = new Signature(process.env.ODEMEHUB_API_SECRET!).verifyMessage(
'POST', path, rawResponseBody, responseTimestampHeader, responseSignatureHeader,
);
import os
from odemehub import Signature
# SDK her yanıtı kendisi doğrular; tutmazsa SignatureError atar.
valid = Signature(os.environ["ODEMEHUB_API_SECRET"]).verify(
"POST", path, raw_response_body, response_timestamp_header, response_signature_header,
)
import com.odemehub.Signature;
// SDK her yanıtı kendisi doğrular; tutmazsa SignatureException atar.
boolean valid = new Signature(System.getenv("ODEMEHUB_API_SECRET")).verify(
"POST", path, rawResponseBody, responseTimestampHeader, responseSignatureHeader);
# Yanıt gövdesi response.json'da, başlıklar headers.txt'de (curl -D headers.txt -o response.json ...)
RESPONSE_TIMESTAMP=$(grep -i '^x-timestamp:' headers.txt | awk '{print $2}' | tr -d '\r')
RECEIVED=$(grep -i '^x-signature:' headers.txt | awk '{print $2}' | tr -d '\r')
EXPECTED=$({ printf '%s\n%s\n%s\n' "$RESPONSE_TIMESTAMP" "POST" "$URI_PATH"; cat response.json; } | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')
[ "$EXPECTED" = "$RECEIVED" ] && echo "imza geçerli" || echo "imza geçersiz"
SDK'ların verify yardımcıları, zaman damgası 5 dakikadan eski olan imzayı da geçersiz sayar.
Kimlik doğrulama hataları
Yanıt 401'dir ve imzasızdır.
| Durum | result.message |
|---|---|
X-Api-Key eksik ya da adresteki çalışma alanına ait değil | Geçersiz API anahtarı. |
X-Timestamp eksik, rakam dışı karakter içeriyor ya da 5 dakikadan uzak | İmzanın zaman damgası eksik ya da izin verilen aralığın dışında. |
X-Signature eksik ya da imzalanan metinle tutmuyor | İmza doğrulanamadı. |
{
"result": {
"successful": false,
"message": "İmza doğrulanamadı."
}
}
Sunucunuzun saati kaymışsa bütün istekler zaman damgası hatası alır; saati NTP ile eşitleyin.