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.

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