API

Porquê duas APIs?

A API clássica de revenda (v2) que todo o setor utiliza envia um formulário para um único endpoint e responde sempre HTTP 200. É exatamente este o formato que o software de painel já feito espera, por isso mantém-se tal como está. Quem escreve o seu próprio sistema, esse, esbarrava constantemente nos limites deste formato: os erros não se distinguiam, o catálogo chegava numa só peça e o estado da encomenda tinha de ser consultado sem fim. A v3 foi escrita para esses casos.

Comparação

Qual devo escolher?

Primeiros passos

1. 1Crie uma chave de API no separador Chaves.
2. 2Obtenha a lista de serviços e veja o id e o esquema de campos do serviço que vai utilizar.
3. 3Valide a encomenda primeiro com preview e só depois a crie.
4. 4Registe um webhook, ou leia o fluxo de eventos, para acompanhar as mudanças de estado.

Endereço base

Todos os caminhos são acrescentados a este endereço. A versão vive no caminho: se alguma vez for necessária uma alteração incompatível, é publicado um caminho novo (v4) e este continua a funcionar sem qualquer mexida. A data de publicação do contrato é devolvida no cabeçalho X-Api-Version em cada resposta.

https://panelfollows.com/api/v3

Autenticação

Envie a sua chave de API como token Bearer no cabeçalho Authorization. Em alternativa, também é aceite o cabeçalho X-Api-Key.

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

A sua chave legacy atual também funciona na v3, por isso pode experimentar já. Em produção utilize uma chave v3: pode ser etiquetada, revogada uma a uma e nunca fica guardada em texto simples.

Arranque rápido

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

Idioma

O idioma da resposta escolhe-se com o cabeçalho Accept-Language ou com o parâmetro ?lang=; o parâmetro prevalece sobre o cabeçalho. O nome do serviço, a descrição do serviço, o nome da categoria, a etiqueta de estado da encomenda, as etiquetas dos campos da encomenda e as mensagens de erro chegam todos nesse idioma.

Os valores de máquina não mudam em idioma nenhum: error.code, order.status, service.type e currency são sempre os mesmos. Escreva as suas condições sobre esses valores e mostre o texto ao utilizador.

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

Formato de pedido e resposta

O corpo do pedido é JSON (application/json); para ensaios rápidos também se aceita form-urlencoded. As respostas são JSON: um recurso isolado é um objeto simples e as listas chegam num envelope com data, has_more e next_cursor. Cada objeto traz um campo object que diz qual é o seu tipo.

Os montantes são devolvidos como CADEIAS decimais ("1.2340"), não como vírgula flutuante. Converta-os para um tipo decimal do seu lado, para não se perderem cêntimos. A moeda é USD.

As marcas temporais seguem o formato RFC 3339 (2026-08-21T00:24:45.255Z).

Erros

Em caso de falha é devolvido um código de estado HTTP real e o corpo traz um único objeto error. O seu código deve decidir com base em error.code: esse valor é estável e não muda com o idioma.

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

Limite de pedidos

600 pedidos por minuto por chave, mais 900 por minuto por IP. Cada resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, para que possa abrandar antes de bater no limite. Ultrapassá-lo devolve 429 com um cabeçalho Retry-After.

Paginação

As listas são paginadas por cursor. Envie limit para o tamanho da página (500 no máximo) e starting_after com o id do último registo da página anterior. Continue até has_more ser false; next_cursor dá-lhe o cursor já pronto para a chamada seguinte. Um limit fora do intervalo não é cortado em silêncio, devolve erro: o corte silencioso deixa o cliente convencido de que trouxe tudo.

Proteção contra duplicados (Idempotency-Key)

Acrescente ao pedido um cabeçalho Idempotency-Key aleatório ao criar uma encomenda. Se a ligação cair e repetir com a mesma chave, não é aberta uma segunda encomenda: é devolvida de novo a resposta do primeiro pedido, com o cabeçalho Idempotent-Replay: true. Os registos ficam guardados 24 horas.

