API Dokümantasyonu

Taban adres

https://app.flowoy.com

Sürüm

v1

Kimlik

X-API-Key

Sınır

120 istek/dk

Plan

Profesyonel

Hızlı başlangıç

Kargo bildirimi kuran bir ekibin izlediği yol — beş çağrı, sırayla.

# 1 — anahtar doğru mu, hangi hesaba bağlı?
curl https://app.flowoy.com/api/v1/me -H "X-API-Key: $KEY"

# 2 — hangi şablon kaç değişken istiyor?
curl https://app.flowoy.com/api/v1/templates -H "X-API-Key: $KEY"

# 3 — müşteriyi deftere yaz (izniyle birlikte)
curl -X POST https://app.flowoy.com/api/v1/customers \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"phone":"05551112233","firstName":"Ayşe","marketingConsent":true}'

# 4 — kargoya verilince şablonu gönder
curl -X POST https://app.flowoy.com/api/v1/messages/template \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"phone":"05551112233","template":"kargo_takip_butonlu",
       "variables":{"1":"Ayşe","2":"SP-1042","3":"Aras Kargo",
                    "4":"7788991122","button_0_1":"xCpXi4v"}}'

# 5 — sonucu webhook ile bekleyin; webhook yoksa durumu sorun
curl https://app.flowoy.com/api/v1/messages/96a67fd4-… -H "X-API-Key: $KEY"

Dördüncü adımın döndürdüğü messageId değerini kendi sisteminizde siparişin yanına saklayın. Bir sorun olduğunda destekle konuşurken tek referans odur.

Kimlik doğrulama

Her istek X-API-Key başlığı ister. Anahtarsız istek 401 döner — API ile hesabınız olmadan hiçbir işlem yapılamaz.

curl https://app.flowoy.com/api/v1/me \
  -H "X-API-Key: ptf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Anahtar nereden alınır

Panel → Ayarlar → API Anahtarları → Yeni Anahtar. Anahtar yalnız bir kez gösterilir; kaybederseniz yenisini üretip eskisini silin.

• Anahtar hesabınıza bağlıdır; başka hesabın verisine erişemez.
• API erişimi Profesyonel planında açıktır. Plan düşerse mevcut anahtarlar da 403 plan_required döner.
• Anahtar biçimi ptf_ + 32 karakter. İlk 12 karakter arama ön eki olarak saklanır, gerisi yalnız hash hâlinde durur — bizde bile düz metin karşılığı yoktur.

Hız sınırı

Anahtar başına dakikada 120 istek. Her yanıt kalan hakkı X-RateLimit-Remaining başlığında taşır. Sınır aşılınca 429 ve Retry-After döner — o kadar saniye bekleyip devam edin.

Bunun dışında gönderim, WhatsApp numaranızın kendi saatlik ve günlük kotasına da tabidir. Toplu iş yaparken iki sınırı da gözetin; 25'lik partiler için /messages/bulk ucunu kullanın.

Yanıt ve hatalar

Başarılı her yanıt ok: true, her hata ok: false ve makine tarafından okunabilir bir error kodu taşır.

Değişken hatası neye benzer

Eksik parametreyi Meta'nın 132000 ailesinden değil, bizden ve adıyla öğrenirsiniz:

{
  "ok": false,
  "error": "variables",
  "missing": ["button_0_1"],
  "unexpected": [],
  "expected": {
    "bodyVariableCount": 4,
    "dynamicButtons": [{ "anahtar": "button_0_1", "metin": "Kargomu takip et" }]
  }
}

Uç noktalar

{ "ok": true, "data": {
  "company": "Örnek Market",
  "plan": "proexpert",
  "phone": "+90 5xx xxx xx xx",
  "rateLimitPerMinute": 120
} }

Webhook aboneliği

Durumu yoklamak yerine biz size haber verelim. Her olay HTTPS adresinize imzalı olarak POST edilir.

curl -X POST https://app.flowoy.com/api/v1/webhooks \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://sizin-siteniz.com/flowoy/webhook",
       "events":["message.delivered","message.failed","message.received"]}'

# → 201 — secret YALNIZ burada gösterilir, saklayın
{ "ok": true, "data": {
  "id": "8b3c8f5d-…",
  "url": "https://sizin-siteniz.com/flowoy/webhook",
  "events": ["message.delivered", "message.failed", "message.received"],
  "secret": "whsec_4Kc…"
} }

Olaylar

// Size gelen gövde
{
  "olayId": "c1f0a0f2-…",
  "olay": "message.delivered",
  "zaman": "2026-10-31T09:14:22.418Z",
  "veri": {
    "messageId": "96a67fd4-…",
    "to": "905551112233",
    "status": "delivered",
    "error": null,
    "errorCode": null,
    "at": "2026-10-31T09:14:21.000Z"
  }
}

İmza doğrulama

