API

Warum zwei APIs?

Die klassische Reseller-API (v2), die die ganze Branche nutzt, schickt ein Formular an einen einzigen Endpunkt und antwortet immer mit HTTP 200. Genau diese Form erwartet fertige Panel-Software, deshalb bleibt sie, wie sie ist. Wer eigene Systeme entwickelt, stieß damit aber immer wieder an Grenzen: Fehler ließen sich nicht auseinanderhalten, der Katalog kam in einem Stück, und den Bestellstatus musste man endlos abfragen. Für sie wurde v3 entwickelt.

Vergleich

Welche API soll ich nutzen?

Erste Schritte

1. 1Erstelle im Tab „Schlüssel“ einen API-Schlüssel.
2. 2Ruf die Serviceliste ab und lies die id und das Feldschema des Service aus, den du brauchst.
3. 3Prüf die Bestellung zuerst mit preview und leg sie erst dann an.
4. 4Registriere einen Webhook oder lies den Event-Stream, um Statusänderungen zu verfolgen.

Basis-URL

Jeder Pfad wird an diese URL angehängt. Die Version steckt im Pfad: Sollte jemals eine inkompatible Änderung nötig werden, erscheint ein neuer Pfad (v4), und dieser hier läuft unverändert weiter. Das Veröffentlichungsdatum der API-Spezifikation steht in jeder Antwort im Header X-Api-Version.

https://panelfollows.com/api/v3

Authentifizierung

Sende deinen API-Schlüssel als Bearer-Token im Header Authorization. Alternativ wird auch der Header X-Api-Key akzeptiert.

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

Dein bestehender Legacy-Schlüssel funktioniert auch mit v3, du kannst also sofort loslegen. Im Produktivbetrieb solltest du einen v3-Schlüssel verwenden: Er lässt sich benennen, einzeln widerrufen und wird nie im Klartext gespeichert.

Schnellstart

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

Sprache

Die Antwortsprache wählst du über den Header Accept-Language oder den Parameter ?lang=; der Parameter hat Vorrang. Servicenamen, Servicebeschreibungen, Kategorienamen, Status-Labels von Bestellungen, Labels der Bestellfelder und Fehlermeldungen kommen alle in dieser Sprache zurück.

Maschinenwerte ändern sich nie mit der Sprache: error.code, order.status, service.type und currency sind immer gleich. Richte deine Logik nach diesen Werten und zeig deinen Nutzern den Text.

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

Anfrage- und Antwortformat

Anfrage-Bodys sind JSON (application/json); für schnelle Tests wird auch form-urlencoded akzeptiert. Antworten sind JSON: Eine einzelne Ressource ist ein einfaches Objekt, Listen kommen in einer Hülle (Envelope) mit data, has_more und next_cursor. Jedes Objekt hat ein Feld object, das seinen Typ nennt.

Beträge sind dezimale STRINGS ("1.2340"), keine Gleitkommazahlen. Wandle sie auf deiner Seite in einen Dezimaltyp um, damit keine Nachkommastellen verloren gehen. Die Währung ist USD.

Zeitstempel folgen RFC 3339 (2026-08-21T00:24:45.255Z).

Fehler

Bei einem Fehler bekommst du einen echten HTTP-Statuscode und einen Body mit genau einem error-Objekt. Dein Code sollte sich nach error.code richten: Dieser Wert ist fest und ändert sich nie mit der Sprache.

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

Rate-Limits

600 Anfragen pro Minute und Schlüssel, zusätzlich 900 pro Minute und IP. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, damit du dein Tempo drosseln kannst, bevor du an die Grenze stößt. Überschreitest du das Limit, bekommst du 429 mit einem Retry-After-Header.

Paginierung

Listen werden per Cursor paginiert. Sende limit für die Seitengröße (maximal 500) und starting_after mit der id des letzten Eintrags der vorherigen Seite. Mach so lange weiter, bis has_more false ist; next_cursor liefert dir den Cursor für den nächsten Aufruf. Ein limit außerhalb des erlaubten Bereichs wird nicht stillschweigend angepasst, sondern führt zu einem Fehler: Stilles Anpassen lässt Clients glauben, sie hätten alles abgerufen.

Schutz vor Duplikaten (Idempotency-Key)

Füg beim Anlegen einer Bestellung einen zufälligen Idempotency-Key-Header hinzu. Bricht die Verbindung ab und du wiederholst die Anfrage mit demselben Key, entsteht keine zweite Bestellung: Du bekommst die erste Antwort noch einmal, mit dem Header Idempotent-Replay: true. Die Einträge werden 24 Stunden aufbewahrt.