Enviar a mesma chave com um corpo DIFERENTE devolve 409 idempotency_key_reuse. Isto quer dizer, quase sempre, que a geração de chaves está avariada do lado do cliente. Um pedido que falha não queima a chave: corrija o problema e repita com a mesma.

Criar uma encomenda

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

Esquema de campos do serviço

Cada serviço publica numa lista fields os campos que pede na encomenda: nome do campo, tipo, se é obrigatório, os seus limites e ainda uma etiqueta com a respetiva descrição no idioma do utilizador. Quando um campo tem determines_quantity a true, a quantidade é calculada a partir do número de linhas nesse campo.

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

O objeto serviço

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

Pré-visualização da encomenda (execução em seco)

POST /orders/preview valida a encomenda e calcula o custo SEM a abrir. Pode mostrar o preço ao seu cliente e ver de antemão se o seu saldo chega. Nada é descontado do saldo e o fornecedor não é contactado.

Encomendas em lote

Com POST /orders/batch pode enviar até 50 encomendas numa só chamada. Os itens são processados por ordem e cada um recebe o seu próprio resultado: mesmo que um falhe, os restantes são abertos, e vê no resultado do item qual falhou e porquê.

Incorporar objetos relacionados

Se enviar include=service nos endpoints de encomenda, o objeto do serviço fica incorporado na resposta e poupa-lhe um segundo pedido.

Qualidade do serviço e a lista dos melhores serviços

A cada hora o painel mede cada serviço: como terminaram as nossas próprias encomendas (concluídas, canceladas, presas, rejeitadas), com que frequência os clientes pediram reposição ou abriram um pedido de suporte, quanto tempo a entrega demorou realmente e se a fonte ainda o lista. GET /services/top transforma essas medições numa lista classificada, e include=quality anexa o mesmo relatório a qualquer objeto de serviço.

A pontuação (0-100) é uma combinação ponderada de cinco componentes: fiabilidade (42 %, a taxa de sucesso estimada), satisfação (14 %, a partir da taxa de reclamações), velocidade (28 %, logarítmica no tempo de entrega efetivo; 5 minutos dão pontuação máxima, 48 horas dão zero), a pontuação própria do motor de saúde (8 %) e a quantidade de evidência (8 %). Pequenos bónus premeiam a garantia de reposição, uma fonte de confiança e a antiguidade no catálogo. Serviços em revisão, sinalizados pelo motor de saúde ou vindos de uma fonte em observação são pontuados mas nunca classificados.

Filtre por plataforma, slug de categoria ou prateleira (followers, likes, views... partilhadas entre plataformas), ordene por score, speed, reliability, price ou orders, e use group_by=category (ou platform) com per_group para obter uma lista por categoria numa única chamada: exatamente o que uma loja precisa para marcar um serviço 'recomendado' em cada categoria.

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

Referência de endpoints

Esquema OpenAPI

Uma definição legível por máquina de cada endpoint. Entregue este ficheiro a um gerador de clientes (openapi-generator, Kiota) ou ao Postman e obtém um cliente pronto na sua própria linguagem.

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

Perguntas frequentes

Endpoint

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

Autenticação

Em cada pedido é enviado o parâmetro key. Guarde a sua chave em segredo e renove-a de imediato se houver fuga.

Formato de pedido e resposta

Os pedidos são enviados por POST como formulário (application/x-www-form-urlencoded) e as respostas são JSON. Em caso de falha também é devolvido HTTP 200, com { "error": "..." } no corpo.

Também é suportado, embora nunca tenha sido documentado até hoje: pode chamá-la com GET e pode enviar o corpo como application/json.

Limite de pedidos

240 pedidos por minuto por chave, mais 300 por minuto por IP. Os pedidos em excesso são recusados com 429.

Ações e parâmetros

Exemplo

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 }

