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.

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