Kimlik Doğrulama (Authentication)

Partner API'ye yapılan her istek, HMAC-SHA256 istek imzalama ile doğrulanmalıdır. Bu, isteklerin hem özgün olduğunu hem de iletim sırasında değiştirilmediğini garanti eder.

Gerekli Başlıklar (Headers)

Başlık	Açıklama
`X-API-Key`	Kuruluşunuzun API anahtarı
`X-Timestamp`	Saniye cinsinden geçerli Unix zaman damgası (ör. `1711000000`)
`X-Nonce`	Her istek için benzersiz bir dize (UUID v4 önerilir)
`X-Signature`	İsteğin HMAC-SHA256 onaltılık (hex) imzası

İmza Oluşturma

İmza, nokta ile ayrılmış bir mesaj dizesi oluşturularak ve API anahtar gizli anahtarınızla imzalanarak hesaplanır:

message = "{timestamp}.{nonce}.{method}.{path}.{body}"
signature = HMAC-SHA256(apiKeySecret, message).hexDigest()

Noktalarla (.) birleştirilen mesaj bileşenleri:

timestamp — Saniye cinsinden Unix zaman damgası (X-Timestamp başlığındaki değerle aynı)
nonce — X-Nonce başlığında gönderilen aynı değer
method — Büyük harfle HTTP metodu (ör. GET, POST)
path — Tam istek yolu (ör. /v2/partners/products/tickets)
body — Ham JSON istek gövdesi dizesi. Gövdesi olmayan GET istekleri için boş dize "" kullanın

Elde edilen HMAC özeti küçük harfli onaltılık (hex) olarak kodlanmalıdır.

Örnekler

API_KEY="your-api-key"
API_SECRET="your-api-secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="GET"
REQ_PATH="/v2/partners/products/tickets"
BODY=""

MESSAGE="${TIMESTAMP}.${NONCE}.${METHOD}.${REQ_PATH}.${BODY}"

SIGNATURE=$(echo -n "${MESSAGE}" | \
  openssl dgst -sha256 -hmac "${API_SECRET}" | \
  awk '{print $2}')

curl -X GET "https://api.vignetim.com${REQ_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}"

Önemli Notlar

X-Timestamp sunucu saatinin 5 dakikası (300 saniye) içinde olmalıdır. Süresi geçmiş zaman damgalarına sahip istekler 401 hatasıyla reddedilir.
Her X-Nonce değeri benzersiz olmalı ve yalnızca bir kez kullanılabilir. Bir nonce'un tekrar kullanılması 401 hatasıyla sonuçlanır.
İmza hesaplaması için her zaman ham, biçimlendirilmemiş JSON gövde dizesini kullanın. İmzalamadan önce gövdeyi güzelleştirmeyin veya yeniden serileştirmeyin.
İmza küçük harfli onaltılık (hex) kodlanmış olmalıdır. Base64 kullanmayın.

Başlık

Açıklama

X-API-Key

Kuruluşunuzun API anahtarı

X-Timestamp

Saniye cinsinden geçerli Unix zaman damgası (ör. 1711000000)

X-Nonce

Her istek için benzersiz bir dize (UUID v4 önerilir)

X-Signature

İsteğin HMAC-SHA256 onaltılık (hex) imzası

İmza Oluşturma

İmza, nokta ile ayrılmış bir mesaj dizesi oluşturularak ve API anahtar gizli anahtarınızla imzalanarak hesaplanır:

message = "{timestamp}.{nonce}.{method}.{path}.{body}" signature = HMAC-SHA256(apiKeySecret, message).hexDigest()

Noktalarla (.) birleştirilen mesaj bileşenleri:

timestamp — Saniye cinsinden Unix zaman damgası (X-Timestamp başlığındaki değerle aynı)

nonce — X-Nonce başlığında gönderilen aynı değer

method — Büyük harfle HTTP metodu (ör. GET, POST)

path — Tam istek yolu (ör. /v2/partners/products/tickets)

body — Ham JSON istek gövdesi dizesi. Gövdesi olmayan GET istekleri için boş dize "" kullanın

Elde edilen HMAC özeti küçük harfli onaltılık (hex) olarak kodlanmalıdır.

Örnekler

API_KEY="your-api-key"
API_SECRET="your-api-secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="GET"
REQ_PATH="/v2/partners/products/tickets"
BODY=""

MESSAGE="${TIMESTAMP}.${NONCE}.${METHOD}.${REQ_PATH}.${BODY}"

SIGNATURE=$(echo -n "${MESSAGE}" | \
  openssl dgst -sha256 -hmac "${API_SECRET}" | \
  awk '{print $2}')

curl -X GET "https://api.vignetim.com${REQ_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}"

Önemli Notlar

X-Timestamp sunucu saatinin 5 dakikası (300 saniye) içinde olmalıdır. Süresi geçmiş zaman damgalarına sahip istekler 401 hatasıyla reddedilir.

Her X-Nonce değeri benzersiz olmalı ve yalnızca bir kez kullanılabilir. Bir nonce'un tekrar kullanılması 401 hatasıyla sonuçlanır.

İmza hesaplaması için her zaman ham, biçimlendirilmemiş JSON gövde dizesini kullanın. İmzalamadan önce gövdeyi güzelleştirmeyin veya yeniden serileştirmeyin.

İmza küçük harfli onaltılık (hex) kodlanmış olmalıdır. Base64 kullanmayın.