Flowella REST API: kimlik doğrulama, kapsamlar, limitler ve hatalar

Flowella REST API, kendi kodunuzdan WhatsApp mesajları göndermenizi, kişileri ve abonelikten çıkma kayıtlarını yönetmenizi, şablonlar ve Flows ile çalışmanızı ve analizleri okumanızı sağlar. Bu sayfa, bir uç noktayı çağırmadan önce bilmeniz gerekenleri kapsar. Bu API referansının Endpoints bölümü tek tek istekleri belgeler. Eksiksiz ve güncel liste için canlı OpenAPI belgesini veya uygulamadaki etkileşimli API belgelerini kullanın.

Temel URL

https://api.flowella.io/v1

Her uç nokta bu temel adresin altında yer alır, örneğin https://api.flowella.io/v1/messages. Uygulama, Geliştirici merkezi içindeki API base URL gibi /api/v1 ile biten bir adres gösterse bile bunu kullanın.

Uygulama sunucusuna, https://app.flowella.io/api/v1/... adresine yapılan istekler kalıcı olarak (308) https://api.flowella.io/v1/... adresine yönlendirilir. Birçok HTTP istemcisi, başka bir sunucuya yönlendirmeyi izlerken Authorization başlığını düşürür; bu nedenle yönlendirilen istek 401 ile başarısız olabilir. https://api.flowella.io/v1 adresini doğrudan çağırın.

Kimlik doğrulama

Her isteğin Authorization başlığında bir bearer token gönderin:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Flowella iki tür token kabul eder. İkisi de yalnızca tek bir kuruluş üzerinde işlem yapar.

Token	Başlangıcı	Nereden gelir	Kapsamlar	Geçerlilik süresi
API anahtarı	`flo_`	Bir Owner veya Admin tarafından Settings → API keys bölümünde oluşturulur. API anahtarları sayfasına bakın.	Tüm kapsamlar	Yok. İptal edilene kadar çalışır.
OAuth erişim token’ı	`fla_`	Settings → Developer apps altında kaydedilmiş bir OAuth uygulaması. OAuth ile bir iş ortağı uygulaması kaydetme sayfasına bakın.	Yalnızca uygulama yetkilendirildiğinde verilen kapsamlar	1 saat. Süresi dolduğunda yeni bir token isteyin.

Kendi betikleriniz ve entegrasyonlarınız için bir API anahtarı kullanın. Entegrasyonunuzu diğer Flowella kuruluşları yüklediğinde bir OAuth uygulaması kullanın.

Anahtarlara ve token’lara parola gibi davranın. Bunları asla kaynak kontrolüne göndermeyin veya sohbetlere ya da paylaşılan belgelere yapıştırmayın. Artık ihtiyacınız olmayan bir anahtarı API anahtarları sayfasından iptal edin.

Kimlik bilgilerinizi kontrol edin

Bir anahtarın veya token’ın çalıştığını doğrulamak için ping uç noktasını çağırın:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

const res = await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
print(res.json())

200 OK yanıtı, kimliğinizin doğrulandığı anlamına gelir. organizationId, kuruluşunuzun sayısal kimliğidir:

{
  "ok": true,
  "organizationId": 4821
}

401 yanıtı UNAUTHORIZED koduna ve şu mesajlardan birine sahiptir: Missing bearer token, Invalid or expired API key, Invalid or expired access token veya Unsupported bearer token.

Kapsamlar

Her uç nokta bir kapsam gerektirir. Uygulamada oluşturulan API anahtarları tüm kapsamlara sahiptir. OAuth erişim token’ları yalnızca yetkilendirme sırasında verilen kapsamlara sahiptir.

Kapsam	İzin verdiği
`messages:read`	Mesajları okuma.
`messages:write`	`POST /v1/messages` ile mesaj gönderme.
`contacts:read`	Kişileri ve abonelikten çıkma kayıtlarını okuma.
`contacts:write`	Kişi oluşturma, güncelleme ve silme, toplu upsert işlemleri ve abonelikten çıkma kaydetme.
`conversations:read`	Konuşmaları ve WhatsApp kanallarını okuma.
`conversations:write`	Konuşmaları güncelleme, kapatma ve yeniden açma.
`templates:read`	Şablonları ve onay durumlarını okuma.
`templates:write`	Şablon oluşturma, düzenleme, gönderme ve silme, test gönderimleri ve `POST /v1/templates/send` ile toplu gönderimler.
`webhooks:manage`	Webhook’ları, teslimatları, yeniden oynatmaları ve imzalama gizli anahtarlarını yönetme.
`analytics:read`	Analizleri ve kullanımı okuma.
`account:read`	Yetenekleri, entegrasyon durumunu ve istek ayrıntılarını okuma.
`flows:read`	Flows’ları ve senkronizasyon durumlarını okuma.
`flows:write`	Flows oluşturma, düzenleme, yayımlama ve silme ve form sağlayıcılarını ayarlama.
`forms:ingest`	Gelen form webhook’ları dahil form gönderimlerini gönderme ve okuma.
`events:read`	`GET /v1/events` ile olay akışını okuma.
`jobs:read`	Arka plan işlerini ve sonuçlarını okuma.
`jobs:write`	Arka plan işlerini iptal etme.
`sandbox:manage`	Sandbox ayarını okuma ve değiştirme ve sandbox test araçlarını kullanma.

