API

Waarom twee API's?

De klassieke reseller-API (v2) die de hele branche gebruikt, stuurt een formulier naar één endpoint en antwoordt altijd met HTTP 200. Dat is precies het formaat dat kant-en-klare panelsoftware verwacht, dus het blijft ongewijzigd. Wie zijn eigen systeem schrijft, liep juist voortdurend tegen de grenzen ervan aan: fouten waren niet van elkaar te onderscheiden, de catalogus kwam in één stuk binnen en de status van een bestelling moest eindeloos worden opgevraagd. v3 is daarvoor geschreven.

Vergelijking

Welke moet ik kiezen?

Aan de slag

1. 1Maak een API-sleutel aan op het tabblad Sleutels.
2. 2Haal de dienstenlijst op en bekijk de id en het veldschema van de dienst die je nodig hebt.
3. 3Controleer de bestelling eerst met preview en maak hem daarna pas aan.
4. 4Registreer een webhook, of lees de gebeurtenisstroom, om statuswijzigingen te volgen.

Basisadres

Alle paden worden achter dit adres geplakt. De versie zit in het pad: mocht er ooit een brekende wijziging nodig zijn, dan verschijnt er een nieuw pad (v4) en blijft dit pad ongewijzigd werken. De publicatiedatum van het contract komt bij elk antwoord terug in de header X-Api-Version.

https://panelfollows.com/api/v3

Authenticatie

Stuur je API-sleutel als Bearer-token mee in de header Authorization. Als alternatief wordt ook de header X-Api-Key geaccepteerd.

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

Je bestaande legacy-sleutel werkt ook op v3, dus je kunt meteen aan de slag. Gebruik in productie een v3-sleutel: die kun je labelen, stuk voor stuk intrekken, en hij wordt nooit als platte tekst opgeslagen.

Snelle start

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

Taal

De taal van het antwoord kies je met de header Accept-Language of met de parameter ?lang=; de parameter gaat boven de header. Dienstnamen, dienstomschrijvingen, categorienamen, het statuslabel van een bestelling, de labels van bestelvelden en foutmeldingen komen allemaal in die taal terug.

Machinewaarden veranderen in geen enkele taal: error.code, order.status, service.type en currency zijn altijd hetzelfde. Bouw je logica op die waarden en laat de tekst aan je gebruikers zien.

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

Formaat van verzoek en antwoord

De body van een verzoek is JSON (application/json); voor snelle proefjes wordt ook form-urlencoded geaccepteerd. Antwoorden zijn JSON: een losse resource is een gewoon object, en lijsten komen in een envelop met data, has_more en next_cursor. Elk object bevat een veld object dat zijn type benoemt.

Bedragen komen terug als decimale TEKENREEKSEN ("1.2340"), niet als getallen met drijvende komma. Zet ze aan jouw kant om naar een decimaal type, zodat er geen centen verloren gaan. De valuta is USD.

Tijdstempels hebben het formaat RFC 3339 (2026-08-21T00:24:45.255Z).

Fouten

Bij een fout komt er een echte HTTP-statuscode terug en bevat de body één enkel error-object. Je code hoort te kijken naar error.code: die waarde ligt vast en verandert niet mee met de taal.

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

Verzoeklimiet

600 verzoeken per minuut per sleutel, plus 900 per minuut per IP. Elk antwoord bevat RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset, zodat je jezelf kunt afremmen voordat je tegen de limiet aan loopt. Ga je eroverheen, dan volgt 429 met een Retry-After-header.

Paginering

Lijsten worden gepagineerd met een cursor. Stuur limit voor de paginagrootte (maximaal 500) en starting_after met de id van het laatste item op de vorige pagina. Ga door tot has_more false is; next_cursor geeft je de cursor voor het volgende verzoek. Een limit buiten het bereik wordt niet stilletjes bijgeknipt maar geeft een fout: stil bijknippen laat een client geloven dat hij alles heeft opgehaald.

Bescherming tegen dubbele bestellingen (Idempotency-Key)

Voeg bij het aanmaken van een bestelling een willekeurige Idempotency-Key-header toe. Valt de verbinding weg en probeer je het opnieuw met dezelfde sleutel, dan komt er geen tweede bestelling: het antwoord van het eerste verzoek komt ongewijzigd terug, met de header Idempotent-Replay: true. Deze gegevens worden 24 uur bewaard.

Stuur je dezelfde sleutel met een ANDERE body, dan volgt 409 idempotency_key_reuse. Dat betekent bijna altijd dat het genereren van sleutels aan de clientkant stuk is. Een mislukt verzoek verbrandt de sleutel niet: los het probleem op en probeer het opnieuw met dezelfde sleutel.

Een bestelling aanmaken

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

Veldschema van een dienst

Elke dienst publiceert in de array fields welke velden hij bij een bestelling vraagt: veldnaam, type, of het verplicht is, de grenzen ervan en een label met omschrijving in de taal van de gebruiker. Staat determines_quantity van een veld op true, dan wordt de hoeveelheid berekend uit het aantal regels in dat veld.

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

Het dienstobject

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

Bestelling vooraf bekijken (droge run)

POST /orders/preview controleert een bestelling en berekent de kosten ZONDER hem aan te maken. Je kunt je klant de prijs laten zien en vooraf nagaan of je saldo toereikend is. Er wordt niets van je saldo afgeschreven en de leverancier wordt niet benaderd.

Bestellingen in bulk

Met POST /orders/batch stuur je maximaal 50 bestellingen in één aanroep. De regels worden op volgorde verwerkt en elke regel krijgt zijn eigen resultaat: mislukt er één, dan worden de andere gewoon aangemaakt en zie je in het resultaat van die regel welke misging en waarom.

