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 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 /tokenİ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
{
"apiKey": "your-api-key-here",
"secretKey": "your-secret-key-here"
}Başarılı Yanıt
{
"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 |
tokenType | string | Token tipi (genellikle "Bearer") |
expiresIn | integer | Token geçerlilik süresi (saniye cinsinden) |
3. Token Kullanımı
Access token'ı aldıktan sonra, tüm API isteklerinde Authorization header'ında Bearer token olarak gönderin.
Header Örneği
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.
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://auth-sandbox.odeal.com/api/v1/Test ortamında farklı API Key ve Secret Key kullanılır.
Canlı (Production) Ortamı
Base URL: https://auth-sandbox.odeal.com/api/v1/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 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.
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.