GET /v1/ping ve GET /v1/rate-limits kapsam gerektirmez. GET /v1/capabilities (kapsam account:read), token’ınızın sahip olduğu kapsamları listeler. Gereken kapsama sahip olmayan bir istek, INSUFFICIENT_SCOPE koduyla 403 döndürür. details.required, eksik kapsamları listeler:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

Hatalar

Hatalar aynı zarfı kullanır. requestId, destekle iletişime geçtiğinizde isteği tanımlar; details ise varsa doğrulama sorunları gibi ek bilgileri içerir:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

HTTP durumu	`error.code`	Ne zaman görürsünüz
`400`	`BAD_REQUEST`	İstek doğrulamadan geçemedi, `API-Version` desteklenmiyor veya `Idempotency-Key` yanlış uzunlukta.
`400`	`META_ERROR`	Meta isteği reddetti.
`400`	`INVALID_TEMPLATE_NAME`, `INVALID_TEMPLATE_COMPONENTS`	Şablon adı veya bileşenleri geçerli değil.
`401`	`UNAUTHORIZED`	Bearer token eksik, geçersiz, iptal edilmiş veya süresi dolmuş.
`402`	`PAYMENT_REQUIRED`	Abonelik ödemenizin vadesi geçmiş.
`403`	`INSUFFICIENT_SCOPE`	Token’ınız, uç noktanın ihtiyaç duyduğu bir kapsama sahip değil.
`403`	`FORBIDDEN`	İşleme izin verilmiyor; örneğin o numarada abonelikten çıkmış bir kişiye gönderim yapmak veya aboneliğinizin etkin olmaması.
`404`	`NOT_FOUND`	Kaynak kuruluşunuzda mevcut değil.
`409`	`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_KEY_IN_FLIGHT`	`externalId` gibi yinelenen bir değer veya bir eşgüçlülük anahtarı çakışması.
`429`	`RATE_LIMITED`	Çok fazla istek gönderdiniz. Hız sınırları bölümüne bakın.
`500`	`INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR`	Flowella tarafında bir sorun oluştu. Daha sonra yeniden deneyin ve desteğe `requestId` değerini iletin.

error.code değeri kararlıdır, bu nedenle kodunuz ona güvenebilir. error.message metni insanlar içindir ve değişebilir.

Hız sınırları

Her API anahtarının ve her OAuth erişim token’ının dakika başına istekler için kendi sınırı vardır. Flowella, istekleri dakika başında (UTC) başlayan sabit bir dakikalık pencerelerde sayar. Kimlik doğrulama ve kapsam kontrollerinden geçen isteklerin yanıtları şu başlıkları içerir:

Başlık	Anlamı
`X-RateLimit-Limit`	Her pencerede izin verilen istek sayısı.
`X-RateLimit-Remaining`	Mevcut pencerede kalan istek sayısı.
`X-RateLimit-Reset`	Mevcut pencerenin sona erdiği zaman, Unix saniyesi olarak.

Sınırı aştığınızda Flowella, RATE_LIMITED koduyla 429 ve beklemeniz gereken saniye sayısını içeren bir Retry-After başlığı döndürür. GET /v1/rate-limits, limit, remaining ve reset değerlerinizi JSON olarak döndürür. Büyük gönderimler için tek bir istekte 50.000’e kadar alıcı kabul eden POST /v1/templates/send uç noktasını kullanın. İstek ayrıca 1 ile 100.000 arasında bir tam sayı olan isteğe bağlı bir throttlePerHour alanını kabul eder, ancak bu alan şu anda gönderimlerin hızını ayarlamaz; bu nedenle ona güvenmeyin. Büyük bir gönderimi zamana yaymak için alıcı listesini daha küçük gruplara bölün ve her grubu ayrı ayrı gönderin.

İstek kimlikleri