Sendest du denselben Key mit einem ANDEREN Body, kommt 409 idempotency_key_reuse zurück. Das heißt fast immer, dass die Key-Erzeugung auf Client-Seite fehlerhaft ist. Eine fehlgeschlagene Anfrage verbraucht den Key nicht: Behebe das Problem und versuch es mit demselben Key erneut.

Bestellung anlegen

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
  }'

Feldschema eines Service

Jeder Service veröffentlicht die Felder, die er braucht, in einem fields-Array: Name, Typ, ob das Feld Pflicht ist, seine Grenzen sowie ein Label und eine Beschreibung in deiner Sprache. Ist bei einem Feld determines_quantity auf true gesetzt, ergibt sich die Menge aus der Anzahl der Zeilen darin.

// 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,
  });
}

Das Service-Objekt

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

Bestellvorschau (Probelauf)

POST /orders/preview prüft eine Bestellung und berechnet den Preis, OHNE sie anzulegen. So kannst du deinem Kunden vorab den Preis zeigen und prüfen, ob dein Guthaben reicht. Es wird nichts abgebucht und kein Anbieter kontaktiert.

Sammelbestellungen

POST /orders/batch nimmt bis zu 50 Bestellungen in einem Aufruf an. Die Einträge werden der Reihe nach verarbeitet, und jeder meldet sein eigenes Ergebnis: Schlägt einer fehl, werden die übrigen trotzdem angelegt, und du siehst genau, welcher gescheitert ist und warum.

Verknüpfte Objekte einbetten

Übergib include=service an die Bestell-Endpunkte, dann wird das Service-Objekt direkt in die Antwort eingebettet und du sparst dir eine zweite Anfrage.

Servicequalität und die Shortlist der besten Services

Das Panel misst jeden Service stündlich: wie unsere eigenen Bestellungen dafür ausgegangen sind (abgeschlossen, storniert, hängen geblieben, abgelehnt), wie oft Kunden ein Refill angefordert oder ein Ticket eröffnet haben, wie lange die Lieferung tatsächlich gedauert hat und ob die Quelle den Service noch führt. GET /services/top macht aus diesen Messungen eine sortierte Shortlist, und include=quality hängt denselben Bericht an jedes Service-Objekt an.

Der Score (0-100) ist eine gewichtete Mischung aus fünf Komponenten: Zuverlässigkeit (42 %, die geschätzte Erfolgsquote), Zufriedenheit (14 %, aus der Beschwerdequote), Tempo (28 %, logarithmisch abhängig von der effektiven Lieferzeit; 5 Minuten ergeben die volle Punktzahl, 48 Stunden null), der eigene Score der Health-Engine (8 %) und der Umfang der Datenbasis (8 %). Kleine Boni gibt es für eine Refill-Garantie, eine vertrauenswürdige Quelle und eine lange Zugehörigkeit zum Katalog. Services, die gerade geprüft werden, von der Health-Engine markiert wurden oder von einer Quelle in der Probezeit stammen, bekommen zwar einen Score, landen aber nie im Ranking.

Filtere nach Plattform, Kategorie-Slug oder Service-Art (shelf: followers, likes, views …, plattformübergreifend), sortiere nach score, speed, reliability, price oder orders und nutze group_by=category (oder platform) mit per_group, um in einem einzigen Aufruf eine Shortlist pro Kategorie zu bekommen: genau das, was ein Shop braucht, um in jeder Kategorie einen „empfohlenen“ Service zu markieren.

# Instagram takipçi kategorisinde en iyi 5 servis
curl "https://panelfollows.com/api/v3/services/top?category=instagram-followers&limit=5"   -H "Authorization: Bearer YOUR_API_KEY"

# Her kategori için kanıtlı en iyi 3 servis (tek istek)
curl "https://panelfollows.com/api/v3/services/top?group_by=category&per_group=3&min_confidence=medium"   -H "Authorization: Bearer YOUR_API_KEY"

Endpunkt-Referenz

OpenAPI-Schema

Eine maschinenlesbare Beschreibung aller Endpunkte. Gib diese Datei an einen Client-Generator (openapi-generator, Kiota) oder an Postman weiter und du bekommst einen fertigen Client in deiner eigenen Programmiersprache.

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

Häufige Fragen

Endpunkt

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

Authentifizierung

Jede Anfrage enthält den Parameter key. Halte deinen Schlüssel geheim und erzeuge sofort einen neuen, falls er nach außen gelangt.

Anfrage- und Antwortformat

Anfragen werden als Formular per POST gesendet (application/x-www-form-urlencoded), Antworten kommen als JSON. Auch Fehler liefern HTTP 200, mit { "error": "..." } im Body.

Ebenfalls unterstützt, auch wenn es bisher nirgends dokumentiert war: Du kannst die API per GET aufrufen und den Body als application/json senden.

Rate-Limits

