Affiliate programı

Affiliate uç noktalarıyla ortaklık programınızı kendi sistemlerinizle eşitlersiniz: ortakları listeler, atfedilen siparişleri ve ödemeleri takip edersiniz.

Mağazanızın affiliate programı için onaylanmış olması gerekir. Panelde Affiliate bölümünden başvurun. Onaya kadar tüm affiliate uç noktaları FEATURE_NOT_ENABLED koduyla 403 döner.

Uç noktalar

Metot	Yol	Açıklama
`GET`	`/affiliates/partners`	Ortakları listeler. `status` ile filtreleyin veya `q` ile arayın.
`POST`	`/affiliates/partners`	E-postayla ortak davet eder. Ortak hemen aktif olur.
`GET`	`/affiliates/conversions`	Atfedilen siparişleri komisyon durumlarıyla listeler.
`GET`	`/affiliates/payouts`	Ödeme taleplerini listeler. Açık talepler önce gelir.

Ortak onaylama, işaretlenen dönüşümleri inceleme ve ödeme gönderme panelde kalır.

Tutarlar ve ID’ler

API yanıtlarındaki tutarlar en küçük para birimi cinsinden tam sayıdır. USD için commission: 499, 4,99 $ demektir.
Webhook gövdeleri ana birim kullanır. commission: 4.99, 4,99 $ demektir.
Ortaklar ve ödemeler 16 karakterlik public ID kullanır. Dönüşümler siparişin public invoice_id değerini kullanır.

Sayfalama

Liste uç noktaları sayfa başına 25 kayıt ve bir next_cursor döner. Sonraki sayfa için bu değeri cursor olarak gönderin. Son sayfada next_cursor değeri null olur.

curl "https://app.papelship.com/api/v1/affiliates/conversions?status=valid&cursor=1832" \
  -H "x-api-key: your_api_key" \
  -H "x-store-hash: your_store_hash"

Her liste ayrıca durum başına kayıt sayısını veren counts alanını döner:

{
  "success": true,
  "conversions": [ ... ],
  "next_cursor": 1807,
  "counts": { "valid": 40, "flagged": 2, "rejected": 1 }
}

Ortak davet etme

curl -X POST https://app.papelship.com/api/v1/affiliates/partners \
  -H "x-api-key: your_api_key" \
  -H "x-store-hash: your_store_hash" \
  -H "Content-Type: application/json" \
  -d '{ "email": "creator@example.com", "name": "Alex Creator" }'

Yanıt (201)

{ "success": true, "id": "7fKq2LmN9xPa3RtB" }

Salt okunur anahtarlar ortak davet edemez.

Siparişler nasıl atfedilir

Sipariş bir ortağa şu yollardan biriyle yazılır (öncelik sırasıyla):

Ortak kuponu. Alıcı ortağa bağlı bir kupon kullandı.
Takip linki. Alıcı bir ortak linkini açtı: https://magazaniz.com/herhangi-sayfa?ref=KOD veya https://magazaniz.com/r/KOD. Storefront tıklamayı programın çerez süresi boyunca hatırlar.
API. Faturayı oluştururken affiliateCode gönderdiniz. Dönüşüm source: "api" olur.

Alıcı ortağın kendisiyse veya başka bir kupon kullanıldıysa ve program kupon birleştirmeye izin vermiyorsa dönüşüm reddedilir. Siparişin fraud puanı yüksekse veya ortak kısa sürede olağandışı sayıda sipariş alıyorsa dönüşüm incelemeye düşer.

Komisyon durumları

`commission_state`	Anlamı
`unpaid`	Sipariş henüz tamamlanmadı.
`held`	İşaretlendi. Paneldeki incelemenizi bekliyor.
`pending`	Bekleme süresinde. Bkz. `available_at`.
`available`	Ortak ödeme talep edebilir.
`none`	Dönüşüm reddedildi.

İadeler komisyonu otomatik olarak geri alır. commission her zaman net tutardır.

Webhook’lar

Bu olaylara Developers › Webhooks bölümünden abone olun. Sipariş olaylarıyla aynı zarfı ve PapelShip-Signature başlığını kullanırlar.

Olay	Ne zaman
`affiliate.partner_applied`	Biri storefront’tan programınıza başvurur.
`affiliate.conversion`	Atfedilen bir sipariş tamamlanır ve komisyon kaydedilir. Sipariş başına bir kez gönderilir.
`affiliate.payout_requested`	Bir ortak ödeme talep eder.
`affiliate.payout_sent`	Bir ödemeyi gönderildi olarak işaretlersiniz.

affiliate.conversion

{
  "id": "evt_9b2c...",
  "object": "event",
  "type": "affiliate.conversion",
  "created": 1791100000,
  "livemode": true,
  "store": { "id": "0bHQn0bU2dei", "name": "Acme", "slug": "acme" },
  "data": {
    "object": {
      "object": "affiliate_conversion",
      "order_id": "c35ffd-19a1b2c3d4e-8c7a20",
      "partner": { "id": "7fKq2LmN9xPa3RtB", "email": "creator@example.com" },
      "source": "link",
      "link_code": "alex",
      "status": "valid",
      "commission": 4.99,
      "currency": "USD",
      "available_at": "2026-10-18T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  }
}

affiliate.payout_sent

{
  "type": "affiliate.payout_sent",
  "data": {
    "object": {
      "object": "affiliate_payout",
      "id": "Qm3vX8kL2pN7rT4w",
      "partner": { "id": "7fKq2LmN9xPa3RtB", "email": "creator@example.com" },
      "amount": 125,
      "currency": "USD",
      "method": "crypto",
      "coin": "USDT",
      "network": "TRC20",
      "amount_coin": 125.04,
      "status": "sent",
      "tx_hash": "a1b2c3...",
      "created_at": "2026-10-02T09:30:00.000Z"
    }
  }
}

Hatalar

Affiliate hataları makinece okunabilir bir code içerir:

{ "success": false, "code": "ALREADY_MEMBER", "error": "This email is already a partner of your store." }

Kod	Durum	Anlamı
`FEATURE_NOT_ENABLED`	`403`	Mağaza affiliate programı için onaylı değil.
`INVALID_EMAIL`	`400`	E-posta adresi geçersiz.
`ALREADY_MEMBER`	`409`	Bu e-posta zaten mağazanın ortağı.
`BANNED`	`409`	Ortak bu mağazada yasaklı.
`NOT_FOUND`	`404`	Ortak veya kayıt bulunamadı.

Rehberler

Endpoint'ler

Uç noktalar

Tutarlar ve ID’ler

Sayfalama

Ortak davet etme

Siparişler nasıl atfedilir

Komisyon durumları

Webhook’lar

Hatalar

​Uç noktalar

​Tutarlar ve ID’ler

​Sayfalama

​Ortak davet etme

​Siparişler nasıl atfedilir

​Komisyon durumları

​Webhook’lar

​Hatalar

Uç noktalar

Tutarlar ve ID’ler

Sayfalama

Ortak davet etme

Siparişler nasıl atfedilir

Komisyon durumları

Webhook’lar

Hatalar