> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliate programı

> Ortakları, dönüşümleri ve ödemeleri okuyun, ortak davet edin ve affiliate webhook'larını dinleyin.

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

<Info>
  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.
</Info>

## 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.

```bash theme={"system"}
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:

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

## Ortak davet etme

```bash theme={"system"}
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" }'
```

```json Yanıt (201) theme={"system"}
{ "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):

1. **Ortak kuponu.** Alıcı ortağa bağlı bir kupon kullandı.
2. **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.
3. **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. |

```json affiliate.conversion theme={"system"}
{
  "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"
    }
  }
}
```

```json affiliate.payout_sent theme={"system"}
{
  "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:

```json theme={"system"}
{ "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ı. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.