240 Anfragen pro Minute und Schlüssel, zusätzlich 300 pro Minute und IP. Überzählige Anfragen werden mit 429 abgelehnt.

Aktionen und Parameter

Beispiel

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 }

Antworten auf Türkisch

Häng /tr an die URL an, um Servicenamen, Kategorien, Bestellstatus und Fehlermeldungen auf Türkisch zu erhalten. Parameter, Aktionen und Antwortstruktur sind identisch, und dein Schlüssel funktioniert unter beiden URLs. Technische Felder (type, refill_status, currency) bleiben für die Kompatibilität mit dem Standard auf Englisch.

Umstieg auf v3

Der Umstieg ist freiwillig. Wenn du wechselst, bleibt der Großteil deiner Geschäftslogik erhalten, weil die Parameternamen gleich bleiben; anders sind nur der Transport und die Art, wie du Fehler ausliest.

1. 1Verschiebe den Schlüssel aus dem Feld key im Body in den Header Authorization: Bearer.
2. 2Ruf einen Ressourcenpfad auf statt action=... (POST /orders statt add).
3. 3Erkenne Fehler am HTTP-Status und an error.code statt an der Frage „Gibt es ein error-Feld?“.
4. 4Vergleiche den Bestellstatus mit dem Maschinenwert, nicht mit dem Anzeigetext.
5. 5Füg beim Anlegen von Bestellungen einen Idempotency-Key hinzu.
6. 6Ersetze das ständige Abfragen des Status durch Webhooks.

v3-Schlüssel

Erstelle so viele Schlüssel, wie du brauchst, gib jedem eine Bezeichnung und widerrufe sie einzeln. Bei uns wird nur ein kryptografischer Hash des Schlüssels gespeichert.

Legacy-Schlüssel

Der einzelne Schlüssel der klassischen Reseller-API (v2). Er funktioniert auch mit v3. Wenn du ihn neu erzeugst, wird der alte Wert sofort ungültig.

Sicherheit

• Speichere den Schlüssel in einer Umgebungsvariable, nie im Quellcode.
• Nutze keinen Schlüssel in Code, der im Browser läuft; leite die Aufrufe über deinen eigenen Server.
• Erstelle für jedes System einen eigenen Schlüssel, damit das Widerrufen eines Schlüssels die anderen nicht betrifft.
• Wenn du ein Leck vermutest, rolle zuerst den neuen Schlüssel aus und widerrufe erst dann den alten.

Warum Webhooks?

Polling ist langsam und verschwenderisch zugleich: Fragst du jede Minute Tausende Bestellungen ab, verbrauchst du dein Rate-Limit und erfährst von Änderungen trotzdem erst Minuten später. Mit Webhooks erreicht dich eine Änderung in dem Moment, in dem sie passiert.

Einrichtung

1. 1Bereite eine öffentliche https-URL vor (lokale Adressen und Adressen aus privaten Netzen werden abgelehnt).
2. 2Füg die URL unten hinzu und speichere das Signatur-Secret, das nur einmal angezeigt wird.
3. 3Prüf die Signatur auf deiner Seite und antworte mit 2xx.
4. 4Nutze den Test-Button, um den gesamten Weg von Anfang bis Ende zu prüfen.

Was wir senden

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

Signatur prüfen

Jede Anfrage enthält einen Webhook-Signature-Header: t ist der Zeitstempel, v1 die Signatur. Die Signatur ist der HMAC-SHA256 des Strings "<timestamp>.<raw body>", berechnet mit deinem Secret.

1. 1Lies t und v1 aus dem Header aus.
2. 2Prüf, dass t nicht älter als 5 Minuten ist, um Replay-Angriffe abzuwehren.
3. 3Berechne den HMAC-SHA256 von "<t>.<raw body>" mit deinem Secret.
4. 4Vergleiche das Ergebnis in konstanter Zeit mit v1 und lehne die Anfrage ab, wenn es nicht übereinstimmt.

Beispiel zur Prüfung

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
  }
});

Wiederholungen

Der erste Versuch erfolgt, sobald das Ereignis eintritt. Ist die Antwort kein 2xx oder schlägt die Verbindung fehl, wird die Zustellung nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden wiederholt. Nach 6 Versuchen gilt die Zustellung als fehlgeschlagen und erscheint im Zustellprotokoll.

Ereignistypen

Abonniere die Typen, die dich interessieren, oder empfange alle. Eine Statusänderung erzeugt genau ein Ereignis, und zwar mit dem Typ, der am besten zum neuen Status passt.

Wenn du keinen Webhook hosten kannst

Dieselben Ereignisse kannst du per Cursor über GET /api/v3/events abrufen. Nutze das bei der lokalen Entwicklung, wenn du keine statische IP hast oder hinter einer Firewall sitzt.

// 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);