Dokümantasyon

Ürünleşme, faturalandırma, destek ve API'yi tek sayfada öğrenin.

Ürünleşme

Segmento, işlem verilerinizi eyleme dönüştürülebilir müşteri segmentlerine çeviren bir müşteri zekâsı platformudur. RFM analizi, AI tabanlı kümeleme, churn tahmini ve çok kanallı otomasyonları tek bir akışta birleştirir — veri bilimcisine ihtiyaç duymadan.

Genel Bakış

Segmento çok kiracılı (multi-tenant) bir mimariye sahiptir. Tüm kaynaklar aşağıdaki hiyerarşi içinde organize edilir; API ve panel bu yapıyı paylaşır.

Organization — kiracı ve faturalandırma birimi. Plan, kotalar ve ekip üyeleri burada tanımlanır.
Project — bir veri kümesi ve onun segmentasyon dünyası. API anahtarları proje kapsamlıdır.
Files / Customers — yüklenen ya da API ile gönderilen ham veriler ve bunlardan türeyen müşteri profilleri.
Segments — kümeleme veya kural tabanlı tanımlı müşteri grupları.
Automations / Actions — segmentlere bağlı, çok kanallı tetiklenen eylemler.

Temel Kavramlar

API yanıtlarında ve panelde karşılaşacağınız temel müşteri alanları:

Alan	Açıklama
`rfm_recency_days`	Son işlemden bu yana geçen gün sayısı (Recency).
`rfm_frequency`	Toplam işlem/sipariş sayısı (Frequency).
`rfm_monetary`	Toplam parasal değer (Monetary).
`churn_score`	0–1 arası kayıp (churn) olasılığı.
`churn_risk`	`low` · `medium` · `high` kategorisi.
`abc_category`	Değer bazlı ABC sınıfı: `A` · `B` · `C`.
`uplift_score`	Bir kampanyanın bu müşteride yaratacağı tahmini ek etki.
`segment_label`	Müşterinin atandığı segmentin etiketi.

ML Yetenekleri

Engine (ML katmanı) her proje için aşağıdaki analizleri üretir:

RFM analizi — müşteri başına recency / frequency / monetary ve iade oranı.
K-Means segmentasyon — otomatik k seçimi (knee/elbow + silhouette) ile kümeleme.
Churn tahmini — churn_score ve risk kategorisi.
Uplift modelleme — kampanya etkisini maksimize edecek hedefleme.
Benzer müşteri — pgvector embedding üzerinde en yakın müşteriler.
Hibrit kural filtresi — kümeleme + manuel kuralları birleştiren segmentler.
ABC analizi — değer bazlı müşteri sınıflandırması.

Proje Yaşam Döngüsü

Her proje aynı boru hattından (pipeline) geçer:

Ingestion — ham veri alınır, doğrulanır ve şemaya eşlenir.
Segmentation — RFM + K-Means ile müşteriler segmentlere ayrılır.
Predictive — churn / uplift skorları hesaplanır (opsiyonel).
Action — segmentlere bağlı kampanya/otomasyon tetiklenir (opsiyonel).

Veri iki yoldan girer: panelden CSV/XLSX yükleme ya da API ile gönderme (POST /api/v1/ingest). Her ikisi de aynı işleme kuyruğunu besler.

Entegrasyonlar

Eylemler (kampanya/otomasyon) aşağıdaki kanallar üzerinden iletilir. Her kanal için gereken kimlik bilgileri:

Kanal	Gerekli alanlar
`custom_webhook`	`url`
`sendgrid`	`apiKey`
`mailchimp`	`apiKey`, `listId`
`amazon_ses`	`accessKeyId`, `secretAccessKey`, `region`
`twilio`	`accountSid`, `authToken`
`messagebird`	`apiKey`
`slack`	`webhookUrl`
`teams`	`webhookUrl`

Gizli alanlar (apiKey, authToken, secretAccessKey) okuma sırasında [REDACTED] olarak maskelenir ve asla geri döndürülmez.

Faturalandırma

Planlar ve Kotalar

Ücretsiz başlayın, hazır olduğunuzda ölçeklendirin. Tüm kotalar organizasyon bazındadır.

	Free	Starter	Pro	Enterprise
