API

Pourquoi deux API ?

L’API revendeur classique (v2), utilisée par tout le secteur, reçoit un formulaire envoyé en POST sur un endpoint unique et répond toujours avec un code HTTP 200. C’est exactement le format qu’attendent les logiciels de panel prêts à l’emploi, elle reste donc telle quelle. Les développeurs qui écrivent leurs propres systèmes se heurtaient sans cesse à ses limites : impossible de distinguer les erreurs, le catalogue arrivait d’un seul bloc et il fallait interroger le statut des commandes en permanence. La v3 a été conçue pour eux.

Comparatif

Laquelle choisir ?

Premiers pas

1. 1Créez une clé API dans l’onglet Clés.
2. 2Récupérez la liste des services et relevez l’id et le schéma de champs du service dont vous avez besoin.
3. 3Validez d’abord la commande avec preview, puis créez-la.
4. 4Enregistrez un webhook, ou lisez le flux d’événements, pour suivre les changements de statut.

URL de base

Chaque chemin s’ajoute à cette URL. La version figure dans le chemin : si un changement incompatible devient un jour nécessaire, un nouveau chemin (v4) sera publié et celui-ci continuera de fonctionner sans aucune modification. La date de publication du contrat est renvoyée dans l’en-tête X-Api-Version de chaque réponse.

https://panelfollows.com/api/v3

Authentification

Envoyez votre clé API comme jeton Bearer dans l’en-tête Authorization. L’en-tête X-Api-Key est également accepté comme alternative.

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

Votre clé classique existante fonctionne aussi sur la v3, vous pouvez donc l’essayer tout de suite. En production, utilisez une clé v3 : elle peut porter un libellé, être révoquée individuellement et n’est jamais stockée en clair.

Démarrage rapide

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

Langue

Choisissez la langue des réponses avec l’en-tête Accept-Language ou le paramètre ?lang= (le paramètre est prioritaire). Les noms et descriptions des services, les noms de catégories, les libellés de statut des commandes, les libellés des champs de commande et les messages d’erreur sont alors renvoyés dans cette langue.

Les valeurs machine ne changent jamais selon la langue : error.code, order.status, service.type et currency restent toujours identiques. Basez votre logique sur ces valeurs et affichez le texte à vos utilisateurs.

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

Format des requêtes et des réponses

Le corps des requêtes est en JSON (application/json) ; le format form-urlencoded est aussi accepté pour les tests rapides. Les réponses sont en JSON : une ressource unique est un objet simple, et les listes arrivent dans une enveloppe contenant data, has_more et next_cursor. Chaque objet porte un champ object qui indique son type.

Les montants sont des CHAÎNES décimales ("1.2340"), pas des nombres à virgule flottante. Convertissez-les en type décimal de votre côté pour ne perdre aucune fraction. Tous les montants sont en USD.

Les horodatages sont au format RFC 3339 (2026-08-21T00:24:45.255Z).

Erreurs

En cas d’échec, l’API renvoie un vrai code de statut HTTP et un corps contenant un unique objet error. Votre code doit se baser sur error.code : cette valeur est stable et ne change jamais selon la langue.

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

Limites de requêtes

600 requêtes par minute et par clé, plus 900 par minute et par IP. Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset, ce qui vous permet de ralentir avant d’atteindre la limite. Au-delà, l’API renvoie 429 avec un en-tête Retry-After.

Pagination

Les listes sont paginées par curseur. Envoyez limit pour la taille de page (500 maximum) et starting_after avec l’id du dernier élément de la page précédente. Continuez jusqu’à ce que has_more vaille false ; next_cursor vous donne le curseur de l’appel suivant. Une valeur de limit hors plage n’est pas ramenée silencieusement dans les bornes, elle provoque une erreur : un plafonnement silencieux ferait croire au client qu’il a tout récupéré.

Protection contre les doublons (Idempotency-Key)

