Bi'öğrenci OAuth Geliştirici Dokümantasyonu

1. Bi'öğrenci İle Giriş Yap (OAuth 2.0)

Uygulamanıza üye olmak veya giriş yapmak isteyen öğrencileri Bi'öğrenci üzerinden doğrulayın ve temel bilgilerine (ad, e-posta, öğrenci durumu vs.) güvenle erişin.

Entegrasyon Kod Örnekleri

Platformunuza uygun yöntemi seçin.

A Yetkilendirme Bağlantısı Oluşturun

Kullanıcının "Bi'öğrenci ile Giriş Yap" butonuna tıkladığında yönlendirileceği adres. Gerekli yetkileri (scope) aralarında boşluk bırakarak belirtebilirsiniz.

https://biogrenci.com/oauth/authorize?
                  response_type=code&
                  client_id={BİZE_AİT_CLIENT_ID}&
                  redirect_uri=https://siteniz.com/oauth/callback&
                  scope=profile%20student_status%20email&
                  state={GUVENLIK_KODU}

Not: state parametresi CSRF koruması için gereklidir.

B Access Token Alın

Kullanıcı hesabına giriş yapıp izin verdiğinde, verdiğiniz dönüş URL'sine (redirect_uri) ?code=XYZ&state=... parametreleriyle yönlendirilir. Code'u token ile takas edin.

curl -X POST "https://biogrenci.com/api/oauth/token" \
                  -H "Content-Type: application/json" \
                  -d '{
                    "grant_type": "authorization_code",
                    "client_id": "{BİZE_AİT_CLIENT_ID}",
                    "client_secret": "{BİZE_AİT_CLIENT_SECRET}",
                    "redirect_uri": "https://siteniz.com/oauth/callback",
                    "code": "{DONEN_CODE_DEGERI}"
                  }'

Bu istek access_token (genellikle 24 saat geçerli) ve refresh_token döndürür.

C Token Yenileme (Refresh)

access_token'in süresi dolduğunda, refresh_token ile yeni bir access token alın.

curl -X POST "https://biogrenci.com/api/oauth/token" \
                  -H "Content-Type: application/json" \
                  -d '{
                    "grant_type": "refresh_token",
                    "client_id": "{BİZE_AİT_CLIENT_ID}",
                    "client_secret": "{BİZE_AİT_CLIENT_SECRET}",
                    "refresh_token": "{ELINIZDEKI_REFRESH_TOKEN}"
                  }'

Her refresh yapıldığında eski refresh token yanar ve yeni bir refresh token verilir (Token Rotasyonu).

A PKCE Kodları Üretin (SPA & Mobil için Zorunlu)

Tarayıcı tabanlı uygulamalarda (React, Angular vs.) Secret güvenlik riski olduğundan PKCE (Proof Key for Code Exchange) kullanılır. Arka planda rastgele bir code_verifier dizgesi oluşturun ve SHA-256 algoritmasıyla şifreleyerek code_challenge elde edin.

B Yetkilendirme Bağlantısı

Bağlantıda PKCE parametreleri zorunludur.

https://biogrenci.com/oauth/authorize?
                  response_type=code&
                  client_id={BİZE_AİT_CLIENT_ID}&
                  redirect_uri=http://localhost:3000/callback&
                  scope=profile%20student_status&
                  state={GUVENLIK_KODU}&
                  code_challenge={PKCE_HAsh}&
                  code_challenge_method=S256

UserInfo (Kullanıcı Bilgisi) İsteği

Elde ettiğiniz access_token ile kullanıcının izin verdiği bilgileri almak için istek atılır. Dönecek alanlar istediğiniz scope (kapsam) türüne göre değişir.

curl -X GET "https://biogrenci.com/api/oauth/userinfo" \
                  -H "Authorization: Bearer {ELINIZDEKI_ACCESS_TOKEN}"

Yetki Kapsamları (Scopes) Nedir?

Giriş işlemi esnasında URL'deki scope= alanına yazdığınız anahtar kelimelerdir. Veri güvenliği gereği sadece uygulamanızın **gerçekten ihtiyacı olan** kapsamları istemelisiniz.