Gerelateerde objecten insluiten

Stuur je include=service mee op de bestel-endpoints, dan wordt het dienstobject in het antwoord ingesloten en hoef je geen tweede verzoek te doen.

Endpointreferentie

OpenAPI-schema

Een machineleesbare beschrijving van elk endpoint. Geef dit bestand aan een clientgenerator (openapi-generator, Kiota) of aan Postman en je krijgt een kant-en-klare client in je eigen taal.

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

Veelgestelde vragen

Endpoint

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

Authenticatie

Bij elk verzoek gaat de parameter key mee. Houd je sleutel geheim en vernieuw hem meteen als hij is uitgelekt.

Formaat van verzoek en antwoord

Verzoeken worden met POST als formulier verstuurd (application/x-www-form-urlencoded) en antwoorden zijn JSON. Ook bij een fout komt HTTP 200 terug, met { "error": "..." } in de body.

Ook ondersteund, al is het tot nu toe nooit gedocumenteerd: je kunt de API met GET aanroepen en je mag de body als application/json versturen.

Verzoeklimiet

240 verzoeken per minuut per sleutel, plus 300 per minuut per IP. Verzoeken daarboven worden geweigerd met 429.

Acties en parameters

Voorbeeld

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 }

Antwoorden in het Turks

Zet /tr achter het adres om dienstnamen, categorieën, bestelstatussen en foutmeldingen in het Turks te ontvangen. De parameters, de acties en de opbouw van het antwoord zijn exact hetzelfde, en je sleutel werkt op beide adressen. Technische velden (type, refill_status, currency) blijven Engels om standaardcompatibel te blijven.

Overstappen naar v3

Overstappen is niet verplicht. Doe je het wel, dan blijft het grootste deel van je bedrijfslogica overeind omdat de parameternamen hetzelfde blijven; wat verandert, is het transport en de manier waarop je fouten uitleest.

1. 1Verplaats de sleutel van het veld key in de body naar de header Authorization: Bearer.
2. 2Roep een resourcepad aan in plaats van action=... (POST /orders in plaats van add).
3. 3Controleer op fouten via de HTTP-statuscode en error.code in plaats van via "is er een error-veld".
4. 4Vergelijk de bestelstatus met de machinewaarde, niet met de weergegeven tekst.
5. 5Voeg een Idempotency-Key toe bij het aanmaken van bestellingen.
6. 6Vervang het opvragen van status door webhooks.

v3-sleutels

Je kunt zoveel sleutels aanmaken als je nodig hebt, ze allemaal labelen en stuk voor stuk intrekken. Aan onze kant bewaren we alleen een cryptografische samenvatting van de sleutel.

Legacy-sleutel

De enige sleutel die de klassieke reseller-API (v2) gebruikt. Hij werkt ook op v3. Vernieuw je hem, dan vervalt de oude waarde onmiddellijk.

Beveiliging

• Bewaar de sleutel in een omgevingsvariabele, nooit in je broncode.
• Zet geen sleutel in code die in de browser draait; laat de verzoeken via je eigen server lopen.
• Maak per systeem een aparte sleutel, zodat het intrekken van de ene de andere niet raakt.
• Vermoed je een lek, neem dan eerst de nieuwe sleutel in gebruik en trek daarna pas de oude in.

Waarom webhooks?

Voortdurend opvragen is traag én verspillend: elke minuut duizenden bestellingen bevragen slurpt je verzoeklimiet op en toch hoor je pas minuten later van een wijziging. Met een webhook bereikt de wijziging je op het moment dat ze plaatsvindt.

Instellen

1. 1Zorg voor een openbaar https-adres (lokale adressen en adressen in het interne netwerk worden geweigerd).
2. 2Voeg het adres hieronder toe en bewaar de ondertekeningssleutel die één keer wordt getoond.
3. 3Controleer de handtekening aan jouw kant en antwoord met 2xx.
4. 4Gebruik de testknop om het hele traject van begin tot eind te bevestigen.

Wat wij versturen

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

De handtekening controleren

Elk verzoek draagt een Webhook-Signature-header: t is het tijdstempel en v1 is de handtekening. De handtekening is de HMAC-SHA256 van de tekenreeks "<tijdstempel>.<ruwe body>", berekend met jouw geheime sleutel.

1. 1Haal de waarden t en v1 uit de header.
2. 2Controleer dat t niet ouder is dan 5 minuten, om herhaalaanvallen te blokkeren.
3. 3Bereken de HMAC-SHA256 van "<t>.<ruwe body>" met jouw geheime sleutel.
4. 4Vergelijk het resultaat in constante tijd met v1 en weiger het verzoek als het niet klopt.

Voorbeeld van controle

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

Opnieuw proberen

De eerste poging vindt plaats op het moment van de gebeurtenis. Komt er iets anders dan 2xx terug, of lukt de verbinding niet, dan wordt de bezorging opnieuw geprobeerd na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur. Na in totaal 6 pogingen wordt de bezorging als mislukt gemarkeerd en verschijnt ze in het bezorglogboek.

Gebeurtenistypes

Je abonneert je op de types die je nodig hebt, of je ontvangt ze allemaal. Eén statuswijziging levert precies één gebeurtenis op, met het type dat het beste bij de nieuwe status past.

Als je geen webhook kunt hosten

Dezelfde gebeurtenissen lees je met een cursor uit via GET /api/v3/events. Gebruik deze weg tijdens lokaal ontwikkelen, als je geen vast IP hebt of als je achter een firewall zit.

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