Rina Roleplay

Başlangıç

Genel bakış

Gateway API, JSON döndüren basit bir HTTP API'dir. Kullanıcıya ait verilere erişim OAuth 2.0 yetkilendirme kodu akışıyla alınan bir Bearer token ile yapılır.

Temel URL: https://www.rina-roleplay.com/gateway/api/v2
Yanıt biçimi: JSON (UTF-8)
İstek gövdesi: application/x-www-form-urlencoded
Kimlik doğrulama: OAuth 2.0 (Authorization Code) + Bearer token
Access token süresi: 24 saat
Refresh token: Tek kullanımlık, access token süresi dolduktan sonra 30 gün

Uygulama kaydı Uygulamalar RINA ekibi tarafından kaydedilir. client_id / client_secret almak, redirect_uri adreslerinizi kaydettirmek veya bankacılık partner erişimi istemek için destek talebi (ticket) açın. Talepte uygulamanızın adını, ne yaptığını ve kullanacağınız yönlendirme adreslerini belirtin.

POST isteklerinde parametreleri form verisi (application/x-www-form-urlencoded) olarak gönderin; JSON gövde okunmaz. Bu sayfadaki tüm yollar temel URL'ye göredir. https://www.rina-roleplay.com/gateway/api/v1 önekli eski yollar da aynı uç noktalara yönlenir; yeni entegrasyonlarda v2 kullanın.

Kimlik doğrulama

OAuth 2.0 akışı

Kullanıcı RINA Club hesabıyla giriş yapar, uygulamanıza izin verir ve uygulamanız bir access token alır. Şifre hiçbir zaman uygulamanıza iletilmez.

1
Kullanıcıyı yetkilendirme sayfasına yönlendirin

Rastgele bir state üretip oturumda saklayın ve kullanıcıyı aşağıdaki adrese gönderin. Ayrıntılar: /oauth/authorize.
URL
```
https://www.rina-roleplay.com/gateway/api/v2/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=basic&state=RANDOM_STATE
```
2
Geri dönüşü karşılayın

Kullanıcı izin verirse redirect_uri adresinize code ve state ile döner. state değerinin sakladığınızla aynı olduğunu doğrulayın. Kullanıcı reddederse error=access_denied gelir. Kod 5 dakika geçerlidir ve yalnızca bir kez kullanılabilir.
URL
```
https://example.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
```

Kodu token ile değiştirin

Sunucunuzdan /oauth/token adresine client_secret ile birlikte istek atın. Yanıttaki access_token değerini güvenli biçimde saklayın.

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/oauth/token" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://example.com/callback"

API'yi çağırın

Her istekte token'ı Authorization başlığında gönderin.

curl

curl "https://www.rina-roleplay.com/gateway/api/v2/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /oauth/token

grant_type=refresh_token

Token yenileme

Access token 24 saat geçerlidir. Süresi dolmadan önce veya bir istek 401 invalid_token aldığında, kullanıcıyı yeniden yönlendirmeden yeni bir token almak için refresh token kullanın.

Refresh token tek kullanımlıktır. Başarılı yenilemede yeni bir access_token ve yeni bir refresh_token döner; eski refresh token ve eski access token anında geçersiz olur. Yeni refresh token'ı hemen saklayın.
Aynı refresh token ikinci kez gönderilirse istek invalid_refresh_token ile reddedilir. Eşzamanlı yenileme isteklerini tek bir noktadan yönetin.
Refresh token yalnızca verildiği uygulamanın client_id ve client_secret değerleriyle kullanılabilir.
Refresh token, access token'ın süresi dolduktan sonra 30 gün daha kullanılabilir. Bu süre geçerse refresh_token_expired döner; kullanıcıyı yeniden yetkilendirme akışına yönlendirin.
Yenilemede kapsam (scope) değişmez.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/oauth/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Örnek yanıt

JSON

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "basic"
}

Güvenlik client_secret ve token'ları yalnızca sunucu tarafında tutun, Authorization: Basic başlığında veya POST gövdesinde gönderin (URL sorgu dizesine koymayın) ve günlük kayıtlarına yazmayın. Akış yalnızca gizli anahtarı saklayabilen sunucu uygulamaları için uygundur; tarayıcı veya mobil istemciler token alma işlemini kendi sunucunuz üzerinden yapmalıdır.

GET /oauth/authorize

Tarayıcı yönlendirmesi

Yetkilendirme isteği

