-
Tami Sanal POS
Tami Sanal POS
İstek Token’ı Oluşturma Genel Açıklama
Tami Sanal POS API’lerine (provizyon, satış vb.) istek gönderirken kullanılacak signedRequest token’ının nasıl üretileceği bu sayfada adım adım anlatılmaktadır.
Nedir, ne işe yarar?
Tami’ye gönderilen istekler düz JSON olarak gönderilmez. Bunun yerine istek gövdesi önce imzalanır (HS512 → JWS), ardından şifrelenir (dir + A256GCM → JWE). Elde edilen token, API’ye şu şekilde iletilir:
{ "signedRequest": "<üretilen-token>" }
Token şifreli olduğu için jwt.io’da açılmaz. Bu bir hata değildir, beklenen davranıştır.
Neye ihtiyaç var?
Aşağıdaki tabloda örnek olarak Test (Sandbox) Ortamı bilgileri kullanılmıştır. Üretim (prod) ortamında işlem yaparken kendi üye işyerinize ait Merchant ve Terminal numaralarını kullanmanız gerekir.
| Bilgi | Örnek |
|---|---|
| Üye işyeri numarası | 77006950 |
| Terminal numarası | 84006953 |
| JWK JSON (işyerine özel anahtar dosyası) | Aşağıda |
{
"kty": "oct",
"kid": "40e74b0c-75d4-4962-9792-c21464f8111b",
"k": "UXchS35U-_CfusZpw1U3LAqVVB7dcUwiettOPYulXHeBLbdjQBTsy42SF8bEyf4Zo-rJKckIU8o7WO6IqDbpzg",
"alg": "HS512"
}
- kid → Anahtar kimliğidir; token başlığına yazılır, sunucu üye işyerini bununla eşleştirir.
- k → Base64URL kodlu gizli anahtardır; imzalama ve şifreleme bu değerden türetilir.
JWK bulunmuyorsa üye işyeri temsilcisinden talep edilmelidir. k değeri hiçbir kişi veya sistemle paylaşılmamalı, kaynak kod deposuna (git) eklenmemelidir.
Token’ı 5 adımda üretme
Tercih edilen dile ait hazır kod örneği Kod Örnekleri bölümünde mevcuttur. Aşağıdaki adımlar mantığı göstermektedir; herhangi bir JOSE/JWT kütüphanesiyle (Java, Node, Python vb.) aynı akış kurulabilir.
Adım 1: JWK’yı yükleme
JWK JSON’u olduğu gibi kütüphaneye verilir. İmza anahtarı, k değerinin çözülmüş halidir.
signingKey = JWK.parse(jwkJson)
Adım 2: Şifreleme anahtarını türetme
İmza anahtarının SHA-256 özeti, şifreleme anahtarıdır (32 byte → A256GCM):
encryptionKey = SHA-256( base64UrlDecode(k) )
Adım 3: Claim’leri hazırlama
| Claim | Değer |
|---|---|
| iss | “77006950:84006953” (merchant:terminal) |
| aud | “tami” (sabit) |
| jti | her token için yeni üretilen UUID |
| iat / nbf | üretim anı |
| exp | üretim anından 10 dakika sonrası |
| tami:body | istek gövdesi (servis sözleşmesindeki JSON) |
| tami:apiVersion | “v4” (sabit) |
Adım 4: İmzalama (JWS)
Claim’ler HS512 ile imzalanır. Başlıkta kid ve typ: JWT yer almalıdır:
header = { alg: "HS512", kid: "<kid>", typ: "JWT" }
Adım 5: Şifreleme (JWE)
İmzalı JWT, aşağıdaki başlıkla şifrelenir ve serialize edilir:
header = { alg: "dir", enc: "A256GCM", cty: "JWT" }
Sonuç: nokta ile ayrılmış 5 parçalı bir compact token elde edilir. Bu, signedRequest değeridir.
API’ye gönderme
POST /api/v0/payment/auth
Content-Type: application/json
{ "signedRequest": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..q8rM..." }
Kurallar
- Token 10 dakika geçerlidir; her işlem öncesinde yeni token üretilmelidir.
- Aynı token sadece 1 kez kullanılabilir (jti bazlı).
- Token 5 parçalı olmalıdır; değilse üretim sürecinde bir sorun olduğu anlaşılır.
- Sunucu saatinin doğru (NTP senkronize) olması gerekir.
Kod Örnekleri
Aşağıda, çeşitli yazılım dilleri kullanılarak yazılmış özel kod örneklerinin linkleri verilmiştir. Tercih edilen programlama diline ait link üzerinden, önceden belirlenmiş değerlerle yazılmış olan kodlar detaylı bir şekilde incelenebilir.
Bu örnekler, signedRequest token oluşturma akışının 5 adımını içeren kodları barındırmaktadır ve farklı dillerde yazıldığı için çeşitli yaklaşımları ve pratikleri de gözlemlemek mümkündür. Bu sayede tercih edilen programlama diline dair daha anlaşılır ve özgün örneklerle çalışma imkânı bulunmaktadır.
- Java Kod Örnekleri için tıklayınız.
- PHP Kod Örnekleri için tıklayınız.
- C# Kod Örnekleri için tıklayınız.
- VB.Net Kod Örnekleri için tıklayınız.
- NodeJS Kod Örnekleri için tıklayınız.
Unutulmamalıdır ki bu örnekler ön tanımlı değerlerle yazılmıştır ve gerçek projelerde kullanımı için gerekli uyarlama ve güvenlik önlemlerinin alınması gerekebilir.
K ve Kid değerleri işyerlerine özel benzersiz değerlerdir. Production ortamda İşyeri portal sayfasında yer alan İşyeri Ayarları>Pos Yönetimi sayfasından firmalar görüntüleme yapabilir. Bu bilgilerin işlem güvenliği açısından belirli aralıklarla güncellenmesi firmaların sorumluluğundadır.
Test (Sandbox) ortamda işlem denerken K ve Kid değeri test portalinden aynı şekilde görüntüleme yapılabilir. Herhangi bir destek ihtiyacınız olduğunda TeknikDestek@tami.com.tr adresinden destek ekibimize ulaşabilirsiniz.
