# Система постбэков

Постбэк — HTTP-запрос, который сервис автоматически отправляет на URL трекера партнёра в момент оплаты.

---

## Новая система (v2, текущая)

### Что изменилось

| Параметр | Старая система (v1) | Новая система (v2) |
|----------|--------------------|--------------------|
| Отправка | Синхронная (блокирует запрос покупателя) | **Асинхронная** (фоновый процесс) |
| Повторные попытки | Нет | До 3 раз при ошибке |
| Поддержка Keitaro | Частичная (`{data1}..{data5}`) | **Полная** (`{click_id}`, `{revenue}`, `{sub1}..{sub5}`, и т.д.) |
| Логирование | `clickpay24.tv.postback.log` | `clickpay24.tv.postback_new.log` + таблица `postback_queue_tb` |
| Отладка | Только логи | Логи + история в БД |

### Мониторинг

Все постбэки хранятся в таблице `postback_queue_tb`:

```sql
SELECT order_id, status, http_code, attempts, sent_at
FROM postback_queue_tb
ORDER BY created_at DESC
LIMIT 50;
```

Статусы: `pending` → `sent` (успех) или `failed` (ошибка, будет повтор).

---

## Настройка URL постбэка

URL постбэка задаётся партнёром в поле `post_back_url` таблицы `partner2product_tb` (через личный кабинет).

### Поддерживаемые плейсхолдеры

#### Данные клика (передаются в партнёрской ссылке)

| Плейсхолдер | Синонимы | Описание |
|-------------|----------|----------|
| `{data1}`   | `{sub1}` `{click_id}` | Click ID трекера (Keitaro: `{click_id}`) |
| `{data2}`   | `{sub2}` | Кастомный параметр 2 |
| `{data3}`   | `{sub3}` | Кастомный параметр 3 |
| `{data4}`   | `{sub4}` | Кастомный параметр 4 |
| `{data5}`   | `{sub5}` | Кастомный параметр 5 |
| `{utm_source}` | — | UTM и другие кастомные параметры из ссылки |
| `{fbclid}`  | — | Facebook click ID |
| `{gclid}`   | — | Google click ID |
| `{roistat_visit}` | — | Roistat |

> **Важно:** `{utm_source}`, `{fbclid}` и другие нестандартные параметры сохраняются автоматически если они были в партнёрской ссылке.

#### Данные заказа

| Плейсхолдер | Синонимы | Описание |
|-------------|----------|----------|
| `{orderid}` | `{transaction_id}` | ID заказа |
| `{amount}`  | `{revenue}` `{payout}` | Сумма партнёру (uamount) |
| `{status}`  | — | `approved` / `rejected` / `pending` / `rebill` |

---

## Примеры URL постбэков

### Keitaro

```
https://your-keitaro.domain/postback?click_id={click_id}&status={status}&revenue={revenue}
```

### Binom / Tracker.gg

```
https://binom.your-domain.com/click.php?cnv_id={click_id}&cnv_status={status}&cnv_revenue={amount}
```

### PeerClick / Voluum

```
https://trk.domain.com/postback?cid={data1}&payout={revenue}&txid={orderid}
```

### Roistat

```
https://cloud.roistat.com/integration/webhook/payment?visit={roistat_visit}&order_id={orderid}&revenue={amount}
```

### Произвольный трекер с utm

```
https://your-tracker.com/event?source={utm_source}&medium={utm_medium}&cid={data1}&amount={amount}&status={status}
```

---

## Статусы

| Статус | Описание |
|--------|----------|
| `approved` | Оплата подтверждена, деньги зачислены партнёру |
| `rebill` | Повторная оплата по апселу/подписке |
| `pending` | На удержании (hold) |
| `rejected` | Платёж отклонён или возврат |

---

## Передача click ID из Keitaro

### Настройка в Keitaro

1. Создайте кампанию с лендингом:
   ```
   https://your-site.com/pay/redirect.php?code=PARTNER_CODE&data1={click_id}
   ```

2. Настройте постбэк:
   ```
   https://your-keitaro.domain/postback?click_id={click_id}&status={status}&revenue={revenue}
   ```

3. При клике Keitaro подставит свой `click_id` вместо `{click_id}` в URL редиректа.  
   Сервис сохранит его в `data1` и вернёт при оплате.

---

## Миграция со старой системы (v1)

> Старая система (`sendPostBackUrl`) **сохранена** и продолжает работать.  
> Переходить необязательно — новая система уже активна для всех новых заказов.

**Если у вас был URL вида:**
```
https://tracker.com/pb?data1={data1}&orderid={orderid}&amount={amount}
```

— он работает **без изменений** в новой системе.

**Если хотите использовать новые плейсхолдеры** — просто обновите URL:
```
https://tracker.com/pb?click_id={click_id}&txid={transaction_id}&revenue={revenue}
```

Старые плейсхолдеры `{data1}..{data5}`, `{orderid}`, `{amount}`, `{status}` поддерживаются бессрочно.