Scope Adı	Hassasiyet	UserInfo Apisinden Dönecek Alanlar
`openid`	Düşük	`sub` (Benzersiz kullanıcı ID'si)
`profile`	Düşük	`name` (Ad Soyad), `first_name`, `last_name`, `phone`, `phone_verified`, `date_of_birth`, `gender`, `avatar` (Profil resmi linki)
`email`	Düşük	`email`, `email_verified`
`student_status`	Orta	`student_verified` (Kişi sistemimizde hala doğrulanmış m?), `student_type` (Örn: lisans, yüksek lisan vb.)
`student`	Eski Sistem	Eski API'ler için `student.is_verified` olarak obje döndürür.
`education`	Orta	Eğitim detaylarını `education` objesi altında döner: (university isimleri, faculty, department, program isimleri, class_level vb.)
`verification`	Hassas	`verification.tckn` (Türkiye Cumhuriyeti Kimlik Numarası gibi ekstra özel bilgiler)
`opportunities.read`	Düşük	Bi'öğrenci fırsatlarını listelemeye ve bu token sahibi kullanıcı adına kod almaya yarayan yetki (Partner API). Detaylar aşağıda.

Tam Kapsamlı (Profile, Email, Student_Status, Education) UserInfo Örneği

{
                  "sub": 1234,
                  "name": "Ahmet Yılmaz",
                  "first_name": "Ahmet",
                  "last_name": "Yılmaz",
                  "phone": "5551234567",
                  "phone_verified": true,
                  "date_of_birth": "2000-05-15",
                  "gender": "male",
                  "avatar": "https://s3.url/...",
                  "email": "ahmet@example.com",
                  "email_verified": true,
                  "student_verified": true,
                  "student_type": "lisans",
                  "education": {
                      "university": "Boğaziçi Üniversitesi",
                      "faculty": "Mühendislik Fakültesi",
                      "department": "Bilgisayar Mühendisliği",
                      "program": null,
                      "class_level": "3",
                      "education_type": "Örgün",
                      "education_duration_years": 4,
                      "city": {
                          "id": 34,
                          "name": "İstanbul"
                      }
                  }
                }

2. Fırsatları Platformunuzda Listeleme (Partner API)

Uygulamanıza üye olan veya sizin sisteminizi kullanan gençlerin, platformunuzu terk etmeden aktif Bi'öğrenci fırsatlarını görebilmesi içindir.

Bilgi: Fırsatları listelemek (GET) herkese açıktır ve token gerektirmez. Ancak kullanıcılarınızın bir kod (claim) alabilmesi için OAuth Login akışını tamamlayıp opportunities.read scope'u aktif edilmiş bir hesaba ait Access Token ile istek atması zorunludur.

Mevcut Uç Noktalar (Endpoints)

Base URL: https://biogrenci.com/api/partner
Header: Authorization: Bearer {token} (Sadece Claim işlemi için zorunludur)

Metod	Endpoint	Açıklama
GET	`/opportunities`	Aktif fırsatların sayfalanmış (paginated) halini getirir.
GET	`/opportunities/{id}`	Sadece belirtilen id'li fırsatın tüm metin ve kural detaylarını getirir.
GET	`/opportunities/categories`	Sistemdeki kategori filtrelerini ID'leriyle getirir (Yeme İçme, Giyim vs).
GET	`/opportunities/brands`	Sistemdeki marka filtrelerini getirir.

GET /opportunities Liste Parametreleri

URL sonuna sorgu dizisi (query string) olarak ekleyebilirsiniz (Örnek: ?type=kupon&sort=popular)

category_id (int) Belirli kategoriye göre listele.
brand_id (int) Belirli markaya göre listele.
type (string) Fırsat tipi: kupon, affiliate, qr
search (string) Başlık/Açıklamada metin arama.
sort (string) Sıralama şekli: featured, popular, newest, alphabetical
page, per_page Sayfalama ayarları. (Varsayılan per_page: 20)

3. Fırsatlardan Yararlanma (Kod Alma)

Listenizden bir fırsatı seçen kullanıcının, sizin uygulamanız içindeyken indirim kuponu talep etmesi (claim) özelliğidir. Yanıt, fırsatın tipine (type) göre farklı alanlar içerir.

Kod Talep Et

curl -X POST "https://biogrenci.com/api/partner/opportunities/{id}/claim" \
                  -H "Authorization: Bearer {KULLANICININ_ACCESS_TOKEN}" \
                  -H "Accept: application/json"

kupon Kupon Tipi Fırsat Yanıtı

Kullanıcıya bir kupon kodu verilir. Kopyalama butonu ile gösterilmelidir. Eğer redirect_url alanı varsa altına "Fırsata Git" butonu koyun.

{
      "success": true,
      "data": {
        "type": "kupon",
        "coupon_code": "XYZ123ABC",
        "claimed_before": false,
        "expires_at": "2026-10-01T23:59:59Z",
        "redirect_url": "https://marka.com/ogrenci?utm_source=biogrenci",
        "utm_tracking": true
      }
    }

coupon_code → Kullanıcıya gösterilecek kupon kodu.
redirect_url (opsiyonel) → Kuponun kullanılacağı marka sitesi linki. Varsa "Fırsata Git" butonu koyun.
expires_at → Kuponun son kullanma tarihi.
claimed_before → true ise kullanıcı bu kuponu daha önce almış.

qr QR Kod Tipi Fırsat Yanıtı

Kullanıcıya QR kodu gösterilmelidir. qr_code alanı SVG formatındadır ve doğrudan HTML olarak render edilebilir.

{
      "success": true,
      "data": {
        "type": "qr",
        "coupon_code": "QR789DEF",
        "qr_code": "<svg ...>...</svg>",
        "claimed_before": false,
        "expires_at": "2026-12-31T23:59:59Z"
      }
    }

qr_code → SVG formatında QR kod. HTML'e doğrudan yerleştirin.
coupon_code → QR kodun altında metin olarak da gösterilebilir.

affiliate Affiliate Tipi Fırsat Yanıtı

Kupon kodu yoktur. Kullanıcıya "Fırsata Git" butonu gösterilmeli ve redirect_url adresine yönlendirilmelidir.

{
      "success": true,
      "data": {
        "type": "affiliate",
        "redirect_url": "https://marka.com/ogrenci-indirimi",
        "claimed_before": false
      }
    }

redirect_url → Kullanıcıyı indirimli sayfaya yönlendiren link.

Başarısız Claim Yanıtı

{
      "success": false,
      "message": "Bu fırsatın kuponları tükenmiş.",
      "error": "COUPONS_DEPLETED"
    }

unauthenticated — Token eksik veya geçersiz.
insufficient_scope — Token yetki kapsamı yetersiz.
COUPONS_DEPLETED — Kuponlar tükendi.
OPPORTUNITY_EXPIRED — Fırsatın süresi dolmuş.
USER_USAGE_LIMIT_REACHED — Kullanıcı limiti dolmuş.
student_verification_required — Öğrenci doğrulaması gerekiyor.

Genel Hata Kodları Sonuçları

Aşağıdaki HTTP Error tablosu sistemde oluşabilecek hata türlerini açıklar.

HTTP	Hata Kodu	Açıklama	Çözüm & Aksiyon
400	`invalid_request`	Eksik veya geçersiz parametre	Bağlantı URL'nizi veya Post nesnenizi kontrol edin.
400	`invalid_grant`	Code veya Refresh Token süresi dolmuş veya hatalı.	Access token yenileme işlemi başarısız olduğu için baştan `authorize` girişi istenir.
401	`unauthenticated`	Access token eksik veya süresi dolmuş	Kullaniciya ait refresh token kullanarak `access_token` ı yenileyin.
403	`insufficient_scope`	Token bu endpoint için yetkisiz (Örn: fırsat çekemiyor)	`authorize` linkinizdeki `scope=` alanında doğru/esik yetkiler var mı inceleyin.
429	`too_many_requests`	Saniye başı API Limit aşıldı	`Retry-After` header değerine kadar saniye bazında bekleyin.

Dokümantasyon