Yanıtlar bir X-Request-Id başlığı içerir ve hata gövdeleri bunu error.requestId olarak tekrarlar. POST /v1/templates/send bunun istisnasıdır: Toplu şablon gönderimleri bölümüne bakın. Kendi kimliğinizi kullanmak için en fazla 128 karakterlik bir X-Request-Id başlığı gönderin; Flowella onu yeniden kullanır. Destekle iletişime geçtiğinizde istek kimliğini iletin. Bir isteği kendiniz aramak için GET /v1/requests/{requestId} (kapsam account:read) çağrısını yapın: bu çağrı, kaydedilmiş isteği ona bağlı olaylar, işler ve webhook teslimatlarıyla birlikte döndürür. Geliştirici merkezi, son isteklerinizi ve kimliklerini listeler.

Eşgüçlülük

Eşgüçlülük (idempotency) anahtarları, bir zaman aşımı veya ağ hatasından sonra bir yazma isteğini, işi iki kez yapmadan yeniden denemenizi sağlar. POST /v1/templates/send aşağıda açıklanan kendi kurallarını izler.

Çoğu yazma isteği

POST, PATCH, PUT ve DELETE istekleri isteğe bağlı bir Idempotency-Key başlığını kabul eder:

Anahtar 8 ile 255 karakter arasında olmalıdır. Diğer uzunluklar 400 döndürür.
Flowella, her anahtarı kuruluşunuz için 24 saat boyunca hatırlar.
Aynı anahtar, yöntem, yol ve gövdeyle yapılan bir tekrar, isteği yeniden çalıştırmadan saklanan yanıtı döndürür.
Aynı anahtar ancak farklı bir yöntem, yol veya gövdeyle yapılan bir tekrar 409 IDEMPOTENCY_KEY_CONFLICT döndürür.
İlk istek hâlâ çalışırken gönderilen bir tekrar 409 IDEMPOTENCY_KEY_IN_FLIGHT döndürür. Bekleyip yeniden deneyin.
Yanıtlar, anahtarı bir Idempotency-Key başlığında geri yansıtır.

Başlık içermeyen istekler, yinelemelere karşı herhangi bir koruma olmadan normal şekilde çalışır.

Toplu şablon gönderimleri

Toplu şablon gönderimleri eşzamansızdır. POST /v1/templates/send, isteği doğrular, kalıcı olarak kuyruğa alır ve hemen 202 Accepted döndürür:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella grubu arka planda teslim eder ve geçici WhatsApp hatalarını otomatik olarak yeniden dener. Alıcılar ayrı ayrı işlenir, bu nedenle geçersiz bir numara grubun geri kalanını engellemez. Teslimat ilerlemesini uygulamada şablonun Statistics sekmesinden takip edin. Her grubu tanımlayan bir Idempotency-Key başlığı iletin:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Bu uç nokta anahtarları diğer yazma isteklerinden farklı şekilde işler:

Anahtar en fazla 200 karakter olabilir. Daha uzun bir anahtar 400 döndürür.
7 gün içinde aynı anahtarla yapılan bir tekrar, gövde değişmiş olsa bile özgün id değerini döndürür ve hiçbir şey göndermez.
Başlık olmadan Flowella, anahtar olarak istek gövdesinin bir karmasını kullanır. Bayt düzeyinde aynı bir gövdeyi 7 gün içinde yeniden gönderirseniz özgün id değerini geri alırsınız ve hiçbir şey gönderilmez. Göndermek istediğiniz her grup için yeni bir anahtar kullanın.

Bu uç nokta için bazı diğer davranışlar da farklıdır:

Bu uç noktayı bir API anahtarıyla çağırın. OAuth erişim token’ları 401 ile reddedilir.
Yanıtları X-Request-Id, API-Version veya X-RateLimit-* başlıklarını içermez. İstekleri yine de anahtarın hız sınırına dahil edilir.

Sürümleme

API sürümünü API-Version başlığıyla sabitleyebilirsiniz:

API-Version: 2026-08-11

2026-08-11 desteklenen tek sürümdür ve başlığı eklemediğinizde varsayılan değerdir. Başka herhangi bir değer veya YYYY-MM-DD biçiminde tarih olmayan bir değer, Unsupported API-Version mesajıyla 400 döndürür. Yanıtlar sürümü API-Version ve X-Flowella-Api-Version başlıklarında geri yansıtır.

Sandbox

Sandbox, WhatsApp’a hiçbir şey göndermeden bir entegrasyonu test etmenizi sağlar. Gerçek kuruluşunuz üzerinde çalışır: ayrı bir test hesabı yoktur. İki şekilde kullanabilirsiniz:

Yalnızca o anahtarla yapılan istekleri etkileyen bir sandbox anahtarı. Sandbox anahtarları bölümüne bakın.
Geliştirici merkezinde bir Owner veya Admin’in açabileceği, kuruluş genelindeki API sandbox. API sandbox bölümüne bakın.

Sandbox geçerliyken POST /v1/messages, Meta ile iletişime geçmeden mesajı saklar ve "sandbox": true döndürür; şablon gönderimi ise anında sahte bir karar döndürür. /v1/test/ ve /v1/sandbox altındaki sandbox test araçları sandbox:manage kapsamını gerektirir.

