Token İşlemleri

Ödeal Sanal POS API'sini kullanabilmek için öncelikle bir authentication token almanız gerekir. Bu token, tüm API isteklerinde Authorization header'ı ile gönderilir.

Token Yaşam Döngüsü

Token Oluşturma: API Key ve Secret Key ile yeni bir access token alınır
Token Kullanımı: Access token, tüm API isteklerinde Bearer token olarak gönderilir
Token Yenileme: Token süresi dolmadan önce refresh token ile yeni token alınır
Token Geçersiz Olma: Yeni token alındığında eski token otomatik olarak geçersiz hale gelir

1. Token Oluşturma

API üzerinden credential isteği ile bir session token oluşturulur. Bu token diğer sanal POS API'leri çağırırken Authorization: Bearer {Token} şeklinde header'da gönderilmelidir.

Endpoint

POST /authenticate/credential/v2

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`apiKey`	string	Evet	Sistem tarafından verilen unique değer
`secretKey`	string	Evet	Müşteri bazlı gizli anahtar bilgisi

İstek Örneği

json

{
  "apiKey": "your-api-key-here",
  "secretKey": "your-secret-key-here"
}

Başarılı Yanıt

json

{
  "result": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
`result.accessToken`	string	API isteklerinde kullanılacak access token
`result.refreshToken`	string	Token yenilemede kullanılacak refresh token
`tokenType`	string	Token tipi (genellikle "Bearer")
`expiresIn`	integer	Token geçerlilik süresi (saniye cinsinden)

2. Token Yenileme

Token expire olduğunda yeni token alınmalıdır. Her yeni token alındığında eski token geçersiz hale gelir.

Endpoint

POST /authenticate/refresh-token/v2

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`refreshToken`	string	Evet	Daha önce alınan refresh token

İstek Örneği

json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Başarılı Yanıt

json

{
  "result": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "tokenType": "Bearer",
  "expiresIn": 3600
}

3. Token Kullanımı

Access token'ı aldıktan sonra, tüm API isteklerinde Authorization header'ında Bearer token olarak gönderin.

Header Örneği

http

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Önerilen Uygulamalar

1. Token Önbellekleme

Token'ı her istekte yeniden almak yerine, süresi dolana kadar önbellekte tutun. Bu performansı artırır ve gereksiz API çağrılarını önler.

2. Token Süresi Takibi

expiresIn değerini kullanarak token'ın ne zaman yenileneceğini belirleyin. Token süresinin dolmasından 5 dakika önce yenileme işlemine başlamak önerilir.

3. Güvenli Saklama

API Key ve Secret Key'i asla kodda saklamayın
Ortam değişkenleri (environment variables) kullanın
Secrets manager servisleri kullanın (AWS Secrets Manager, Azure Key Vault, vb.)

4. Hata Yönetimi

Token alımında oluşabilecek hataları yönetin. HTTP hataları ve response doğrulaması yapın.

5. Refresh Token Kullanımı

Token süresi dolmadan önce refresh token ile yenilemek, credential'ları tekrar göndermekten daha güvenlidir.

Güvenlik Önerileri

Kritik Güvenlik Kuralları

API Key ve Secret Key'i asla client-side kodda (JavaScript, mobil app) saklamayın
Bu bilgiler sadece backend/sunucu tarafında tutulmalıdır
HTTPS kullanımı zorunludur
Token'ları log'larda kaydetmeyin
Token'ları URL parametresi olarak göndermeyin

Test ve Production Ortamları

Test (Staging) Ortamı

Base URL: https://apigwstg.odeal.com/mobile

Test ortamında farklı API Key ve Secret Key kullanılır.

Canlı (Production) Ortamı

Base URL: https://apigw.odeal.com/mobile

Canlı ortam için ayrı API Key ve Secret Key verilir.

Sık Sorulan Sorular

Token ne kadar süre geçerlidir?

Token geçerlilik süresi expiresIn alanında saniye cinsinden döner. Genellikle 1 saat (3600 saniye) geçerlidir.

Token süresi dolduktan sonra ne olur?

Token süresi dolduğunda API istekleri 401 Unauthorized hatası döner. Yeni bir token almanız veya refresh token ile yenilemeniz gerekir.

Birden fazla token alabilir miyim?

Evet, ancak her yeni token alındığında önceki token geçersiz hale gelir. Aynı anda sadece bir aktif token bulunur.

Refresh token ne zaman kullanmalıyım?

Access token süresi dolmadan önce (örneğin 5 dakika kala) refresh token ile yeni token almanız önerilir. Bu sayede kesintisiz hizmet sağlarsınız.

Token'ı nasıl saklamalıyım?

Backend uygulamalarında memory cache veya Redis gibi hızlı cache çözümleri kullanabilirsiniz. Client-side uygulamalarda token alımı backend üzerinden yapılmalıdır.

Token İşlemleri ​

Token Yaşam Döngüsü ​

1. Token Oluşturma ​

Endpoint ​

İstek Parametreleri ​

İstek Örneği ​

Başarılı Yanıt ​

Yanıt Parametreleri ​

2. Token Yenileme ​

Endpoint ​

İstek Parametreleri ​

İstek Örneği ​

Başarılı Yanıt ​

3. Token Kullanımı ​

Header Örneği ​

Önerilen Uygulamalar ​

1. Token Önbellekleme ​

2. Token Süresi Takibi ​

3. Güvenli Saklama ​

4. Hata Yönetimi ​

5. Refresh Token Kullanımı ​

Güvenlik Önerileri ​

Test ve Production Ortamları ​

Test (Staging) Ortamı ​

Canlı (Production) Ortamı ​

Sık Sorulan Sorular ​

Token ne kadar süre geçerlidir? ​

Token süresi dolduktan sonra ne olur? ​

Birden fazla token alabilir miyim? ​

Refresh token ne zaman kullanmalıyım? ​

Token'ı nasıl saklamalıyım? ​

İlgili Kaynaklar ​

Token İşlemleri

Token Yaşam Döngüsü

1. Token Oluşturma

Endpoint

İstek Parametreleri

İstek Örneği

Başarılı Yanıt

Yanıt Parametreleri

2. Token Yenileme

Endpoint

İstek Parametreleri

İstek Örneği

Başarılı Yanıt

3. Token Kullanımı

Header Örneği

Önerilen Uygulamalar

1. Token Önbellekleme

2. Token Süresi Takibi

3. Güvenli Saklama

4. Hata Yönetimi

5. Refresh Token Kullanımı

Güvenlik Önerileri

Test ve Production Ortamları

Test (Staging) Ortamı

Canlı (Production) Ortamı

Sık Sorulan Sorular

Token ne kadar süre geçerlidir?

Token süresi dolduktan sonra ne olur?

Birden fazla token alabilir miyim?

Refresh token ne zaman kullanmalıyım?

Token'ı nasıl saklamalıyım?

İlgili Kaynaklar