API

Почему два API?

Классический реселлерский API (v2), которым пользуется вся отрасль, принимает форму на единственном эндпоинте и всегда отвечает HTTP 200. Именно такой формат ожидает готовое панельное ПО, поэтому он сохранён без изменений. А те, кто пишет собственную систему, постоянно упирались в его ограничения: ошибки нельзя было различить, каталог приходил одним куском, а статус заказа приходилось бесконечно опрашивать. v3 написан для них.

Сравнение

Какой выбрать?

С чего начать

1. 1Создайте ключ API на вкладке «Ключи».
2. 2Получите список услуг и посмотрите id и схему полей нужной услуги.
3. 3Сначала проверьте заказ через preview, затем создайте его.
4. 4Подключите вебхук или читайте поток событий, чтобы отслеживать изменения статуса.

Базовый адрес

Все пути добавляются к этому адресу. Версия находится в пути: если когда-нибудь понадобится ломающее изменение, будет опубликован новый путь (v4), а этот продолжит работать без правок. Дата публикации контракта возвращается в заголовке X-Api-Version в каждом ответе.

https://panelfollows.com/api/v3

Аутентификация

Отправляйте ключ API как токен Bearer в заголовке Authorization. В качестве альтернативы принимается заголовок X-Api-Key.

GET https://panelfollows.com/api/v3/account
Authorization: Bearer pf_live_...

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

Быстрый старт

curl https://panelfollows.com/api/v3/services?limit=5 \
  -H "Authorization: Bearer YOUR_API_KEY"

Язык

Язык ответа выбирается заголовком Accept-Language или параметром ?lang=; параметр имеет приоритет. Названия услуг, описания услуг, названия категорий, подписи статусов заказа, подписи полей заказа и сообщения об ошибках приходят на выбранном языке.

Машинные значения не меняются ни на одном языке: error.code, order.status, service.type и currency всегда одинаковы. Стройте условия на них, а пользователю показывайте текст.

Accept-Language: tr
# veya
GET https://panelfollows.com/api/v3/services?lang=tr

Формат запроса и ответа

Тело запроса передаётся в JSON (application/json); для быстрых проверок принимается и form-urlencoded. Ответы приходят в JSON: одиночный ресурс представлен обычным объектом, а списки приходят в конверте с полями data, has_more и next_cursor. В каждом объекте есть поле object, называющее его тип.

Суммы возвращаются десятичными СТРОКАМИ ("1.2340"), а не числами с плавающей точкой. Разбирайте их в десятичный тип на своей стороне, чтобы не терять доли. Валюта: USD.

Отметки времени даны в формате RFC 3339 (2026-08-21T00:24:45.255Z).

Ошибки

При сбое возвращается настоящий HTTP-код, а тело содержит единственный объект error. Ваш код должен ветвиться по error.code: это значение стабильно и не меняется вместе с языком.

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_0c858d8af7f65eca001b2f5a

{
  "object": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "quantity_out_of_range",
    "message": "Miktar, bu servisin izin verdiği aralığın dışında.",
    "param": "quantity",
    "doc_url": "https://panelfollows.com/api-docs#error-quantity_out_of_range",
    "request_id": "req_0c858d8af7f65eca001b2f5a"
  }
}

Ограничение запросов

600 запросов в минуту на ключ и дополнительно 900 запросов в минуту на IP. В каждом ответе приходят заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset, так что вы можете притормозить, не упираясь в лимит. При превышении возвращается 429 с заголовком Retry-After.

Постраничный вывод

Списки листаются курсором. Передавайте limit для размера страницы (не более 500) и starting_after с id последней записи предыдущей страницы. Продолжайте, пока has_more не станет false; next_cursor даёт готовый курсор для следующего запроса. Значение limit вне диапазона не обрезается молча, а возвращает ошибку: тихое обрезание создаёт у клиента иллюзию, что он выгрузил всё.

Защита от дублей (Idempotency-Key)

При создании заказа добавьте к запросу случайный заголовок Idempotency-Key. Если связь оборвётся и вы повторите запрос с тем же ключом, второй заказ создан не будет: вернётся тот же ответ, что и на первый запрос, с заголовком Idempotent-Replay: true. Записи хранятся 24 часа.

Если отправить тот же ключ с ДРУГИМ телом, вернётся 409 idempotency_key_reuse. Почти всегда это означает, что генерация ключей на стороне клиента сломана. Неудачный запрос не сжигает ключ: исправьте проблему и повторите с тем же ключом.

Создание заказа

curl -X POST https://panelfollows.com/api/v3/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea3a-4b1c-9c1e-2b0d5c6a7e91" \
  -d '{
    "service": 1234,
    "link": "https://instagram.com/username",
    "quantity": 1000
  }'

Схема полей услуги

Каждая услуга публикует нужные ей поля в массиве fields: имя, тип, обязательность, ограничения, а также подпись и описание на вашем языке. Если у поля determines_quantity равно true, количество вычисляется по числу строк в этом поле.