Aylık	$0	$29	$99	$200
Yıllık (ay başına)	$0	$24	$79	$189
Satır (rows)	500K	10M	100M	Sınırsız
Müşteri profili	5.000	50.000	500.000	Sınırsız
Model çalıştırma	5	50	500	Sınırsız
GenAI işlemi	5	50	500	Sınırsız
Otomasyon	2	10	50	Sınırsız
Depolama	0,5 GB	5 GB	50 GB	500 GB
Ekip koltuğu	1	5	25	Sınırsız

Doğrulanacak

Enterprise fiyatı landing sayfasıyla ($200/ay · $189/yıl) uyumlu gösterilmiştir; ancak faturalandırma kaynağında (plan-limits.ts) Enterprise null (“iletişime geçin”) olarak tanımlıdır. Yayından önce bu çelişki netleştirilmelidir.

Kullanım Ölçümü

Her metrik şu şekilde hesaplanır:

Metrik	Nasıl hesaplanır
`rows`	Durumu `completed` olan dosyaların `rowCount` toplamı.
`storageGb`	Yüklenen dosyaların `sizeBytes` toplamı ÷ 1024³.
`automations`	Aktif otomasyon sayısı.
`teamSeats`	Organizasyon üye sayısı.
`profiles`	Engine'den proje başına `total_customers` toplamı.
`modelRuns` / `genaiOps`	Organizasyonun `currentUsage` sayaçları.

GET /api/organizations/:orgId/usagejson

{
  "plan": "free",
  "data": {
    "rows":        { "used": 250000, "limit": 500000 },
    "profiles":    { "used": 3200,   "limit": 5000 },
    "automations": { "used": 1,      "limit": 2 },
    "modelRuns":   { "used": 3,      "limit": 5 },
    "genaiOps":    { "used": 0,      "limit": 5 },
    "storageGb":   { "used": 0.25,   "limit": 0.5 },
    "teamSeats":   { "used": 1,      "limit": 1 }
  }
}

Depolama ve model çalıştırma limitleri aşıldığında istek 429 ile reddedilir.

Abonelik Yönetimi

Faturalandırma Stripe ile yürütülür. İlgili uçlar (sahip/yönetici yetkisi gerektirir):

GET/api/organizations/:orgId/billingOturum

Fatura bilgilerini (ad, vergi no, adres) görüntüler.

PUT/api/organizations/:orgId/billingOturum

Fatura adresini ve vergi numarasını günceller; Stripe müşterisine senkronlanır.

GET/api/organizations/:orgId/invoicesOturum

Stripe fatura geçmişi (PDF bağlantılarıyla).

GET/api/organizations/:orgId/payment-methodsOturum

Kayıtlı kartlar (marka, son 4 hane, varsayılan).

POST/api/organizations/:orgId/billing-portalOturum

Self-servis Stripe Billing Portal oturumu açar.

POST/api/organizations/:orgId/subscribe-freeOturum

Ücretsiz planı etkinleştirir (Stripe ödemesi yok).

POST/api/organizations/:orgId/cancel-subscriptionOturum

Dönem sonunda iptal eder (cancel_at_period_end).

POST/api/organizations/:orgId/sync-subscriptionOturum

Stripe ile manuel senkronizasyon.

Billing Portal oturumubash

curl -X POST https://api.segmento.app/api/organizations/org_01HXX.../billing-portal \
  -H "Cookie: <better-auth session>"

Denemeler ve İptal

Ücretli planlar deneme süresiyle sunulur. İptal, dönem sonunda gerçekleşir — abonelik fatura döneminin sonuna kadar etkin kalır, anında kesilmez.

Doğrulanacak

Deneme süresi (pazarlama metninde 14 gün) Stripe fiyat yapılandırmasından gelir, kodda sabit değildir. İade politikası kodda tanımlı değildir; her ikisi de yayından önce ürün ekibiyle netleştirilmelidir.

Müşteri Destek

İletişim Kanalları

Şu an için tek destek kanalı e-postadır. Panel üzerindeki iletişim formu ya da doğrudan POST /api/contact ucu, mesajı [email protected] adresine iletir.

POST/api/contact

Genel; kimlik doğrulama gerektirmez.

İletişim formubash

