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

# Партнерська програма

> Отримуйте дані про партнерів, конверсії та виплати, запрошуйте партнерів і реагуйте на партнерські вебхуки.

Використовуйте партнерські ендпоінти, щоб синхронізувати свою партнерську програму з власними системами: отримуйте список партнерів, відстежуйте атрибутовані замовлення та стежте за виплатами.

> [!NOTE]
>
> Ваш магазин має бути схвалений для партнерської програми. Подайте заявку в панелі керування в розділі **Affiliates**. До того часу кожен партнерський ендпоінт повертає `403` з кодом `FEATURE_NOT_ENABLED`.

## Ендпоінти

| Метод | Шлях | Опис |
| :- | :- | :- |
| `GET` | `/affiliates/partners` | Список партнерів. Фільтруйте за `status` або шукайте через `q`. |
| `POST` | `/affiliates/partners` | Запросити партнера за email. Партнер одразу стає активним. |
| `GET` | `/affiliates/conversions` | Список атрибутованих замовлень зі станом комісії для кожного. |
| `GET` | `/affiliates/payouts` | Список запитів на виплату. Відкриті запити йдуть першими. |

Схвалення партнерів, перевірка позначених конверсій і надсилання виплат залишаються в панелі керування.

## Суми та ID

* Суми у відповідях API є цілими числами в дрібних одиницях. `commission: 499` у `USD` означає \$4.99.
* Дані вебхуків використовують основні одиниці. `commission: 4.99` означає \$4.99.
* Партнери та виплати мають 16-символьні публічні ID. Конверсії використовують публічний `invoice_id` замовлення.

## Пагінація

Ендпоінти списків повертають 25 елементів на сторінку разом із `next_cursor`. Передайте його назад як `cursor`, щоб отримати наступну сторінку. На останній сторінці `next_cursor` дорівнює `null`.

```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"
```

Кожен список також повертає `counts`, кількість записів для кожного статусу:

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

## Запросіть партнера

```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 Відповідь (201) theme={"system"}
{ "success": true, "id": "7fKq2LmN9xPa3RtB" }
```

Ключі лише для читання не можуть запрошувати партнерів.

## Як замовлення атрибутуються

Замовлення зараховується партнеру одним із таких способів, у порядку пріоритету:

1. **Купон партнера.** Покупець використав купон, прив'язаний до партнера.
2. **Посилання для відстеження.** Покупець відкрив партнерське посилання: `https://your-store.com/any-page?ref=CODE` або `https://your-store.com/r/CODE`. Вітрина запам'ятовує перехід на час дії cookie-вікна програми.
3. **API.** Ви передали `affiliateCode` під час створення рахунку. Конверсія має `source: "api"`.

Конверсію відхиляють, якщо покупець є самим партнером, або якщо використано інший купон, а програма не дозволяє поєднувати купони. Її позначають для перевірки, якщо замовлення має високу оцінку ризику шахрайства або партнер отримує незвично багато замовлень за короткий час.

## Стани комісії

| `commission_state` | Значення |
| :- | :- |
| `unpaid` | Замовлення ще не завершено. |
| `held` | Позначено. Очікує вашої перевірки в панелі керування. |
| `pending` | Триває період утримання. Див. `available_at`. |
| `available` | Партнер може запросити виплату. |
| `none` | Конверсію відхилено. |

Повернення коштів автоматично скасовують комісію. `commission` завжди є чистою сумою.

## Вебхуки

Підпишіться на ці події в розділі **Developers › Webhooks**. Вони використовують ту саму обгортку та заголовок `PapelShip-Signature`, що й події замовлень.

| Подія | Коли |
| :- | :- |
| `affiliate.partner_applied` | Хтось подає заявку до вашої програми з вітрини. |
| `affiliate.conversion` | Атрибутоване замовлення завершено, і комісію зафіксовано. Надсилається один раз на замовлення. |
| `affiliate.payout_requested` | Партнер запитує виплату. |
| `affiliate.payout_sent` | Ви позначаєте виплату як надіслану. |

```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"
    }
  }
}
```

## Помилки

Партнерські помилки містять машиночитний `code`:

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

| Код | Статус | Значення |
| :- | :- | :- |
| `FEATURE_NOT_ENABLED` | `403` | Магазин не схвалено для партнерської програми. |
| `INVALID_EMAIL` | `400` | Адреса email недійсна. |
| `ALREADY_MEMBER` | `409` | Цей email уже є партнером цього магазину. |
| `BANNED` | `409` | Партнера заблоковано в цьому магазині. |
| `NOT_FOUND` | `404` | Партнер або запис не існує. |


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