Sayfalandırma

/v1/conversations, /v1/contacts ve /v1/templates gibi liste uç noktaları imleç tabanlı sayfalandırma kullanır:

limit (1 ile 100 arası, varsayılan 25) ve isteğe bağlı bir cursor iletin.
Yanıt items ve daha fazla sonuç olduğunda bir nextCursor içerir.
Sonraki sayfayı almak için nextCursor değerini cursor parametresi olarak geri iletin.
nextCursor eksik veya null olduğunda sona ulaşmışsınızdır.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

Tarih ve saat

Tüm zaman damgaları UTC cinsinden ISO 8601 dizeleridir, örneğin 2025-01-15T14:30:00.000Z. API’nin tarih kabul ettiği yerlerde hem yalnızca tarih (2025-01-15) hem de tam ISO 8601 değerleri çalışır.

Telefon numaraları

Telefon numaralarını mümkün olduğunda E.164 biçiminde (+15551234567) iletin. Flowella yaygın varyasyonları normalleştirir, ancak en güvenli seçenek E.164’tür.

Kanallar

Birçok uç nokta bir whatsappChannelId kabul eder. Kuruluşunuzun tek bir kanalı varsa ve bunu atlarsanız Flowella varsayılan kanalınızı kullanır. Birden fazla kanalınız varsa yanlış numaradan gönderim yapmamak için kimliği açıkça iletin. Tam URL kalıbı ve kanal değiştirme için Çoklu kanal sayfasına bakın.

OpenAPI belirtimi

Canlı, makine tarafından okunabilir belirtim herkese açıktır:

https://api.flowella.io/v1/openapi.json

Bunu Postman’e, Insomnia’ya veya bir kod oluşturucuya aktarın. Hem API anahtarı hem de OAuth kimlik doğrulamasını açıklar.

Geliştirici kaynakları

Uygulamada daha fazla geliştirici materyali bulunur. Bu sayfalar herkese açıktır, bu nedenle oturum açmadan açabilirsiniz:

Kaynak	Adres
Deneme istekleriyle etkileşimli API belgeleri	`https://app.flowella.io/docs`
Postman koleksiyonu (bir `.json` dosyası indirir)	`https://app.flowella.io/docs/postman`
Sandbox kılavuzu	`https://app.flowella.io/docs/sandbox`
Salesforce, Zoho CRM, SurveyMonkey, Typeform ve n8n için Markdown biçiminde hızlı başlangıç kılavuzları	`https://app.flowella.io/docs/quickstarts/salesforce`; `salesforce` yerine `zoho`, `surveymonkey`, `typeform` veya `n8n` ile

Settings içindeki Geliştirici merkezi, bu bağlantıları son API isteklerinizle ve API sandbox anahtarıyla bir araya getirir.

Değişiklikleri yoklamak yerine olaylara tepki vermek için bu sayfayı webhook referansıyla birlikte kullanın.

Başlarken

Temel bilgiler

Uygulamayı kullanma

Ayarlar

Meta ve WhatsApp kurulumu

HubSpot entegrasyonu

Flow'lar ve kampanyalar

API referansı

Sorun giderme

Değişiklik günlüğü

Flowella REST API: kimlik doğrulama, kapsamlar, limitler ve hatalar

Temel URL

Kimlik doğrulama

Kimlik bilgilerinizi kontrol edin

Kapsamlar

Hatalar

Hız sınırları

İstek kimlikleri

Eşgüçlülük

Çoğu yazma isteği

Toplu şablon gönderimleri

Sürümleme

Sandbox

Sayfalandırma

Tarih ve saat

Telefon numaraları

Kanallar

OpenAPI belirtimi

Geliştirici kaynakları

​Temel URL

​Kimlik doğrulama

​Kimlik bilgilerinizi kontrol edin

​Kapsamlar

​Hatalar

​Hız sınırları

​İstek kimlikleri

​Eşgüçlülük

​Çoğu yazma isteği

​Toplu şablon gönderimleri

​Sürümleme

​Sandbox

​Sayfalandırma

​Tarih ve saat

​Telefon numaraları

​Kanallar

​OpenAPI belirtimi

​Geliştirici kaynakları

Temel URL

Kimlik doğrulama

Kimlik bilgilerinizi kontrol edin

Kapsamlar

Hatalar

Hız sınırları

İstek kimlikleri

Eşgüçlülük

Çoğu yazma isteği

Toplu şablon gönderimleri

Sürümleme

Sandbox

Sayfalandırma

Tarih ve saat

Telefon numaraları

Kanallar

OpenAPI belirtimi

Geliştirici kaynakları