Kullanıcının tarayıcısını bu adrese yönlendirin. Kullanıcı Club hesabına giriş yapmamışsa önce giriş formu, ardından uygulamanızın adını ve istenen kapsamı gösteren onay ekranı açılır. Bu uç nokta JSON döndürmez; sonuç her zaman redirect_uri adresinize yapılan bir yönlendirmedir.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`client_id`	string	Evet	Sorgu	Uygulamanıza verilen istemci kimliği.
`redirect_uri`	string	Evet	Sorgu	Uygulamanız için kayıtlı yönlendirme adresiyle birebir aynı olmalıdır (sondaki `/` yok sayılır).
`scope`	string	Hayır	Sorgu	İstenen kapsam. Gönderilmezse `basic` kullanılır.
`state`	string	Hayır	Sorgu	Rastgele bir değer üretin; geri yönlendirmede aynen döner. CSRF koruması için mutlaka kullanmanız önerilir.

Onay verilirse kullanıcı redirect_uri?code=…&state=… adresine döner. Kod 5 dakika geçerlidir ve tek kullanımlıktır.
Kullanıcı onay ekranında İptal derse redirect_uri?error=access_denied&state=… adresine döner.
client_id veya redirect_uri geçersizse kullanıcıya hata sayfası gösterilir ve uygulamanıza yönlendirme yapılmaz.
Yetkilendirme ve onay sayfaları iframe içinde açılamaz; kullanıcıyı tam sayfa yönlendirme veya yeni pencere ile gönderin.

Örnek istek

URL

https://www.rina-roleplay.com/gateway/api/v2/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=basic&state=RANDOM_STATE

Örnek yanıt

HTTP

HTTP/1.1 302 Found
Location: https://example.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

POST /oauth/token

client_secret

Token al ve yenile

Yetkilendirme kodunu bir access token ile değiştirir (grant_type=authorization_code) veya token'ı refresh token ile yeniler (grant_type=refresh_token). Bu isteği yalnızca sunucu tarafından yapın; client_secret hiçbir zaman tarayıcıya, mobil uygulamaya veya herkese açık bir depoya konmamalıdır.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`grant_type`	string	Hayır	Gövde	`authorization_code` (varsayılan) veya `refresh_token`.
`client_id`	string	Evet	Gövde veya Basic	Uygulamanızın istemci kimliği.
`client_secret`	string	Evet	Gövde veya Basic	Uygulamanızın gizli anahtarı. Alternatif: `Authorization: Basic base64(client_id:client_secret)`.
`code`	string	Evet	Gövde	Yalnızca `authorization_code`: geri yönlendirmede aldığınız `code`.
`redirect_uri`	string	Evet	Gövde	Yalnızca `authorization_code`: yetkilendirme isteğinde kullandığınız adresin aynısı.
`refresh_token`	string	Evet	Gövde	Yalnızca `refresh_token`: en son aldığınız refresh token.

access_token 24 saat geçerlidir; kalan süre saniye cinsinden expires_in alanındadır.
Yenileme kuralları ve örnek istek için Token yenileme bölümüne bakın.
Yanıtlar önbelleğe alınmaz (Cache-Control: no-store).

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/oauth/token" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://example.com/callback"

Örnek yanıt

JSON

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "basic"
}

Olası hatalar

HTTP	Kod	Açıklama
400	`invalid_client`	`client_id` bulunamadı, uygulama aktif değil veya `client_secret` hatalı.
400	`unsupported_grant_type`	`grant_type` desteklenmiyor.
400	`invalid_redirect_uri`	`redirect_uri` kayıtlı adresle veya kodun alındığı adresle eşleşmiyor.
400	`invalid_code`	Kod bu uygulamaya ait değil veya bulunamadı.
400	`code_used`	Kod daha önce kullanılmış.
400	`code_expired`	Kodun 5 dakikalık süresi dolmuş.
400	`invalid_refresh_token`	Refresh token bulunamadı, başka bir uygulamaya ait, iptal edilmiş veya daha önce kullanılmış.
400	`refresh_token_expired`	Refresh token'ın kullanım süresi dolmuş; kullanıcıyı yeniden yetkilendirin.
500	`server_error`	Token oluşturulamadı; akışı yeniden başlatın.
405	`(boş gövde)`	İstek `POST` değil.

Yetkiler

Kapsamlar

Kapsam, yetkilendirme isteğindeki scope parametresiyle istenir ve onay ekranında kullanıcıya gösterilir. Verilen kapsam token yanıtındaki ve /me yanıtındaki scope alanında döner.

