API Kontratları (API Contracts & Specifications)

Bu doküman, Humindx platformunun B2C (Mobil), B2B (Kurumsal Panel) ve Partner (3. Parti API) kanallarındaki tüm endpoint'lerin istek/yanıt sözleşmelerini tanımlar. Frontend ve Backend ekiplerinin birbirini beklemeden paralel geliştirme yapabilmesi için kesin kontratlar sunar.

Kapsam Uyarısı: Bu doküman, endpoint imzalarını ve payload yapılarını kapsar. Trafik yönlendirme ve güvenlik katmanı için api-gateway.md, iş mantığı detayları için b2c-engine.md ve b2b-tenant-os.md dosyalarına bakınız.

---

1. Genel Kurallar (Conventions)

Kural	Standart
Base URL	https://api.humindx.com/api/v1
Protokol	HTTPS (REST), WSS (WebSocket — sadece B2C Chat)
Auth	JWT Bearer Token (B2C/B2B), API Key + OAuth2 (Partner)
Format	JSON (UTF-8)
Tarih/Saat	ISO 8601, UTC (2026-04-15T10:30:00Z)
Hata Formatı	{ "error": { "code": "CONSENT_REQUIRED", "message": "..." } }
Sayfalama	Cursor-based: ?cursor=abc&limit=20
Versiyonlama	URL path: /api/v1/, /api/v2/

---

2. B2C Endpoints (Mobil Uygulama)

2.1. Kimlik Doğrulama (Auth)

POST /b2c/auth/register

Yeni kullanıcı kaydı oluşturur.

Request:

{
  "email": "can@example.com",
  "password": "hashed_client_side",
  "locale": "tr-TR"
}

Response (201 Created):

{
  "user_id": "uuid-101",
  "access_token": "jwt_token",
  "refresh_token": "refresh_token",
  "genome_id": "hash_xyz"
}

POST /b2c/auth/login

Mevcut kullanıcı girişi.

DELETE /b2c/auth/account

GDPR/KVKK "Unutulma Hakkı". Hesabı ve tüm PII'yi kalıcı olarak siler. B2B tarafında Statistical Ghosting (Anonim Düğüm) tetiklenir.

Response (200 OK):

{
  "status": "deleted",
  "ghost_node_created": true,
  "message": "Hesabınız ve kişisel verileriniz kalıcı olarak silindi."
}

---

2.2. Mikro-Keşif ve Onboarding

GET /b2c/discovery/quick-scan

Onboarding'deki A/B görsel ikilemlerini döndürür.

Response (200 OK):

{
  "scan_id": "scan_001",
  "questions": [
    {
      "id": "q1",
      "type": "visual_choice",
      "option_a": { "image_url": "...", "label": "Planlı tatil" },
      "option_b": { "image_url": "...", "label": "Anlık macera" }
    }
  ],
  "total_questions": 10
}

POST /b2c/discovery/quick-scan/submit

Kullanıcının Quick-Scan yanıtlarını gönderir. Başlangıç Çapası ($S_0$) hesaplanır.

Request:

{
  "scan_id": "scan_001",
  "answers": [
    { "question_id": "q1", "selected": "option_b" }
  ]
}

Response (200 OK):

{
  "anchor_scores": {
    "openness": 72,
    "conscientiousness": 55,
    "extraversion": 68,
    "agreeableness": 80,
    "neuroticism": 35
  },
  "confidence_score": 0.14,
  "next_step": "proof_loop"
}

---

2.3. Sohbet ve Sisli Sohbet (Chat & Misty Chat)

POST /b2c/chat/init

Yeni bir sohbet oturumu başlatır. Sisli Sohbet'te ajan tipi frontend'e gizlenir.

Request:

{
  "scenario_type": "misty_chat",
  "scenario_category": "work_conflict"
}

Response (200 OK):

{
  "session_id": "sess_8472",
  "status": "READY",
  "websocket_url": "wss://api.humindx.com/ws/chat/sess_8472"
}

Not: agent_type (SHADOW, MIRROR vb.) yanıtta yer almaz — Sisli Sohbet gizliliği korunur.

