Genel bakış

Katıl Bi API'si ile kendi sitende aldığın siparişleri otomatik olarak Katıl Bi'ye iletebilirsin: fiyatı sor, siparişi ver (tutar reklam bakiyenden bloke edilir), durumunu takip et, kanıtları ve kanıt görsellerini çek. Temel URL: https://katilbi.com/api/v1. Tüm yanıtlar JSON, tutarlar kuruş cinsindendir (1 ₺ = 100).

Kanıtlarda görevi yapan kullanıcının kimliği paylaşılmaz; kanıtlar Kanıt #numara ile anılır.

Erişim izni

API erişimi başvuruyla açılır. Görev veren panelindeki API erişimi bölümünden ya da API entegrasyonu sayfasından talep gönder; Katıl Bi ekibi onaylayınca aynı bölümde anahtarını oluşturur ve webhook adresini tanımlarsın. Erişim kapatılırsa mevcut anahtarlar 403 api_disabled döner.

Kimlik doğrulama

Tüm istekler HTTPS üzerinden yapılır ve anahtarı Authorization: Bearer grv_live_… başlığında bekler. Anahtarı yalnızca sunucu tarafında sakla. grv_test_ ile başlayan test anahtarları sipariş açmaz.

curl https://katilbi.com/api/v1/balance \
  -H "Authorization: Bearer grv_live_8f21..."

Hata kodları & limitler

Anahtar başına dakikada 120 istek; aşıldığında 429 ve Retry-After başlığı döner. Hatalarda gövde {"message": "…", "code": "…"} biçimindedir.

SMM API (tek uç)

SMM panelleri (PerfectPanel ve türevleri) Katıl Bi'yi sağlayıcı olarak ekleyebilir. Panelin beklediği standart protokol desteklenir: tek uç, application/x-www-form-urlencoded gövde, key + action. Yukarıdaki REST uçlarından ayrıdır, Bearer başlığı kullanılmaz.

Desteklenen action değerleri: services · add · status · balance · cancel. Bir service Katıl Bi görev tipine, bir order Katıl Bi görevine karşılık gelir. Sipariş açılınca tutar reklam bakiyesinden bloke edilir ve görev yönetici onayına düşer (durum: Pending).

curl -X POST https://katilbi.com/api/v2 \
  -d "key=grv_live_8f21..." \
  -d "action=add" \
  -d "service=14" \
  -d "link=https://instagram.com/hesabim" \
  -d "quantity=100"

// {"order": 1042}

Durum karşılıkları: Pending (onay bekliyor) · In progress (yayında) · Completed · Partial (kısmen tamamlanıp iptal edildi) · Canceled. Hatalar standart biçimdedir: HTTP 200 + {"error": "..."}. refill desteklenmez; Katıl Bi'de kaldırılan çalışma kontenjan yeniden açılarak telafi edilir.

GET /task-types

Sipariş verilebilen görev türleri: slug, name, category, unit_price (kuruş), min_quantity (bu türde verilebilecek en az adet), duration.

[ { "slug": "google-maps-yorum", "name": "Google Maps: Yorum", "unit_price": 1400 } ]

POST /quote

Sipariş vermeden önce tutarı ve bakiyenin yetip yetmediğini hesaplar. Gövde: type, quantity. Adet türün min_quantity değerinin altındaysa 422 below_min_quantity döner (aynı kural POST /tasks için de geçerlidir). Kademeli adet indirimi otomatik uygulanır.

{ "unit_price": 1400, "subtotal": 70000, "discount": 3500, "total": 66500, "ad_balance": 150000, "enough_balance": true }

POST /tasks

Sipariş verir. Tutar reklam bakiyenden bloke edilir, sipariş Katıl Bi ekibinin onayına gider (pending_approval) ve onaylanınca yayına alınır. Kullanılmayan tutar iptal ya da tamamlanmada bakiyene iade edilir.

curl -X POST https://katilbi.com/api/v1/tasks \
  -H "Authorization: Bearer grv_live_..." -H "Content-Type: application/json" \
  -d '{"type":"google-maps-yorum","title":"Kafe yorumu","quantity":50,"external_ref":"SIP-10231"}'

{ "id": 1838, "external_ref": "SIP-10231", "status": "pending_approval", "quantity": 50, "filled": 0, "progress": 0, "budget_total": 66500 }

GET /tasks · GET /tasks/:id

Siparişlerini sayfalı listeler (?status=active&external_ref=SIP-10231&page=2&per_page=50) ya da tek siparişi döner.

POST /tasks/:id/status

Gövde action: pause, resume, cancel (iptal talebi oluşturur; Katıl Bi ekibi onaylayınca kalan tutar bakiyene iade edilir, isteğe bağlı reason), submit (taslağı onaya gönder).

GET /tasks/:id/submissions

Bir siparişin kanıtları, en yeniden eskiye (?status=approved). Görsel adresleri üç boyutta gelir:

{ "data": [ { "id": 5821, "proof_no": "Kanıt #5821", "external_ref": "SIP-10231", "status": "approved",
    "files": [ { "thumb": "https://…", "url": "https://…", "original": "https://…" } ] } ],
  "meta": { "page": 1, "last_page": 3, "total": 61 } }

GET /submissions

Tüm siparişlerindeki kanıtlar: ?task_id=1838&status=pending&page=1.

GET /submissions/:id

Tek bir kanıtı döner (alanlar yukarıdakiyle aynı).

POST /submissions/:id/approve · reject

Yalnızca kanıt incelemesini kendin yaptığın siparişlerde kullanılır. Varsayılan olarak kanıtları Katıl Bi ekibi inceler; bu durumda 403 platform_review döner. Red için gövdede reason ve isteğe bağlı allow_retry.

GET /balance

{ "ad_balance": 53125, "locked_ad_balance": 290875, "currency": "TRY" }

ad_balance sipariş için kullanılabilir bakiye, locked_ad_balance yayındaki siparişlere bloke edilmiş tutardır.

Olay tipleri

Panelden webhook adresi tanımladığında aşağıdaki olaylar JSON POST olarak gönderilir; gövde {event, created_at, data}. Olay geldiğinde ayrıntıyı ilgili uç noktadan çek.

İmza doğrulama

Her istek X-Gorevle-Signature başlığı taşır: ham gövdenin webhook gizli anahtarınla HMAC-SHA256 özeti (hex). Karşılaştırmayı sabit zamanlı yap.

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);
if (! hash_equals($expected, $_SERVER['HTTP_X_GOREVLE_SIGNATURE'] ?? '')) { http_response_code(401); exit; }