API

Por que existem duas APIs?

A API clássica de revenda (v2), usada pelo setor inteiro, envia um formulário para um único endpoint e sempre responde HTTP 200. Esse é exatamente o formato que os softwares de painel prontos esperam, então ele continua igual. Já quem escreve o próprio sistema vivia esbarrando nas limitações desse formato: não dava para distinguir os erros, o catálogo chegava em uma peça só e o status do pedido precisava ser consultado sem parar. A v3 foi escrita para esse público.

Comparação

Qual das duas eu devo usar?

Primeiros passos

1. 1Crie uma chave de API na aba Chaves.
2. 2Baixe a lista de serviços e veja o id e o esquema de campos do serviço que você vai usar.
3. 3Valide o pedido primeiro com preview e só depois crie de fato.
4. 4Cadastre um webhook, ou leia o stream de eventos, para acompanhar as mudanças de status.

Endereço base

Todos os caminhos são acrescentados a esse endereço. A versão fica no caminho: se algum dia for necessária uma mudança que quebre compatibilidade, um caminho novo (v4) é publicado e o atual continua funcionando sem alteração nenhuma. A data de publicação do contrato volta no cabeçalho X-Api-Version em toda resposta.

https://panelfollows.com/api/v3

Autenticação

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

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

A sua chave legacy atual também funciona na v3, então você já pode testar agora. Em produção, use uma chave v3: ela pode ser rotulada, revogada uma a uma e nunca fica guardada em texto puro.

Início rápido

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

Idioma

O idioma da resposta é escolhido pelo cabeçalho Accept-Language ou pelo parâmetro ?lang=; o parâmetro tem prioridade sobre o cabeçalho. Nome do serviço, descrição do serviço, nome da categoria, rótulo de status do pedido, rótulos dos campos do pedido e mensagens de erro voltam todos no idioma escolhido.

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

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

Formato de requisição e resposta

O corpo da requisição é JSON (application/json); para testes rápidos, form-urlencoded também é aceito. As respostas são JSON: um recurso individual vem como objeto simples e as listas vêm em um envelope com data, has_more e next_cursor. Todo objeto carrega um campo object informando o próprio tipo.

Os valores são retornados como STRINGS decimais ("1.2340"), e não como ponto flutuante. Converta para um tipo decimal do seu lado, para não perder centavos. A moeda é USD.

Os carimbos de data e hora seguem o formato RFC 3339 (2026-08-21T00:24:45.255Z).

Erros

Quando algo falha, volta um código de status HTTP real e o corpo traz um único objeto error. O seu código deve olhar para error.code: esse valor é estável e não muda conforme 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 requisições

600 requisições por minuto por chave, mais 900 por minuto por IP. Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, então você consegue reduzir o ritmo antes de bater no teto. Passar do limite devolve 429 com o cabeçalho Retry-After.

Paginação

As listas são paginadas por cursor. Envie limit para o tamanho da página (no máximo 500) e starting_after com o id do último item da página anterior. Siga até has_more virar false; next_cursor entrega o cursor pronto para a próxima chamada. Um limit fora da faixa não é cortado em silêncio, ele devolve erro: o corte silencioso faz o cliente acreditar que baixou tudo.

Proteção contra duplicidade (Idempotency-Key)

Ao criar um pedido, adicione à requisição um cabeçalho Idempotency-Key aleatório. Se a conexão cair e você tentar de novo com a mesma chave, nenhum segundo pedido é aberto: a resposta da primeira requisição volta igual, com o cabeçalho Idempotent-Replay: true. Os registros ficam guardados por 24 horas.

Enviar a mesma chave com um corpo DIFERENTE devolve 409 idempotency_key_reuse. Isso quase sempre indica que a geração de chaves está quebrada do lado do cliente. Uma requisição que falhou não queima a chave: corrija o problema e tente de novo com ela mesma.

Criando um pedido

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 no array fields quais campos ele pede no pedido: nome do campo, tipo, se é obrigatório, os limites dele e ainda um rótulo com a descrição no idioma do usuário. Quando um campo tem determines_quantity igual a true, a quantidade é calculada pelo número de linhas desse 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évia do pedido (execução seca)

POST /orders/preview valida o pedido e calcula a cobrança SEM criar nada. Você pode mostrar o preço para o seu cliente e conferir antes se o seu saldo cobre o valor. Nada é debitado do saldo e o provedor não é acionado.

Pedidos em lote

Com POST /orders/batch você envia até 50 pedidos em uma única chamada. Os itens são processados em ordem e cada um recebe o próprio resultado: mesmo que um falhe, os outros são criados, e o resultado do item mostra qual falhou e por quê.

Embutir objetos relacionados

Se você mandar include=service nos endpoints de pedido, o objeto do serviço vem embutido na resposta e você economiza uma segunda requisição.

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