Her iletim üç başlık taşır. Gövdeyi işlemeden önce imzayı doğrulayın; aksi hâlde adresinize herkes sahte olay gönderebilir.

Zaman damgası imzaya dahildir: aksi hâlde eski bir gövde aynı imzayla sonsuza kadar tekrar oynatılabilirdi.

PHP

$govde = file_get_contents('php://input');
$zaman = $_SERVER['HTTP_X_FLOWOY_TIMESTAMP'] ?? '';
$imza  = $_SERVER['HTTP_X_FLOWOY_SIGNATURE'] ?? '';

// 1) Tazelik — tekrar oynatmayı (replay) engeller
if (abs(time() - (int)$zaman) > 300) { http_response_code(400); exit; }

// 2) İmza — sabit zamanlı karşılaştırma
$beklenen = 'sha256=' . hash_hmac('sha256', $zaman . '.' . $govde, FLOWOY_SECRET);
if (!hash_equals($beklenen, $imza)) { http_response_code(401); exit; }

$olay = json_decode($govde, true);
// … olayId ile tekilleştirin, işinizi yapın
http_response_code(200);

Node.js

const crypto = require('crypto');

// DİKKAT: ham gövde gerekir — express.json() sonrası hesaplama tutmaz.
app.post('/flowoy/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const zaman = req.get('X-Flowoy-Timestamp') || '';
  const imza  = req.get('X-Flowoy-Signature') || '';
  if (Math.abs(Date.now() / 1000 - Number(zaman)) > 300) return res.sendStatus(400);

  const beklenen = 'sha256=' + crypto
    .createHmac('sha256', process.env.FLOWOY_SECRET)
    .update(`${zaman}.${req.body}`)
    .digest('hex');

  const a = Buffer.from(beklenen), b = Buffer.from(imza);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const olay = JSON.parse(req.body);
  res.sendStatus(200); // önce 200 dön, işi arka planda yap
});

Teslim günlüğü

{ "ok": true, "count": 2, "data": [
  { "event": "message.delivered", "statusCode": 200, "ok": true,
    "attempt": 1, "durationMs": 184, "at": "2026-10-31T09:14:22Z" },
  { "event": "message.failed", "statusCode": 502, "ok": false,
    "error": "HTTP 502", "attempt": 3, "durationMs": 10004, "at": "2026-10-31T08:02:10Z" }
] }

Gönderim kapıları

API panelin kısa yolu değil. Her gönderim, panelden yapılan gönderimle aynı kapılardan sırayla geçer; hangisine takıldığınızı yanıttaki kod söyler.

1. 1
   Anahtar401 unauthorized

   Hesap bağlamı yalnız anahtardan gelir. Anahtarsız hiçbir uç iş yapmaz.

2. 2
   Plan403 plan_required

   API erişimi plandan kaldırılırsa daha önce üretilmiş anahtarlar da çalışmayı bırakır.

3. 3
   Hız sınırı429 rate_limited

   Dakikada 120 istek. Retry-After kadar bekleyin.

4. 4
   Şablon onayı400 template

   Yalnız Meta'da onaylı şablon gönderilir. Taslak ya da reddedilmiş şablon listede bile görünmez.

5. 5
   Değişken denetimi400 variables

   Eksik ya da fazla anahtar burada yakalanır. Bu denetim izin kapısından önce çalışır ki hatalı bir istek müşterinin sıklık sayacını tüketmesin.

6. 6
   İzin kapısı403 not_sendable

   Pazarlama izni, opt-out, kara liste ve sıklık sınırı — dördü de veritabanı sorgusunda uygulanır. UTILITY ve AUTHENTICATION şablonları hizmet mesajı sayılır; izin ve sıklık sınırı onlara uygulanmaz.

7. 7
   Kuyruk202 queued

   Buraya gelen mesaj kuyruğa girer; numaranızın saatlik ve günlük kotası burada uygulanır. Sonuç webhook ile size döner.

Teslim hataları

failed olayındaki errorCode Meta'nın kodunu taşır. Hangisi kalıcı, hangisi beklemeli:

Henüz olmayanlar

Yol haritasında olup bugün bulunmayanlar. Entegrasyonunuzu bunlara dayandırmayın.

• Gelen mesaj geçmişi. message.received olayı anlık gelir, ama geçmiş yazışmalar API'den okunamaz; panelden görülür.
• Şablon oluşturma. Şablonlar panelden yaratılıp Meta onayına gönderilir.
• Kampanya tetikleme. Kampanyalar panelden başlatılır; API'den tek tek ya da 25'lik partiler hâlinde gönderim yapılır.
• Test (sandbox) ortamı. Ayrı bir test hesabı yoktur; denemelerinizi kendi numaranızla yapın.
• Yetki kapsamları. Anahtar hesabın tüm API uçlarına erişir; uç bazlı kısıtlama yoktur.