curl -X POST https://api.segmento.app/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "message": "Segmentation job 8f1c2d3e... failed at 40% with a schema error."
  }'

Zorunlu alanlar: name (min 2), email (geçerli e-posta), message (min 10 karakter).

İyi Bir Destek Talebi

Talebinizi hızlandırmak için mümkünse şunları ekleyin:

Organizasyon adı / slug
Proje ID
İlgili job_id (başarısız ya da yavaş segmentasyon için)
İlgili API ucu ve zaman damgası
Tam hata mesajı / error_message

Kapsam ve Yanıt Süreleri

Destek şu an asenkron olarak e-posta üzerinden sağlanır; canlı ticketing/portal henüz yoktur.

Doğrulanacak

SLA, destek saatleri ve yanıt süresi taahhütleri kodda tanımlı değildir; ürün ekibiyle netleştirilecek.

API Referansı

Giriş ve Temel URL'ler

Tüm istekler JSON tabanlıdır. Temel URL: https://api.segmento.app/api (yerel geliştirme: http://localhost:3001/api). API iki ayrı yüzeyden oluşur:

Yüzey	Taban	Kimlik doğrulama
Ingest API (M2M)	`/api/v1`	API anahtarı (sk_live_)
Panel / Oturum API	`/api/engine/*`	Oturum çerezi