// Servisin kendi alan şemasından formu OTOMATİK üretmek:
// hiçbir servis tipini koda gömmeniz gerekmez.
const res = await fetch("https://panelfollows.com/api/v3/services/1234", {
  headers: { Authorization: "Bearer YOUR_API_KEY", "Accept-Language": "tr" },
});
const service = await res.json();

for (const field of service.fields) {
  renderInput({
    name: field.name,
    label: field.label,             // kullanıcının dilinde
    hint: field.description,        // kullanıcının dilinde
    required: field.required,
    type: field.type,               // url | integer | string | text_lines
    min: field.min,
    max: field.max,
    // true ise miktarı bu alanın satır sayısı belirler
    countsLines: field.determines_quantity === true,
  });
}

Объект услуги

{
  "object": "service",
  "id": 1234,
  "name": "Instagram Takipçi | Türk | 30 gün telafi",
  "description": "Gerçek hesaplardan Türk takipçi. Başlangıç 0-1 saat.",
  "type": "default",
  "platform": "instagram",
  "category": { "slug": "instagram-takipci", "name": "Instagram Takipçi" },
  "pricing": {
    "rate": "1.2340",
    "currency": "USD",
    "unit": "per_1000",
    "unit_note": "Fiyat 1000 adet içindir."
  },
  "limits": { "min": 100, "max": 100000 },
  "features": { "refill": true, "cancel": false, "dripfeed": true },
  "average_time_seconds": 4320,
  "fields": [
    {
      "name": "link",
      "type": "url",
      "required": true,
      "label": "Bağlantı",
      "description": "Gönderimin yapılacağı profilin herkese açık adresi."
    },
    {
      "name": "quantity",
      "type": "integer",
      "required": true,
      "label": "Miktar",
      "description": "Kaç adet gönderileceği.",
      "min": 100,
      "max": 100000
    }
  ],
  "is_active": true,
  "updated_at": "2026-08-20T09:15:00.000Z"
}

Предпросмотр заказа (сухой прогон)

POST /orders/preview проверяет заказ и рассчитывает стоимость, НЕ создавая его. Вы можете показать цену клиенту и заранее убедиться, что баланса хватает. Списания с баланса не происходит, к поставщику обращения нет.

Пакетные заказы

POST /orders/batch принимает до 50 заказов за один вызов. Элементы обрабатываются по порядку, и каждый получает собственный результат: даже если один не прошёл, остальные будут созданы, а в результате элемента видно, какой именно и почему не прошёл.

Встраивание связанных объектов

Если передать include=service на эндпоинтах заказов, объект услуги встраивается в ответ и второй запрос не понадобится.

Справочник эндпоинтов

Схема OpenAPI

Машиночитаемое описание всех эндпоинтов. Передайте этот файл генератору клиентов (openapi-generator, Kiota) или Postman и получите готовый клиент на своём языке.

https://panelfollows.com/api/v3/openapi.json

Частые вопросы

Эндпоинт

POST https://panelfollows.com/api/v2
POST https://panelfollows.com/api/v2/tr

Аутентификация

В каждом запросе передаётся параметр key. Держите ключ в секрете и сразу перевыпускайте его при утечке.

Формат запроса и ответа

Запросы отправляются методом POST в виде формы (application/x-www-form-urlencoded), ответы приходят в JSON. При ошибке тоже возвращается HTTP 200, а в теле находится { "error": "..." }.

Также поддерживается, хотя раньше не документировалось: вызывать можно и методом GET, а тело допустимо отправлять как application/json.

Ограничение запросов

240 запросов в минуту на ключ и дополнительно 300 запросов в минуту на IP. Запросы сверх лимита отклоняются с кодом 429.

Действия и параметры

Пример

curl -X POST https://panelfollows.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1234" \
  -d "link=https://instagram.com/username" \
  -d "quantity=1000"

# Yanıt: { "order": 23501 }

Ответы на турецком

Добавьте /tr в конец адреса, чтобы получать названия услуг, категории, статусы заказов и сообщения об ошибках на турецком. Параметры, действия и структура ответа полностью совпадают, а ваш ключ работает по обоим адресам. Технические поля (type, refill_status, currency) остаются на английском ради совместимости со стандартом.

Переход на v3

Переход не обязателен. Если вы всё же решите перейти, большая часть бизнес-логики сохранится, потому что имена параметров не изменились; меняются транспорт и способ чтения ошибок.

1. 1Перенесите ключ из поля key в теле запроса в заголовок Authorization: Bearer.
2. 2Вызывайте путь ресурса вместо action=... (POST /orders вместо add).
3. 3Проверяйте сбой по HTTP-коду и error.code, а не по вопросу «есть ли поле error».
4. 4Сравнивайте статус заказа с машинным значением, а не с отображаемым текстом.
5. 5При создании заказа добавляйте Idempotency-Key.
6. 6Замените опрос статуса вебхуками.

Ключи v3