Ajoutez un en-tête Idempotency-Key aléatoire lorsque vous créez une commande. Si la connexion est coupée et que vous réessayez avec la même clé, aucune deuxième commande n’est créée : la première réponse est renvoyée à nouveau, avec l’en-tête Idempotent-Replay: true. Les enregistrements sont conservés 24 heures.

Envoyer la même clé avec un corps DIFFÉRENT renvoie 409 idempotency_key_reuse. Cela signifie presque toujours que la génération des clés est défaillante côté client. Une requête échouée ne consomme pas la clé : corrigez le problème et réessayez avec la même.

Créer une commande

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

Schéma des champs d’un service

Chaque service publie les champs dont il a besoin dans un tableau fields : nom, type, caractère obligatoire ou non, limites, ainsi qu’un libellé et une description dans votre langue. Lorsqu’un champ a determines_quantity à true, la quantité est déduite du nombre de lignes qu’il contient.

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

L’objet service

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

Aperçu de commande (simulation)

POST /orders/preview valide une commande et calcule son coût SANS la créer. Affichez le prix à votre client et vérifiez à l’avance que votre solde suffit. Rien n’est débité et aucun fournisseur n’est contacté.

Commandes groupées

POST /orders/batch accepte jusqu’à 50 commandes en un seul appel. Les éléments sont traités dans l’ordre et chacun renvoie son propre résultat : si l’un échoue, les autres sont tout de même créés, et vous savez exactement lequel a échoué et pourquoi.

Inclure les objets liés

Passez include=service sur les endpoints de commande : l’objet service est intégré à la réponse, ce qui vous évite une seconde requête.

Qualité des services et sélection des meilleurs

Toutes les heures, le panel évalue chaque service : comment ont abouti nos propres commandes (terminées, annulées, bloquées, rejetées), à quelle fréquence les clients ont demandé un remplacement ou ouvert un ticket, combien de temps la livraison a réellement pris, et si la source le propose toujours. GET /services/top transforme ces mesures en une sélection classée, et include=quality ajoute le même rapport à n’importe quel objet service.

Le score (0-100) est une combinaison pondérée de cinq composantes : fiabilité (42 %, le taux de réussite estimé), satisfaction (14 %, d’après le taux de réclamations), vitesse (28 %, logarithmique selon le délai de livraison effectif ; 5 minutes donnent la note maximale, 48 heures donnent zéro), le score propre du moteur de santé (8 %) et la quantité de preuves (8 %). De petits bonus récompensent une garantie de remplacement, une source de confiance et l’ancienneté dans le catalogue. Les services en cours d’examen, signalés par le moteur de santé ou provenant d’une source en période probatoire sont notés, mais jamais classés.

Filtrez par plateforme, slug de catégorie ou rayon (followers, likes, views… communs à toutes les plateformes), triez par score, vitesse, fiabilité, prix ou nombre de commandes, et utilisez group_by=category (ou platform) avec per_group pour obtenir une sélection par catégorie en un seul appel : exactement ce qu’il faut à une boutique pour mettre en avant un service « recommandé » dans chaque catégorie.

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

Référence des endpoints

Schéma OpenAPI

Une définition lisible par machine de chaque endpoint. Fournissez ce fichier à un générateur de clients (openapi-generator, Kiota) ou à Postman pour obtenir un client prêt à l’emploi dans votre propre langage.

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

Questions fréquentes

Endpoint

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

Authentification

Chaque requête contient un paramètre key. Gardez votre clé secrète et régénérez-la immédiatement en cas de fuite.

Format des requêtes et des réponses

Les requêtes sont envoyées en POST sous forme de formulaire (application/x-www-form-urlencoded) et les réponses sont en JSON. Les échecs renvoient eux aussi HTTP 200, avec { "error": "..." } dans le corps.

Également pris en charge, bien que jamais documenté jusqu’ici : vous pouvez l’appeler en GET et envoyer le corps en application/json.

Limites de requêtes

240 requêtes par minute et par clé, plus 300 par minute et par IP. Les requêtes excédentaires sont rejetées avec un code 429.

Actions et paramètres

Exemple

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 }