Respostas em turco

Acrescente /tr ao fim do endereço para receber os nomes dos serviços, as categorias, os estados das encomendas e as mensagens de erro em turco. Os parâmetros, as ações e a estrutura da resposta são exatamente iguais, e a sua chave funciona nos dois endereços. Os campos técnicos (type, refill_status, currency) ficam em inglês por compatibilidade com o padrão.

Passar para a v3

A mudança não é obrigatória. Se quiser mudar, a maior parte da sua lógica de negócio mantém-se, porque os nomes dos parâmetros não mudam; o que muda é o transporte e a forma de ler os erros.

1. 1Passe a chave do campo key no corpo para o cabeçalho Authorization: Bearer.
2. 2Chame o caminho do recurso em vez de action=... (POST /orders em vez de add).
3. 3Verifique a falha pelo código de estado HTTP e por error.code, e não por "existe um campo error?".
4. 4Compare o estado da encomenda com o valor de máquina, não com o texto apresentado.
5. 5Acrescente uma Idempotency-Key ao criar encomendas.
6. 6Substitua a sondagem de estado por webhooks.

Chaves v3

Pode criar tantas chaves quantas precisar, etiquetar cada uma e revogá-las uma a uma. Do nosso lado é guardado apenas um resumo criptográfico da chave.

Chave legacy

A chave única utilizada pela API clássica de revenda (v2). Também funciona na v3. Ao renová-la, a chave antiga fica inválida no instante seguinte.

Segurança

• Guarde a chave numa variável de ambiente, nunca no código-fonte.
• Não ponha a chave em código que corre no navegador; encaminhe os pedidos pelo seu próprio servidor.
• Crie uma chave separada para cada sistema, para que revogar uma não afete as outras.
• Se suspeitar de uma fuga, ponha primeiro a chave nova a funcionar e só depois revogue a antiga.

Porquê webhooks?

A sondagem é ao mesmo tempo lenta e um desperdício: perguntar por milhares de encomendas a cada minuto esgota o seu limite de pedidos e, ainda assim, só fica a saber da mudança minutos depois. Com webhook a mudança chega-lhe no momento em que acontece.

Configuração

1. 1Prepare um endereço https público (endereços locais e de rede interna não são aceites).
2. 2Acrescente o endereço abaixo e guarde a chave de assinatura, que só é mostrada uma vez.
3. 3Verifique a assinatura do seu lado e devolva 2xx.
4. 4Use o botão de teste para confirmar o percurso completo, de ponta a ponta.

O pedido que enviamos

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

Verificação da assinatura

Cada pedido traz um cabeçalho Webhook-Signature: t é a marca temporal e v1 é a assinatura. A assinatura é o HMAC-SHA256 da cadeia "<marca temporal>.<corpo em bruto>" calculado com a sua chave secreta.

1. 1Extraia do cabeçalho os valores t e v1.
2. 2Confirme que t não tem mais de 5 minutos, para travar ataques de repetição.
3. 3Calcule o HMAC-SHA256 da cadeia "<t>.<corpo em bruto>" com a sua chave secreta.
4. 4Compare o resultado com v1 em tempo constante e recuse o pedido se não coincidir.

Exemplo de verificação

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

Novas tentativas

A primeira tentativa é feita no momento do evento. Se a resposta não for 2xx, ou se a ligação não se estabelecer, o envio é repetido ao fim de 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas. Ao fim de 6 tentativas no total, o envio é marcado como falhado e aparece no registo de entregas.

Tipos de evento

Pode subscrever apenas os tipos que lhe interessam ou receber todos. Uma mudança de estado gera exatamente um evento, com o tipo que melhor corresponde ao estado novo.

Se não conseguir alojar um webhook

Os mesmos eventos podem ser lidos com cursor em GET /api/v3/events. Use este caminho enquanto desenvolve localmente, quando não tem IP fixo ou quando está atrás de uma firewall.

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