4. Adım 1 — Kimlik bilgileri ve access token
4.1 Fırsat'tan aldıklarınız
| Alan | Nasıl görünür | Gizli mi? |
|---|---|---|
client_id | fpc_ + 32 hex karakter, ör. fpc_3f9a… | Hayır. Kullanıcı adı gibidir. |
client_secret | Uzun, rastgele bir metin | Evet. Şifre gibi davranın. |
| POS header id | <POS adınız>/ + 6 karakter, ör. adisyo/k7qm2x | Hayır. POS'unuzu tanımlar; token isteği dışındaki her çağrıda X-Firsat-Pos olarak gönderin. Asla değişmez, secret yenilense bile. |
Secret'ı yalnızca bir kez gösteririz. Kaybederseniz yenilemesini isteyin: yenisini alırsınız, eskisi çalışmayı bırakır.
Secret'ı sunucunuzda saklayın, asla restorandaki cihazda çalışan POS uygulamasının içinde değil. Bir cihazdan secret'ı okuyan herkes tüm işletmeleriniz adına kupon kullanabilir. Önerilen kurulum: secret'ı bulut tarafındaki backend'iniz tutar ve Fırsat ile o konuşur; POS cihazlarınız kendi backend'inizle konuşur.
4.2 Token alma
curl -X POST https://partner-api.firsat.dev/api/partner/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=fpc_3f9a...&client_secret=SIZIN_SECRET'Aynı istek JSON olarak da çalışır:
{ "grant_type": "client_credentials", "client_id": "fpc_3f9a…", "client_secret": "SIZIN_SECRET" }Id ve secret'ı HTTP Basic olarak da gönderebilirsiniz: Authorization: Basic base64(client_id:client_secret). İkisini birden gönderirseniz header geçerli olur.
Cevap:
{ "access_token": "fpt_Xk3…", "token_type": "Bearer", "expires_in": 3600 }Bu, X-Firsat-Pos taşımayan tek çağrıdır: client id ve secret zaten kim olduğunuzu söyler. Sonraki tüm çağrılar onu taşır.
4.3 Token nasıl kullanılır
- Diğer tüm çağrılara ekleyin:
Authorization: Bearer fpt_Xk3…. - Tek bir token tüm işletmeleriniz için geçerlidir. İşletme başına veya çağrı başına token istemeyin.
- Token'ı cache'leyin;
expires_indolmadan birkaç dakika önce yenisini isteyin. Token adresine rate limit uygulanır (bölüm 10). - Herhangi bir çağrı
401vePOS_PARTNER_TOKEN_INVALIDkodu dönerse, bir kez yeni token alıp aynı çağrıyı tekrarlayın. Yeni token da401alırsa durun ve Fırsat ile iletişime geçin (dev@firsat.com); secret'ınız yenilenmiş olabilir. - Token opaktır. Çözmeye (decode) çalışmayın.
function getToken():
if cachedToken var ve cachedToken.expiresAt > şimdi + 5 dakika:
return cachedToken
cevap = POST /oauth/token (client credentials)
cachedToken = cevap.access_token, expiresAt = şimdi + cevap.expires_in saniye
return cachedToken