A cada hora o painel mede cada serviço: como terminaram os nossos próprios pedidos (concluídos, cancelados, travados, rejeitados), com que frequência os clientes pediram reposição ou abriram um chamado, quanto tempo a entrega levou de verdade e se a fonte ainda o lista. GET /services/top transforma essas medições em uma lista ranqueada, 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: confiabilidade (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ências (8%). Pequenos bônus premiam a garantia de reposição, uma fonte confiável e o tempo de 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 ranqueados.

Filtre por plataforma, slug de categoria ou prateleira (followers, likes, views... compartilhadas entre plataformas), ordene por score, speed, reliability, price ou orders, e use group_by=category (ou platform) com per_group para receber uma lista por categoria em uma ú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 todos os endpoints. Passe esse arquivo para um gerador de clientes (openapi-generator, Kiota) ou para o Postman e você recebe 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

Toda requisição leva o parâmetro key. Mantenha a sua chave em segredo e gere outra na hora se ela vazar.

Formato de requisição e resposta

As requisições são enviadas por POST como formulário (application/x-www-form-urlencoded) e as respostas são JSON. Quando falha, também volta HTTP 200, com { "error": "..." } no corpo.

Também é suportado, ainda que nunca tenha sido documentado: você pode chamar por GET e pode mandar o corpo como application/json.

Limite de requisições

240 requisições por minuto por chave, mais 300 por minuto por IP. As requisições que passarem disso são recusadas 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 final do endereço para receber nome do serviço, categoria, status do pedido e mensagens de erro em turco. Os parâmetros, as ações e a estrutura da resposta são idênticos, e a sua chave funciona nos dois endereços. Os campos técnicos (type, refill_status, currency) continuam em inglês por compatibilidade com o padrão.

Migrando para a v3

A migração não é obrigatória. Se você resolver migrar, boa parte da sua lógica de negócio se mantém, porque os nomes dos parâmetros continuam os mesmos; o que muda é o transporte e o jeito de ler os erros.

1. 1Tire a chave do campo key no corpo e passe para o cabeçalho Authorization: Bearer.
2. 2Chame o caminho do recurso no lugar de action=... (POST /orders em vez de add).
3. 3Verifique a falha pelo código de status HTTP e por error.code, e não perguntando "tem um campo error?".
4. 4Compare o status do pedido pelo valor de máquina, não pelo texto exibido.
5. 5Adicione uma Idempotency-Key ao criar pedidos.
6. 6Troque a consulta contínua de status por webhooks.

Chaves v3

Você pode criar quantas chaves quiser, rotular cada uma e revogá-las individualmente. Do nosso lado fica guardado apenas um resumo criptográfico da chave.

Chave legacy

A chave única usada pela API clássica de revenda (v2). Ela também funciona na v3. Quando você gera outra, a antiga perde a validade na mesma hora.

Segurança

• Guarde a chave em uma variável de ambiente, nunca no código-fonte.
• Não coloque a chave em código que roda no navegador; passe as chamadas pelo seu próprio servidor.
• Crie uma chave separada para cada sistema, assim revogar uma não afeta as outras.
• Se desconfiar de um vazamento, coloque a chave nova em uso primeiro e só depois revogue a antiga.

Por que webhooks?

A consulta contínua é lenta e ainda por cima desperdiça recursos: perguntar por milhares de pedidos a cada minuto consome todo o seu limite de requisições e mesmo assim você só descobre a mudança minutos depois. Com webhook a mudança chega até você no instante em que acontece.

Configuração

1. 1Prepare um endereço https público (endereços locais e de rede interna não são aceitos).
2. 2Adicione o endereço abaixo e guarde a chave de assinatura, que aparece uma única vez.
3. 3Confira a assinatura do seu lado e responda 2xx.
4. 4Use o botão de teste para validar o caminho inteiro, de ponta a ponta.

O que a gente envia

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

Conferindo a assinatura

Toda requisição carrega o cabeçalho Webhook-Signature: t é o carimbo de data e hora e v1 é a assinatura. A assinatura é o HMAC-SHA256 da string "<carimbo de data e hora>.<corpo bruto>" calculado com a sua chave secreta.

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

Exemplo de conferência

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 acontece no instante do evento. Se a resposta não for 2xx, ou se a conexão não se estabelecer, o envio é repetido depois de 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas. Depois de 6 tentativas no total, o envio é marcado como falho e aparece no log de entregas.

Tipos de evento

Você pode assinar só os tipos que interessam ou receber todos. Uma mudança de status gera exatamente um evento, com o tipo que melhor combina com o status novo.

Se você não puder hospedar um webhook

Os mesmos eventos podem ser lidos por cursor em GET /api/v3/events. Use esse caminho quando estiver desenvolvendo localmente, quando não tiver IP fixo ou quando estiver atrás de um 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);