Вы можете создать столько ключей, сколько нужно, пометить каждый и отзывать их по отдельности. На нашей стороне хранится только криптографический отпечаток ключа.

Legacy-ключ

Единственный ключ, который использует классический реселлерский API (v2). Он работает и в v3. После перевыпуска старое значение становится недействительным мгновенно.

Безопасность

• Храните ключ в переменной окружения, а не в исходном коде.
• Не размещайте ключ в коде, который выполняется в браузере; проводите запросы через собственный сервер.
• Заводите отдельный ключ для каждой системы, тогда отзыв одного не затронет остальные.
• При подозрении на утечку сначала введите в работу новый ключ, а затем отзовите старый.

Зачем вебхуки?

Опрос и медленный, и расточительный: спрашивать про тысячи заказов каждую минуту значит выбрать весь лимит запросов и всё равно узнать об изменении спустя минуты. С вебхуком изменение доходит до вас в момент, когда оно произошло.

Настройка

1. 1Подготовьте публичный адрес https (локальные адреса и адреса внутренней сети не принимаются).
2. 2Добавьте адрес ниже и сохраните ключ подписи, который показывается один раз.
3. 3Проверяйте подпись на своей стороне и отвечайте 2xx.
4. 4Нажмите кнопку тестовой отправки, чтобы проверить весь путь от начала до конца.

Что мы отправляем

POST /hooks/pf HTTP/1.1
Content-Type: application/json
Webhook-Id: evt_7f910fba7cd042ef9d9069ba5c074fa0
Webhook-Timestamp: 1787261223
Webhook-Signature: t=1787261223,v1=9c1e2b0d5c6a7e91...

{
  "object": "event",
  "id": "evt_7f910fba7cd042ef9d9069ba5c074fa0",
  "type": "order.completed",
  "created_at": "2026-08-21T00:27:03.531Z",
  "data": {
    "previous_status": "in_progress",
    "order": {
      "object": "order",
      "id": 23501,
      "status": "completed",
      "status_label": "Tamamlandı",
      "service": 1234,
      "quantity": 1000,
      "start_count": 4210,
      "remains": 0,
      "charge": "1.2340",
      "currency": "USD"
    }
  }
}

Проверка подписи

Каждый запрос несёт заголовок Webhook-Signature: t: отметка времени, v1: подпись. Подпись представляет собой HMAC-SHA256 строки "<отметка времени>.<сырое тело>", вычисленный с вашим секретным ключом.

1. 1Разберите из заголовка значения t и v1.
2. 2Убедитесь, что значение t не старше 5 минут, чтобы заблокировать повторные атаки.
3. 3Вычислите HMAC-SHA256 строки "<t>.<сырое тело>" со своим секретным ключом.
4. 4Сравните результат с v1 за постоянное время и отклоните запрос, если они не совпадают.

Пример проверки

import crypto from "node:crypto";
import express from "express";

const app = express();
// ÖNEMLİ: imza HAM gövde üzerinden hesaplanır. JSON'a çevirip yeniden
// dizeye dönüştürürseniz boşluklar değişir ve imza tutmaz.
app.post("/hooks/pf", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const header = req.get("Webhook-Signature") ?? "";
  const m = /t=(\d+),v1=([0-9a-f]+)/.exec(header);
  if (!m) return res.sendStatus(400);

  const [, timestamp, signature] = m;
  // Tekrar saldırısına karşı: 5 dakikadan eski damgayı reddet.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400);

  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${raw}`, "utf8")
    .digest("hex");

  const ok =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(raw);
  // 2xx dönmezseniz gönderim artan aralıklarla tekrar denenir.
  res.sendStatus(200);

  if (event.type === "order.completed") {
    // ... siparişi kendi sisteminizde tamamlandı olarak işaretleyin
  }
});

Повторные отправки

Первая попытка выполняется в момент события. Если ответ отличается от 2xx или соединение не установилось, отправка повторяется через 1 минуту, 5 минут, 30 минут, 2 часа и 6 часов. После 6 попыток доставка помечается как неуспешная и попадает в журнал доставок.

Типы событий

Можно подписаться на интересующие типы или получать все. Одно изменение статуса порождает ровно одно событие, с типом, который лучше всего соответствует новому статусу.

Если разместить вебхук негде

Те же события можно читать по курсору через GET /api/v3/events. Пользуйтесь этим способом при локальной разработке, при отсутствии статического IP или из-за межсетевого экрана.

// Webhook kuramıyorsanız (yerelde geliştirme, sabit IP yok) aynı bilgiyi
// imleçle çekebilirsiniz. İmleci kendi tarafınızda saklayın.
let cursor = loadCursor(); // en son işlediğiniz olayın "cursor" değeri

const url = new URL("https://panelfollows.com/api/v3/events");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("starting_after", String(cursor));

const res = await fetch(url, { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const { data, has_more } = await res.json();

for (const event of data) {
  handle(event);        // sizin işleyiciniz
  cursor = event.cursor; // imleci ilerlet
}
saveCursor(cursor);