Bugün yalnızca veri gönderme (/api/v1/ingest) API anahtarıyla korunur. Segment/müşteri okuma uçları oturum gerektirir (panel üzerinden, /api/engine/* proxy'si).

Kimlik Doğrulama

Makineden makineye (M2M) istekler API anahtarı ile yetkilendirilir. Anahtar formatı sk_live_<64 hex> ve başlık olarak Authorization: Bearer sk_live_... şeklinde gönderilir.

Anahtarlar SHA-256 ile saklanır ve timing-safe karşılaştırılır.
Yalnızca enabled anahtarlar kabul edilir.
Süresi geçmiş (expiresAt) anahtar 401 döner.
Anahtarlar proje kapsamlıdır; eşleşmeyen proje 403 döner.

Anahtar oluşturma (panelden, oturumlu):

POST/api/projects/:projectId/api-keysOturum

Gövde: { name, expiresAt? }

Anahtar oluşturbash

curl -X POST https://api.segmento.app/api/projects/proj_01HXX.../api-keys \
  -H "Cookie: <better-auth session>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production ingest", "expiresAt": "2027-01-01T00:00:00Z" }'

Yanıt — 201json

{
  "id": "f0e9c8b7-...-uuid",
  "name": "Production ingest",
  "keyPrefix": "sk_live_a1b2c3",
  "key": "sk_live_a1b2c3d4e5f6...the-only-time-this-is-returned",
  "enabled": true,
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-06-07T10:00:00Z"
}

Ham anahtar (key) yalnızca oluşturma anında bir kez döner. Hemen kaydedin; tekrar gösterilmez.

Veri Gönderme (Ingest)

POST/api/v1/ingestAPI anahtarı

Gövde: project_id (zorunlu), records (1–10.000 nesne) ve opsiyonel batch_id. Kayıtlar CSV'ye dönüştürülüp işleme kuyruğuna eklenir; yanıt 202 Accepted ile bir job_id döndürür.

curl -X POST https://api.segmento.app/api/v1/ingest \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_01HXX...",
    "records": [
      { "customer_id": "C-1001", "order_date": "2026-05-01", "amount": 129.90, "country": "TR" },
      { "customer_id": "C-1002", "order_date": "2026-05-02", "amount": 59.00, "country": "DE" }
    ],
    "batch_id": "may-2026-orders"
  }'

Yanıt — 202json

{
  "job_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "file_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "status": "processing"
}

Hata durumları: 401 (eksik/geçersiz/süresi geçmiş anahtar), 403 (proje uyuşmazlığı), 400 (boş veya 10.000'den fazla kayıt), 500 (sunucu hatası).

Asenkron İş Akışı

Ingest ve segmentasyon asenkrondur (Celery + Redis). Dönen job_id ile ilerleme izlenir.

GET/api/engine/jobs/:jobId/progressOturum

Anlık ilerleme (yüzde + mesaj).

İlerleme sorgulabash

curl https://api.segmento.app/api/engine/jobs/8f1c2d3e-.../progress \
  -H "Cookie: <better-auth session>"

Yanıtjson

{
  "job_id": "8f1c2d3e-...",
  "status": "processing",
  "pct": 64,
  "message": "Segmenting customers"
}

GET/api/engine/jobs/:jobId/statusOturum

Kalıcı durum kaydı (result, error_message, zaman damgaları).

GET/api/engine/jobs/:jobId/progress/streamOturum

SSE ile gerçek zamanlı akış (polling gerektirmez).

SSE akışıbash

curl -N https://api.segmento.app/api/engine/jobs/8f1c2d3e-.../progress/stream \
  -H "Cookie: <better-auth session>"

Terminal durumlar: completed | failed. İlerleme kayıtları Redis'te ~1 saat sonra düşer; eski işler için /status ucuna düşülür.

Kaynak Uçları

Aşağıdaki uçlar /api/engine/* altında, oturum çerezi ile çalışır.

GET/api/engine/projects/:projectId/segmentsOturum

Segment listesi (metadata ile).

POST/api/engine/projects/:projectId/segments/previewOturum

Kural sonuçlarını işlemeden önizler.

POST/api/engine/projects/:projectId/segmentsOturum

Özel segment oluşturur.

PATCH/api/engine/segments/:segmentIdOturum

Segmenti günceller (ad, kurallar).

DELETE/api/engine/segments/:segmentIdOturum

GET/api/engine/projects/:projectId/customersOturum

Sayfalı müşteri listesi (filtreler + sıralama).

GET/api/engine/customers/:customerId/similarOturum

Benzer müşteriler (embedding tabanlı).

GET/api/engine/projects/:projectId/overviewOturum

Toplu ML istatistikleri.

Örnek — müşteri listesini filtreleyerek çekme:

GET customersbash

curl "https://api.segmento.app/api/engine/projects/proj_01HXX.../customers\
?limit=2&churn_risk=high&sort_by=rfm_monetary&sort_dir=desc" \
  -H "Cookie: <better-auth session>"

Yanıt — 200json

{
  "customers": [
    {
      "id": "c0a8f1e2-...-uuid",
      "customer_id_hash": "CUST_8F2A",
      "segment_label": "Champions",
      "churn_score": 0.82,
      "churn_risk": "high",
      "abc_category": "A",
      "rfm_recency_days": 12,
      "rfm_frequency": 9,
      "rfm_monetary": 4210.5,
      "return_rate": 0.04,
      "uplift_score": 0.13,
      "last_transaction_at": "2026-05-28T10:14:00Z",
      "extra_features": { "country": "TR" }
    }
  ],
  "total": 5234,
  "page": 1,
  "pages": 2617
}

Gelişmiş filtreleme için filters sorgu parametresine JSON koşullar verilebilir:

filters gramerijson

[
  { "field": "rfm_monetary", "op": "range", "min": 1000, "max": 50000 },
  { "field": "churn_risk", "op": "in", "values": ["low", "medium"] }
]

Hata Yönetimi

Gateway hataları { "error": "..." }, Engine hataları { "detail": "..." } biçimindedir. Mesajlar Accept-Language başlığına göre yerelleştirilir.

Kod	Anlamı
`400`	Doğrulama hatası
`401`	Yetkisiz / geçersiz / süresi geçmiş anahtar
`403`	Yasak / proje uyuşmazlığı
`404`	Bulunamadı
`409`	Çakışma (örn. zaten abone)
`422`	Başarısız entegrasyon testi
`429`	Kota veya hız limiti aşıldı
`500`	Sunucu hatası
`503`	DB / cache / Engine erişilemiyor

Örnek hatajson

{ "error": "Forbidden: API key does not belong to this project" }

Hız Limitleri

Genel limit: 15 dakikada 1000 istek. Anahtar olarak Authorization başlığı kullanılır — yani her API anahtarının kendi kovası vardır. Yanıtlarda standart RateLimit-* başlıkları döner.

429 yanıtıhttp

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 540

İki ayrı 429 kaynağını ayırt edin: bu bölümdeki taşıma (transport) hız limiti ile faturalandırmadaki kota aşımı. İstemcilerde 429 için üstel geri çekilme (exponential backoff) önerilir.