Kapsam	Açıklama	Uç noktalar
`basic`	Varsayılan ve şu anda tanımlı tek kapsam. Temel profil bilgileri (kullanıcı adı, karakterler) ve kullanıcının kendi karakterlerine bildirim gönderme.	/me, /characters, /notification/*, /banking/initiate-payment (partner)

Referans

Uç noktalar

Yollar https://www.rina-roleplay.com/gateway/api/v2 temel URL'sine eklenir.

Desteklenen sunucular Karakter, bildirim ve bankacılık uç noktaları (/characters, /notification/*, /banking/*) şu anda yalnızca serverId=1 (Rina V, Türkçe FiveM sunucusu) için çalışır. Diğer sunucu kimlikleri için bu uç noktalar hata döndürür.

GET /servers

Herkese açık

Sunucu listesi

Aktif sunucuları öncelik sırasına göre listeler. Kimlik doğrulama gerektirmez. Diğer uç noktalarda istenen serverId değerini buradan alabilirsiniz.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`platform`	string	Hayır	Sorgu	Yalnızca belirtilen platformdaki sunucuları döndürür (`gtav` = FiveM, `samp` = SA-MP).

Her kayıt şu alanları içerir: ServerID, Platform, Name, Region, Priority, Active, ActivePlayers, Last24hPlayers.
ActivePlayers anlık çevrimiçi oyuncu sayısı, Last24hPlayers son 24 saatte giriş yapan (veya şu an çevrimiçi olan) oyuncu sayısıdır. Değerler dakikada bir güncellenir; oyuncu sayısı izlenmeyen sunucularda 0 döner.
Sayısal alanlar sorguya göre sayı veya metin (string) olarak gelebilir; istemcinizde ikisini de kabul edin.

Örnek istek

curl

curl "https://www.rina-roleplay.com/gateway/api/v2/servers?platform=gtav"

Örnek yanıt

JSON

{
  "servers": [
    {
      "ServerID": 1,
      "Platform": "gtav",
      "Name": "Rina V - Turkish Server",
      "Region": "tr",
      "Priority": 10,
      "Active": 1,
      "ActivePlayers": 179,
      "Last24hPlayers": 1119
    }
  ]
}

GET /me

Bearer token

Yetkilendiren kullanıcı

Token'ı veren Club hesabının temel bilgilerini ve token'ın kapsamını döndürür.

Parametreler

Bu uç nokta parametre almaz.

Örnek istek

curl

curl "https://www.rina-roleplay.com/gateway/api/v2/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Örnek yanıt

JSON

{
  "user": {
    "AccountID": 12345,
    "Username": "ornek_kullanici",
    "CreationDate": "<hesap oluşturma tarihi>"
  },
  "scope": "basic"
}

Olası hatalar

HTTP	Kod	Açıklama
401	`missing_bearer`	`Authorization: Bearer …` başlığı gönderilmedi.
401	`invalid_token`	Token bulunamadı veya süresi doldu.

POST /characters

Bearer token

Karakterler

Kullanıcının seçilen sunucudaki oyun hesabını ve aktif karakterlerini, karakterlere bağlı banka hesaplarıyla birlikte döndürür. Yalnızca FiveM (gtav) sunucuları desteklenir.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`serverId`	integer	Evet	Gövde	Sunucu kimliği (/servers). Şu anda yalnızca `1` desteklenir.

Devre dışı bırakılmış karakterler listelenmez. Karakterin banka hesabı yoksa BankAccounts boş dizidir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/characters" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "serverId=1"

Örnek yanıt

JSON

{
  "serverId": 1,
  "platform": "gtav",
  "account": {
    "AccountID": 12345,
    "Username": "ornek_kullanici",
    "DiscordID": "<discord kimliği>",
    "ForumID": 0,
    "LastLogin": "<son giriş>",
    "CreationDate": "<oluşturma tarihi>",
    "Online": 0
  },
  "characters": [
    {
      "UserID": 678,
      "Name": "John_Doe",
      "Sex": "<cinsiyet>",
      "Origin": "<köken>",
      "Borndate": "<doğum tarihi>",
      "PhoneNumber": "<telefon numarası>",
      "LastLogin": "<son giriş>",
      "CreatedTime": "<oluşturma tarihi>",
      "HeadshotImage": "<görsel adresi>",
      "Online": 0,
      "BankAccounts": [
        {
          "BankID": 4321,
          "CreatedTime": "<oluşturma tarihi>"
        }
      ]
    }
  ]
}

Olası hatalar

HTTP	Kod	Açıklama
401	`missing_bearer`	`Authorization: Bearer …` başlığı gönderilmedi.
401	`invalid_token`	Token bulunamadı veya süresi doldu.
400	`validation_error`	`serverId` eksik veya 1'den küçük.
404	`server_not_found`	Sunucu bulunamadı veya aktif değil.
400	`unknown_platform`	Sunucu FiveM (`gtav`) değil.
400	`server_not_supported`	Bu sunucu için karakter verisi henüz sunulmuyor.
404	`account_not_found`	Kullanıcının bu sunucuda oyun hesabı yok.
405	`(boş gövde)`	İstek `POST` değil.

POST /notification/send-to-player

Bearer token

Karaktere oyun içi bildirim

Kullanıcının kendi karakterine oyun içi sohbet bildirimi gönderir. Mesajın başına uygulamanızın adı eklenir: [Uygulama Adı] mesaj.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`userId`	integer	Evet	Gövde	Karakter kimliği (/characters yanıtındaki `UserID`). Karakter, token sahibinin hesabına ait olmalıdır.
`serverId`	integer	Evet	Gövde	Karakterin bulunduğu sunucu. Şu anda yalnızca `1` desteklenir.
`messageType`	string	Evet	Gövde	`success`, `error`, `warning`, `gray` veya `normal`.
`messageText`	string	Evet	Gövde	En fazla 500 bayt (Türkçe karakterler 2 bayt sayılır).

Oyun sunucusu yanıta ek alanlar ekleyebilir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/notification/send-to-player" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "userId=678" \
  -d "serverId=1" \
  -d "messageType=success" \
  --data-urlencode "messageText=Siparişin hazır!"

Örnek yanıt

JSON

{
  "message": "Notification sent successfully to player",
  "status": "sent",
  "userId": 678,
  "messageType": "success",
  "messageText": "[Uygulama Adı] Siparişin hazır!",
  "serverId": 1,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı"
  },
  "timestamp": "2026-01-01T12:00:00+03:00"
}

Olası hatalar

HTTP	Kod	Açıklama
401	`authentication_required`	Bearer token gönderilmedi (`error_code` alanında döner).
401	`invalid_token`	Token bulunamadı veya süresi doldu.
401	`invalid_app`	Token'ın ait olduğu uygulama bulunamadı (`error_code`).
400	`missing_parameter`	Zorunlu bir parametre eksik.
400	`invalid_message_type`	`messageType` izin verilen değerlerden biri değil.
400	`invalid_user_id`	`userId` pozitif bir tam sayı değil.
400	`message_too_long`	`messageText` 500 baytı aşıyor.
403	`access_denied`	Karakter token sahibinin hesabına ait değil.
500	`notification_failed`	Bildirim oyun sunucusuna iletilemedi.

POST /notification/send-phone-notify

Bearer token

Karakterin telefonuna bildirim

Kullanıcının kendi karakterinin oyun içi telefonunda bildirim gösterir.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`userId`	integer	Evet	Gövde	Karakter kimliği. Karakter, token sahibinin hesabına ait olmalıdır.
`serverId`	integer	Evet	Gövde	Karakterin bulunduğu sunucu. Şu anda yalnızca `1` desteklenir.
`title`	string	Evet	Gövde	Başlık, en fazla 100 bayt.
`message`	string	Evet	Gövde	Mesaj, en fazla 200 bayt.
`author`	string	Hayır	Gövde	Gönderen adı, en fazla 50 bayt. Varsayılan: uygulamanızın adı.
`image`	string (URL)	Hayır	Gövde	Bildirim görseli adresi. Varsayılan: `https://via.placeholder.com/64x64`.
`timeout`	integer	Hayır	Gövde	Görünme süresi (milisaniye), 1000–30000 arası. Varsayılan: 5000.

İsteğe bağlı parametreler yalnızca istek gövdesinden okunur.
Oyun sunucusu yanıta ek alanlar ekleyebilir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/notification/send-phone-notify" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "userId=678" \
  -d "serverId=1" \
  --data-urlencode "title=Yeni sipariş" \
  --data-urlencode "message=Siparişin kargoya verildi." \
  -d "timeout=8000"

Örnek yanıt

JSON

{
  "message": "Phone notification sent successfully to player",
  "status": "sent",
  "userId": 678,
  "title": "Yeni sipariş",
  "notificationMessage": "Siparişin kargoya verildi.",
  "author": "Uygulama Adı",
  "image": "https://via.placeholder.com/64x64",
  "timeout": 8000,
  "serverId": 1,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı"
  },
  "timestamp": "2026-01-01T12:00:00+03:00"
}

Olası hatalar

HTTP	Kod	Açıklama
401	`authentication_required`	Bearer token gönderilmedi (`error_code` alanında döner).
401	`invalid_token`	Token bulunamadı veya süresi doldu.
401	`invalid_app`	Token'ın ait olduğu uygulama bulunamadı (`error_code`).
400	`missing_parameter`	Zorunlu bir parametre eksik.
400	`invalid_user_id`	`userId` pozitif bir tam sayı değil.
400	`title_too_long`	`title` 100 baytı aşıyor.
400	`message_too_long`	`message` 200 baytı aşıyor.
400	`author_too_long`	`author` 50 baytı aşıyor.
400	`invalid_timeout`	`timeout` 1000–30000 aralığında değil.
403	`access_denied`	Karakter token sahibinin hesabına ait değil.
500	`phone_notification_failed`	Bildirim oyun sunucusuna iletilemedi.

POST /notification/send-to-club

Bearer token

Club hesabına oyun içi bildirim

Belirtilen Club hesabına oyun içi sohbet bildirimi gönderir. Token ile yalnızca kullanıcının kendi hesabına gönderim yapılabilir. Mesajın başına uygulamanızın adı eklenir.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`clubId`	integer	Evet	Gövde	Club hesap kimliği; /me yanıtındaki `user.AccountID` ile aynı olmalıdır.
`serverId`	integer	Evet	Gövde	Sunucu kimliği. Şu anda yalnızca `1` desteklenir.
`messageType`	string	Evet	Gövde	`success`, `error`, `warning`, `gray` veya `normal`.
`messageText`	string	Evet	Gövde	En fazla 500 bayt.

Oyun sunucusu yanıta ek alanlar ekleyebilir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/notification/send-to-club" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "clubId=12345" \
  -d "serverId=1" \
  -d "messageType=normal" \
  --data-urlencode "messageText=Haftalık özetin hazır."

Örnek yanıt

JSON

{
  "message": "Notification sent successfully to club",
  "status": "sent",
  "clubId": 12345,
  "messageType": "normal",
  "messageText": "[Uygulama Adı] Haftalık özetin hazır.",
  "serverId": 1,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı"
  },
  "timestamp": "2026-01-01T12:00:00+03:00"
}

Olası hatalar

HTTP	Kod	Açıklama
401	`authentication_required`	Bearer token gönderilmedi (`error_code` alanında döner).
401	`invalid_token`	Token bulunamadı veya süresi doldu.
401	`invalid_app`	Token'ın ait olduğu uygulama bulunamadı (`error_code`).
400	`missing_parameter`	Zorunlu bir parametre eksik.
400	`invalid_message_type`	`messageType` izin verilen değerlerden biri değil.
400	`invalid_club_id`	`clubId` pozitif bir tam sayı değil.
400	`message_too_long`	`messageText` 500 baytı aşıyor.
403	`access_denied`	`clubId` token sahibinin hesabı değil.
500	`notification_failed`	Bildirim oyun sunucusuna iletilemedi.

Partner

Bankacılık (Partner)

Oyun içi ödeme alma ve transfer uç noktaları yalnızca RINA tarafından onaylanmış partner uygulamalara açıktır.

Onaylı uygulama gerekir Bu uç noktaları kullanabilmek için uygulamanızın ilgili sunucuda bankacılık kaydı (yetkili banka hesapları, vergi oranı, geri çağırma adresi) bulunmalıdır. Kayıt için destek talebi açın. Kaydı olmayan uygulamalar 401 alır.

Yalnızca sunucudan sunucuya transaction-status, transfer ve app-info uygulamanızın client_id ve client_secret değerleriyle doğrulanır. Bu çağrıları hiçbir zaman tarayıcıdan veya oyuncunun cihazından yapmayın; kimlik bilgilerini Authorization: Basic başlığında gönderin. initiate-payment ise kullanıcının OAuth ile verdiği Bearer token ile, yine kendi sunucunuzdan çağrılır.

POST /banking/initiate-payment

Bearer token · Partner

Ödeme başlat

Kullanıcının kendi karakterinden uygulamanızın banka hesabına bir ödeme işlemi oluşturur ve oyun sunucusuna iletir. Kullanıcının OAuth ile verdiği Bearer token ile çağrılır; uygulamanızın bu sunucu için onaylı bankacılık kaydı olmalıdır. İşlemin sonucunu transaction-status ile takip edin.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`amount`	integer	Evet	Gövde	Ödeme tutarı, 1 ile 1.000.000 arası.
`description`	string	Evet	Gövde	Oyuncuya gösterilecek açıklama.
`userId`	integer	Evet	Gövde	Ödemeyi yapacak karakter (/characters `UserID`). Token sahibinin aktif karakteri olmalıdır.
`serverId`	integer	Evet	Gövde	Sunucu kimliği. Şu anda yalnızca `1` desteklenir.
`bankId`	integer	Hayır	Gövde	Ödemenin yatırılacağı hesap; uygulamanızın yetkili hesaplarından (`bankIds`) biri olmalıdır. Varsayılan: ilk hesap.
`productInfo`	string	Hayır	Gövde	Ürün bilgisi; işlem kaydında saklanır.
`storeName`	string	Hayır	Gövde	Mağaza adı; işlem kaydında saklanır.

Vergi, uygulamanızın taxPercent değerine göre hesaplanır: taxAmount = amount × taxPercent / 100, totalAmount = amount + taxAmount. Bu alanlar transaction-status yanıtında döner.
Oyun sunucusuna o an ulaşılamazsa işlem yine de kaydedilir ve HTTP 202 ile status: "pending", transactionId, error ve note alanları döner.
transactionId değerini saklayın; durum sorgusu bu değerle yapılır.
Oyun sunucusu yanıta ek alanlar ekleyebilir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/banking/initiate-payment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "amount=2500" \
  --data-urlencode "description=Premium üyelik (30 gün)" \
  -d "userId=678" \
  -d "serverId=1" \
  --data-urlencode "storeName=Örnek Mağaza"

Örnek yanıt

JSON

{
  "message": "Payment initiated successfully",
  "status": "initiated",
  "clubId": 12345,
  "userId": 678,
  "amount": 2500,
  "description": "Premium üyelik (30 gün)",
  "serverId": 1,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı",
    "bankId": 4321,
    "callbackUrl": "https://example.com/rina/callback"
  },
  "timestamp": "2026-01-01T12:00:00+03:00",
  "transactionId": "TXN_20260101120000_1A2B3C4D"
}

Olası hatalar

HTTP	Kod	Açıklama
401	`authentication_required`	Bearer token gönderilmedi (`error_code`).
401	`invalid_token`	Token bulunamadı veya süresi doldu.
400	`missing_parameter`	Zorunlu bir parametre eksik.
400	`invalid_amount`	`amount` 1–1.000.000 aralığında değil.
401	`You can only initiate payments for your own characters`	Karakter token sahibine ait değil veya devre dışı (yalnızca `error` alanı).
401	`Invalid client ID`	Uygulamanızın bu sunucu için onaylı bankacılık kaydı yok (yalnızca `error` alanı).
400	`invalid_bank_id`	`bankId` uygulamanızın yetkili hesaplarından biri değil.
500	`transaction_create_failed`	İşlem kaydı oluşturulamadı.

GET /banking/transaction-status/{transactionId}

client_secret · Partner

İşlem durumu

Uygulamanızın başlattığı bir ödeme işleminin güncel durumunu döndürür. Yalnızca kendi client_id değerinizle oluşturulan işlemler sorgulanabilir.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`transactionId`	string	Evet	Yol	initiate-payment yanıtındaki `transactionId`.
`serverId`	integer	Evet	Sorgu	Sunucu kimliği. Şu anda yalnızca `1` desteklenir.
`client_id / client_secret`	string	Evet	Basic	`Authorization: Basic base64(client_id:client_secret)` (curl: `-u`).

status değerleri: pending, processing, completed, failed, cancelled; tanınmayan bir durumda unknown. transaction.statusCode aynı durumun sayısal karşılığıdır (0–4).
Kayıtlı geri çağırma adresinize (callbackUrl) bildirim yapılıp yapılmadığı transaction.callbackSent alanında görünür. Bildirimin içeriği bu dokümanda tanımlı değildir; ödemeyi teslim etmeden önce sonucu her zaman bu uç noktayla doğrulayın.

Örnek istek

curl

curl "https://www.rina-roleplay.com/gateway/api/v2/banking/transaction-status/TXN_20260101120000_1A2B3C4D?serverId=1" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Örnek yanıt

JSON

{
  "message": "Transaction status retrieved successfully",
  "transactionId": "TXN_20260101120000_1A2B3C4D",
  "status": "completed",
  "amount": 2500,
  "taxAmount": 125,
  "totalAmount": 2625,
  "description": "Premium üyelik (30 gün)",
  "productInfo": null,
  "storeName": "Örnek Mağaza",
  "createdAt": "<oluşturma zamanı>",
  "processedAt": "<işlenme zamanı>",
  "completedAt": "<tamamlanma zamanı>",
  "paymentMethod": "<ödeme yöntemi>",
  "playerName": "John_Doe",
  "failureReason": null,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı",
    "bankId": 4321
  },
  "transaction": {
    "transactionId": "TXN_20260101120000_1A2B3C4D",
    "clubId": 12345,
    "userId": 678,
    "amount": 2500,
    "taxAmount": 125,
    "totalAmount": 2625,
    "description": "Premium üyelik (30 gün)",
    "productInfo": null,
    "storeName": "Örnek Mağaza",
    "status": "completed",
    "statusCode": 2,
    "fromBankAccountId": 9876,
    "toBankAccountId": 4321,
    "paymentMethod": "<ödeme yöntemi>",
    "playerName": "John_Doe",
    "failureReason": null,
    "callbackSent": true,
    "callbackResponse": "<geri çağırma yanıtı>",
    "callbackStatusCode": 200,
    "createdAt": "<oluşturma zamanı>",
    "processedAt": "<işlenme zamanı>",
    "completedAt": "<tamamlanma zamanı>",
    "callbackAt": "<geri çağırma zamanı>"
  },
  "timestamp": "2026-01-01T12:05:00+03:00"
}

Olası hatalar

HTTP	Kod	Açıklama
400	`missing_credentials`	`client_id` veya `client_secret` gönderilmedi.
401	`Invalid client_id`	Uygulama bulunamadı veya aktif değil (yalnızca `error` alanı).
401	`Invalid client_secret`	`client_secret` hatalı (yalnızca `error` alanı).
400	`missing_parameter`	`serverId` eksik.
401	`Client not authorized for banking API on this server`	Uygulamanızın bu sunucu için onaylı bankacılık kaydı yok (yalnızca `error` alanı).
404	`transaction_not_found`	İşlem bulunamadı.
401	`You are not authorized to access this transaction`	İşlem başka bir uygulamaya ait (yalnızca `error` alanı).
405	`(boş gövde)`	İstek `GET` değil.

POST /banking/transfer

client_secret · Partner

Uygulama hesabından transfer

Uygulamanızın yetkili banka hesaplarından birinden belirtilen oyun içi banka hesabına para gönderir. Kullanıcı token'ı gerekmez; yalnızca uygulamanızın kimlik bilgileriyle, kendi sunucunuzdan çağrılmalıdır.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`toBankAccountId`	integer	Evet	Gövde	Paranın gönderileceği banka hesabı.
`amount`	integer	Evet	Gövde	Tutar, 1 ile 10.000.000 arası.
`description`	string	Evet	Gövde	Transfer açıklaması.
`serverId`	integer	Evet	Gövde	Sunucu kimliği. Şu anda yalnızca `1` desteklenir.
`fromBankAccountId`	integer	Hayır	Gövde	Kaynak hesap; uygulamanızın yetkili hesaplarından biri olmalıdır. Varsayılan: ilk hesap.
`client_id / client_secret`	string	Evet	Basic veya Gövde	Tercihen `Authorization: Basic` başlığıyla.

Kaynak hesabın bakiyesi istek anında kontrol edilir; yetersizse transfer başlatılmaz.
Hata durumunda da yanıtta transferId döner; destek taleplerinde bu değeri paylaşın.
Oyun sunucusu yanıta ek alanlar ekleyebilir.

Örnek istek

curl

curl -X POST "https://www.rina-roleplay.com/gateway/api/v2/banking/transfer" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "toBankAccountId=9876" \
  -d "amount=1500" \
  --data-urlencode "description=Turnuva ödülü" \
  -d "serverId=1"

Örnek yanıt

JSON

{
  "message": "Transfer completed successfully",
  "status": "completed",
  "fromBankId": 4321,
  "toBankAccountId": 9876,
  "amount": 1500,
  "description": "Turnuva ödülü",
  "serverId": 1,
  "appInfo": {
    "clientId": "YOUR_CLIENT_ID",
    "appName": "Uygulama Adı",
    "bankId": 4321,
    "callbackUrl": "https://example.com/rina/callback"
  },
  "timestamp": "2026-01-01T12:00:00+03:00",
  "transferId": 555,
  "transferLogId": 555
}

Olası hatalar

HTTP	Kod	Açıklama
400	`missing_credentials`	`client_id` veya `client_secret` gönderilmedi.
401	`Invalid client_id`	Uygulama bulunamadı veya aktif değil (yalnızca `error` alanı).
401	`Invalid client_secret`	`client_secret` hatalı (yalnızca `error` alanı).
400	`missing_parameter`	Zorunlu bir parametre eksik.
401	`Client not authorized for banking API`	Uygulamanızın bu sunucu için onaylı bankacılık kaydı yok (yalnızca `error` alanı).
400	`invalid_amount`	`amount` 1–10.000.000 aralığında değil.
400	`invalid_source_bank_id`	`fromBankAccountId` uygulamanızın yetkili hesaplarından biri değil.
404	`source_account_not_found`	Kaynak banka hesabı bulunamadı.
400	`insufficient_balance`	Kaynak hesapta yeterli bakiye yok.
500	`transfer_failed`	Transfer oyun sunucusunda tamamlanamadı; yanıtta `transferId` bulunur.
405	`(boş gövde)`	İstek `POST` değil.

GET /banking/app-info

client_secret · Partner

Bankacılık uygulama bilgisi

Uygulamanızın belirtilen sunucudaki bankacılık ayarlarını döndürür: yetkili banka hesapları, vergi oranı ve kayıtlı geri çağırma adresi.

Parametreler

Parametre	Tip	Zorunlu	Konum	Açıklama
`serverId`	integer	Evet	Sorgu	Sunucu kimliği. Şu anda yalnızca `1` desteklenir.
`client_id / client_secret`	string	Evet	Basic	`Authorization: Basic base64(client_id:client_secret)` (curl: `-u`).

bankId, bankIds listesindeki ilk (varsayılan) hesaptır.

Örnek istek

curl

curl "https://www.rina-roleplay.com/gateway/api/v2/banking/app-info?serverId=1" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Örnek yanıt

JSON

{
  "clientId": "YOUR_CLIENT_ID",
  "appName": "Uygulama Adı",
  "bankId": 4321,
  "bankIds": [4321, 4322],
  "taxPercent": 5,
  "callbackUrl": "https://example.com/rina/callback",
  "serverId": 1
}

Olası hatalar

HTTP	Kod	Açıklama
400	`missing_credentials`	`client_id` veya `client_secret` gönderilmedi.
401	`Invalid client_id`	Uygulama bulunamadı veya aktif değil (yalnızca `error` alanı).
401	`Invalid client_secret`	`client_secret` hatalı (yalnızca `error` alanı).
400	`missing_server_id`	`serverId` eksik.
401	`Client not authorized for banking API`	Uygulamanızın bu sunucu için onaylı bankacılık kaydı yok (yalnızca `error` alanı).
405	`(boş gövde)`	İstek `GET` değil.

Referans

Hata kodları

Hatalar JSON olarak döner. error alanı her zaman bulunur; bazı uç noktalar makine tarafından okunabilir error_code alanı da ekler. Uygulamanızda önce error_code, yoksa error değerini kontrol edin.

JSON

{
  "error": "Invalid character ID",
  "error_code": "access_denied"
}

HTTP	error / error_code	Anlamı
400	`missing_parameter`	Zorunlu parametre eksik. `error` alanında parametre adı yazar.
400	`validation_error`	Parametre eksik veya geçersiz (`/characters`).
400	`invalid_message_type`, `invalid_user_id`, `invalid_club_id`, `invalid_timeout`	Parametre değeri izin verilen aralıkta değil.
400	`message_too_long`, `title_too_long`, `author_too_long`	Metin uzunluk sınırını aşıyor.
400	`missing_credentials`, `missing_server_id`	Partner uç noktalarında kimlik bilgisi veya `serverId` eksik.
400	`invalid_amount`, `invalid_bank_id`, `invalid_source_bank_id`, `insufficient_balance`	Bankacılık isteği geçersiz.
400	`unknown_platform`, `server_not_supported`	Sunucu bu uç nokta için desteklenmiyor (`/characters`).
401	`missing_bearer`	Bearer token gönderilmedi (`/me`, `/characters`).
401	`authentication_required`	Bearer token gönderilmedi (bildirim uç noktaları).
401	`invalid_token`	Token geçersiz veya süresi dolmuş; kullanıcıyı yeniden yetkilendirin.
401	`invalid_app`	Token'ın ait olduğu uygulama bulunamadı.
401	(yalnızca `error` metni)	Bankacılık uç noktalarında uygulama onaysız, kimlik bilgisi hatalı veya kaynak size ait değil. Ayrıntı için ilgili uç noktaya bakın.
403	`access_denied`	Kaynak token sahibine ait değil.
404	`server_not_found`, `account_not_found`, `transaction_not_found`, `source_account_not_found`	İstenen kayıt bulunamadı.
404	(çeşitli)	Bilinmeyen uç nokta.
405	(boş gövde)	Yanlış HTTP metodu.
500	`notification_failed`, `phone_notification_failed`, `transfer_failed`	İstek oyun sunucusunda tamamlanamadı; daha sonra tekrar deneyin.
500	`transaction_create_failed`	Ödeme işlemi kaydedilemedi.
500	`Internal server error`	Beklenmeyen sunucu hatası.

OAuth token hataları (invalid_client, unsupported_grant_type, invalid_redirect_uri, invalid_code, code_used, code_expired, invalid_refresh_token, refresh_token_expired) için /oauth/token bölümüne bakın.

Geliştirici API

Genel bakış

OAuth 2.0 akışı

Kullanıcıyı yetkilendirme sayfasına yönlendirin

Geri dönüşü karşılayın

Kodu token ile değiştirin

API'yi çağırın

Token yenileme

Örnek istek

Örnek yanıt

Yetkilendirme isteği

Parametreler

Örnek istek

Örnek yanıt

Token al ve yenile

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Kapsamlar

Uç noktalar

Sunucu listesi

Parametreler

Örnek istek

Örnek yanıt

Yetkilendiren kullanıcı

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Karakterler

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Karaktere oyun içi bildirim

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Karakterin telefonuna bildirim

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Club hesabına oyun içi bildirim

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Bankacılık (Partner)

Ödeme başlat

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

İşlem durumu

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Uygulama hesabından transfer

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Bankacılık uygulama bilgisi

Parametreler

Örnek istek

Örnek yanıt

Olası hatalar

Hata kodları