> ## 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]
>
> Ваш магазин должен быть одобрен для участия в партнерской программе. Подайте заявку в панели управления в разделе **Партнеры**. До одобрения каждый партнерский эндпоинт возвращает `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.
* Партнеры и выплаты используют публичные ID длиной 16 символов. Конверсии используют публичный `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` всегда содержит чистую сумму.

## Вебхуки

Подпишитесь на эти события в разделе **Разработчикам › Вебхуки**. Они используют ту же оболочку и заголовок `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.