WebSocket Mesaj Formatı (wss://api.humindx.com/ws/chat/{session_id})

Client → Server:

{
  "type": "USER_MESSAGE",
  "content": "Bana çok haksızlık yaptın!",
  "timestamp": "2026-04-15T10:30:00Z"
}

Server → Client (Streamed):

{
  "type": "AGENT_MESSAGE",
  "content": "Öyle mi düşünüyorsun? Nedenini açıkla.",
  "is_final": true
}

POST /b2c/chat/{session_id}/end

Sohbeti bitirir ve Cold Path analizini tetikler.

Response (202 Accepted):

{
  "session_id": "sess_8472",
  "status": "ANALYZING",
  "message": "Psikometrik analiz başlatıldı."
}

Server → Client (WSS Push — Analiz Tamamlandığında):

{
  "type": "FOG_LIFTED",
  "agent_type": "SHADOW",
  "tested_trait": "agreeableness",
  "shift_summary": "Baskı altında uyumluluk skorun -2.5 puan kaydı.",
  "suggested_label": "[PRO]",
  "rooms_affected": {
    "DISCOVERY": { "agreeableness": -2.5 },
    "PROFESSIONAL": { "agreeableness": 0 }
  }
}

---

2.4. Profil ve Genom

GET /b2c/profile/genome

Kullanıcının tüm Bağlam Odalarındaki güncel skorlarını döndürür.

Response (200 OK):

{
  "genome_id": "hash_xyz",
  "confidence_score": 0.72,
  "rooms": {
    "PROFESSIONAL": {
      "big_five": {
        "openness": 72, "conscientiousness": 58,
        "extraversion": 65, "agreeableness": 77, "neuroticism": 38
      },
      "riasec": "IAS"
    },
    "SOCIAL": {
      "big_five": { "openness": 70, "conscientiousness": 52, "...": "..." }
    },
    "DISCOVERY": { "...": "..." }
  },
  "last_updated": "2026-04-15T10:30:00Z"
}

GET /b2c/profile/lineage/{trait_id}

Belirli bir trait'in Veri Soyu'nu (Data Lineage) döndürür — Veri Röntgeni ekranı için.

Response (200 OK):

{
  "trait_id": "bigfive_agreeableness",
  "current_score": 77,
  "history": [
    {
      "event_id": "evt_001",
      "timestamp": "2026-04-10T14:00:00Z",
      "source": "SCENARIO_COMPLETED",
      "label": "[PRO]",
      "shift_value": -2.5,
      "actor": "LLM",
      "room": "DISCOVERY"
    },
    {
      "event_id": "evt_002",
      "timestamp": "2026-04-12T09:00:00Z",
      "source": "BRIDGE_TRANSFER",
      "shift_value": 5.0,
      "actor": "USER",
      "room": "PROFESSIONAL",
      "metadata": { "transferred_from": "SOCIAL" }
    }
  ]
}

---

2.5. Senaryo Etiketi ve Transfer

PATCH /b2c/scenarios/{scenario_id}/label

Kullanıcının AI'nın önerdiği senaryo etiketini manuel olarak değiştirmesi.

Request:

{
  "new_label": "[PRO]",
  "original_label": "[SOCIAL]"
}

Response (200 OK):

{
  "scenario_id": "sim_8472",
  "label": "[PRO]",
  "integrity_penalty": -3,
  "new_integrity_score": 88,
  "audit_event_id": "evt_override_001"
}

POST /b2c/profile/bridge-transfer

Pozitif Transfer Köprüsü — Sosyal/Keşif odasından Profesyonel odaya trait transferi.

Request:

{
  "trait_id": "bigfive_agreeableness",
  "source_room": "SOCIAL",
  "target_room": "PROFESSIONAL"
}

Response (200 OK):

{
  "transfer_id": "bridge_001",
  "trait_id": "bigfive_agreeableness",
  "transferred_score": 85,
  "integrity_penalty": -15,
  "new_integrity_score": 73,
  "audit_event_id": "evt_bridge_001"
}

---

2.6. Psikometrik Pasaport

POST /b2c/passport/share

Paylaşım linki (Signed JWT URL) oluşturur.

Request:

{
  "granted_level": 1,
  "expires_in_days": 30
}

Response (201 Created):

{
  "share_url": "https://humindx.com/p/token_abc123",
  "qr_code_url": "https://api.humindx.com/qr/token_abc123.png",
  "expires_at": "2026-05-15T00:00:00Z",
  "revoke_id": "share_001"
}

DELETE /b2c/passport/share/{revoke_id}

Paylaşım linkini iptal eder.

POST /b2c/passport/export-pdf (Premium)

Doğrulanmış PDF raporu oluşturur.

Response (202 Accepted):

{
  "export_id": "pdf_001",
  "status": "GENERATING",
  "estimated_seconds": 15,
  "webhook_on_complete": true
}

---

2.7. Consent (İzin Yönetimi)

GET /b2c/consent/grants

Kullanıcının aktif izin listesini döndürür.

Response (200 OK):

{
  "grants": [
    {
      "grant_id": "grant_001",
      "tenant_name": "Acme Corp",
      "tenant_id": "tenant_101",
      "level": 3,
      "workspace": "talent",
      "granted_at": "2026-04-01T09:00:00Z"
    }
  ]
}

DELETE /b2c/consent/grants/{grant_id}

Belirli bir kuruma verilen izni geri çeker (Revocation). WebSocket üzerinden B2B paneline CONSENT_REVOKED event'i anında iletilir.

---

3. B2B Endpoints (Kurumsal Panel)

3.1. İşe Alım Modülü (Hiring)

GET /b2b/hiring/candidates

Başvuran adayların listesini döndürür. Consent Engine strip uygulanır.

Response (200 OK):

{
  "candidates": [
    {
      "user_id": "uuid-84",
      "display_name": "Can Y.",
      "culture_fit_score": 88,
      "integrity_score": 92,
      "confidence_badge": "AI_VERIFIED",
      "consent_level": 1,
      "applied_at": "2026-04-10T14:00:00Z"
    }
  ],
  "cursor": "next_page_token"
}

POST /b2b/hiring/candidates/{user_id}/shadow-interview

Aday için Shadow Interview oturumu başlatır.

Response (201 Created):

{
  "interview_id": "si_001",
  "status": "PENDING_CANDIDATE",
  "notification_sent": true
}

POST /b2b/hiring/candidates/{user_id}/hire

Adayı işe alır — Onboarding Geçişi'ni tetikler.

Response (202 Accepted):

{
  "status": "ONBOARDING_INITIATED",
  "event": "CANDIDATE_HIRED",
  "candidate_notified": true,
  "awaiting_consent_upgrade": true
}

3.2. Yetenek Yönetimi Modülü (Talent)

GET /b2b/talent/teams/{team_id}/topology

Ekibin psikometrik haritasını döndürür.

Response (200 OK):

{
  "team_id": 5,
  "team_name": "Pazarlama",
  "members": [
    {
      "display_name": "Can Y.",
      "role": "Pazarlama Uzmanı",
      "big_five_summary": { "dominant": "Openness", "lowest": "Neuroticism" },
      "consent_level": 3,
      "is_ghost_node": false
    }
  ],
  "team_gaps": ["Uygulayıcı (Implementer) eksik"],
  "turnover_risk": "LOW",
  "culture_dna_version": "v2"
}

GET /b2b/talent/members/{user_id}/management-recipe

Yönetim Reçetesi — Level 3 izni gerektirir.

Response (200 OK):

{
  "user_id": "uuid-84",
  "recipe": "Can, kriz anlarında net talimatlar ve onay bekler. Belirsiz bırakılmamalıdır. Yazılı check-list'ler motivasyonunu artırır.",
  "confidence_badge": "AI_VERIFIED",
  "integrity_score": 92,
  "data_scope": "PROFESSIONAL_ROOM_ONLY"
}

Response (403 Forbidden — İzin yetersiz):

{
  "error": {
    "code": "INSUFFICIENT_CONSENT",
    "message": "Çalışan Level 3 izni vermemiştir. Yönetim Reçetesi görüntülenemez.",
    "current_level": 1
  }
}

3.3. Kültür DNA Yönetimi

GET /b2b/culture-dna

Şirketin güncel Kültür DNA şablonunu döndürür.

PUT /b2b/culture-dna

Kültür DNA şablonunu günceller. Eski versiyon otomatik arşivlenir.

Request:

{
  "ideal_profile": {
    "openness_weight": 0.3,
    "conscientiousness_weight": 0.4,
    "extraversion_weight": 0.1,
    "agreeableness_weight": 0.15,
    "neuroticism_weight": 0.05
  },
  "riasec_target": "ECS"
}

Response (200 OK):

{
  "version": "v3",
  "previous_version": "v2",
  "effective_date": "2026-04-15T00:00:00Z",
  "auto_recalculate": false,
  "message": "Kültür DNA güncellendi. Mevcut ekip skorları yeniden hesaplanmadı. 'Takımı Yeniden Değerlendir' butonunu kullanabilirsiniz."
}

---

4. Partner Endpoints (3. Parti API Lisanslama)

4.1. Uyum Skoru Sorgulama

GET /partner/users/{user_id}/fit-score

Kullanıcının partner uygulamaya verdiği izin kapsamında uyum skorunu döndürür.

Headers: Authorization: Bearer <user_oauth_token>, X-API-Key: <partner_key>

Response (200 OK):

{
  "user_id": "uuid-101",
  "scope": "read:social_fit_score",
  "social_fit": {
    "compatibility_score": 78,
    "dominant_trait": "Openness",
    "communication_style": "Empatik ve dinleyici"
  }
}

4.2. Webhook Kayıt

POST /partner/webhooks

Partner'ın event bildirim URL'sini kaydeder.

Request:

{
  "url": "https://partner-app.com/humindx/webhook",
  "events": ["consent.revoked", "profile.updated.major", "account.deleted"],
  "secret": "hmac_shared_secret"
}

---

5. Ortak Hata Kodları

HTTP Status	Error Code	Açıklama
400	INVALID_PAYLOAD	İstek gövdesi şemaya uymuyor.
401	TOKEN_EXPIRED	JWT süresi dolmuş.
403	INSUFFICIENT_CONSENT	Kullanıcı gerekli izin seviyesini vermemiş.
403	ROLE_NOT_AUTHORIZED	RBAC yetkisi yetersiz (Örn: Recruiter Yönetim Reçetesi istedi).
404	USER_NOT_FOUND	Kullanıcı bulunamadı veya hesabı silinmiş (Ghost Node).
429	RATE_LIMIT_EXCEEDED	Rate limit aşıldı. Retry-After header'ı döner.
503	LLM_UNAVAILABLE	Harici LLM sağlayıcısı yanıt vermiyor. Yeniden deneyin.

---

Son Güncelleme: 2026-04-15 — B2C, B2B ve Partner endpoint kontratları, payload örnekleri ve hata kodları tanımlandı.