Réponses en turc

Ajoutez /tr à l’URL pour recevoir les noms de services, les catégories, les statuts de commande et les messages d’erreur en turc. Les paramètres, les actions et la structure des réponses sont identiques, et votre clé fonctionne sur les deux URL. Les champs techniques (type, refill_status, currency) restent en anglais pour garantir la compatibilité avec le standard.

Passer à la v3

La migration est facultative. Si vous franchissez le pas, l’essentiel de votre logique métier reste valable, car les noms de paramètres sont inchangés. Ce qui change, c’est le transport et la façon de lire les erreurs.

1. 1Déplacez la clé du champ key du corps vers l’en-tête Authorization: Bearer.
2. 2Appelez un chemin de ressource au lieu de action=... (POST /orders au lieu de add).
3. 3Détectez les échecs avec le statut HTTP et error.code, plutôt qu’en vérifiant la présence d’un champ error.
4. 4Comparez le statut de commande à la valeur machine, pas au texte affiché.
5. 5Ajoutez un en-tête Idempotency-Key lorsque vous créez des commandes.
6. 6Remplacez l’interrogation du statut (polling) par des webhooks.

Clés v3

Créez autant de clés que nécessaire, donnez un libellé à chacune et révoquez-les individuellement. De notre côté, seule une empreinte cryptographique de la clé est conservée.

Clé classique

La clé unique utilisée par l’API revendeur classique (v2). Elle fonctionne aussi sur la v3. La régénérer invalide immédiatement l’ancienne valeur.

Sécurité

• Conservez la clé dans une variable d’environnement, jamais dans le code source.
• Ne placez jamais de clé dans du code exécuté par un navigateur : faites passer les appels par votre propre serveur.
• Créez une clé distincte par système, pour que la révocation de l’une n’affecte pas les autres.
• En cas de soupçon de fuite, déployez d’abord la nouvelle clé, puis révoquez l’ancienne.

Pourquoi des webhooks ?

L’interrogation régulière (polling) est à la fois lente et coûteuse : demander le statut de milliers de commandes chaque minute consomme votre limite de requêtes, et vous découvrez quand même les changements avec plusieurs minutes de retard. Avec les webhooks, le changement vous parvient au moment où il se produit.

Mise en place

1. 1Préparez une URL https publique (les adresses locales et de réseau privé sont refusées).
2. 2Ajoutez l’URL ci-dessous et conservez le secret de signature, affiché une seule fois.
3. 3Vérifiez la signature de votre côté et répondez avec un code 2xx.
4. 4Utilisez le bouton de test pour valider toute la chaîne de bout en bout.

Ce que nous envoyons

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

Vérifier la signature

Chaque requête contient un en-tête Webhook-Signature, où t est l’horodatage et v1 la signature. La signature est le HMAC-SHA256 de la chaîne "<timestamp>.<raw body>", calculé avec votre secret.

1. 1Extrayez t et v1 de l’en-tête.
2. 2Vérifiez que t ne date pas de plus de 5 minutes, pour bloquer les rejeux.
3. 3Calculez le HMAC-SHA256 de "<t>.<raw body>" avec votre secret.
4. 4Comparez-le à v1 en temps constant et rejetez la requête s’ils ne correspondent pas.

Exemple de vérification

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

Nouvelles tentatives

La première tentative a lieu dès que l’événement se produit. Si la réponse n’est pas 2xx ou si la connexion échoue, l’envoi est relancé après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures. Au bout de 6 tentatives, l’envoi est marqué comme échoué et apparaît dans le journal des envois.

Types d’événements

Abonnez-vous aux types qui vous intéressent, ou recevez-les tous. Un changement de statut produit exactement un événement, du type qui correspond le mieux au nouveau statut.

Si vous ne pouvez pas héberger de webhook

Les mêmes événements peuvent être lus avec un curseur depuis GET /api/v3/events. Utilisez-le pendant le développement en local, si vous n’avez pas d’IP fixe ou si vous êtes derrière un pare-feu.

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