> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API girişi

> Flowella REST API v1 için kimlik doğrulama, temel URL, hata kodları, sayfalandırma, hız sınırları ve idempotency anahtarları — ilk çağrınızdan önce ihtiyaç duyduğunuz her şey.

Flowella REST API'si, WhatsApp mesajları göndermenize, kişileri ve çıkışları yönetmenize, şablonları listeleyip toplu göndermenize ve analizleri programatik olarak çekmenize olanak tanır. Bu sayfa, bir uç noktayı çağırmadan önce bilmeniz gereken her şeyi kapsar.

Tam uç nokta referansı **API referansı** kenar çubuğunda bulunur ([OpenAPI spesifikasyonundan](/api-reference/openapi.json) otomatik olarak oluşturulur).

## Temel URL

```
https://api.flowella.io/v1
```

Tüm v1 uç noktaları bu kanonik tabanın altında yer alır — örneğin `https://api.flowella.io/v1/messages`.

<Note>
  API, önceden uygulama ana bilgisayarında `https://app.flowella.io/api/v1/...` adresinde bulunuyordu. Bu yola yönelik eski istekler, yöntem ve gövdeyi koruyarak kanonik `https://api.flowella.io/v1/...` adresine kalıcı olarak yönlendirilir (`308`) — bu nedenle mevcut entegrasyonlar çalışmaya devam eder. Ekstra sıçramayı atlamak için fırsat bulduğunuzda temel URL'nizi güncelleyin.
</Note>

## Kimlik doğrulama

Her istek `Authorization` başlığında bir API anahtarına ihtiyaç duyar:

```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```

Anahtarlar kuruluş kapsamlıdır — tek bir Flowella kuruluşunda çalışır ve o kuruluştaki bir Yöneticinin izinlerini devralır.

<Warning>
  Anahtarları parola gibi kabul edin. Bunları kaynak kontrolüne asla göndermeyin, sohbette veya paylaşılan belgelerde asla yapıştırmayın ve ekip arkadaşları kuruluştan ayrıldığında döndürün. Döndürme adımları için [Ayarlar → API anahtarları](/tr/settings/api-keys) sayfasına bakın.
</Warning>

### Anahtar oluşturma

API anahtarlarını yönetmek için **Sahip** veya **Yönetici** rolüne sahip olmanız gerekir.

1. Flowella uygulamasında **Ayarlar → API anahtarları** bölümüne gidin.
2. **Anahtar oluştur** düğmesine tıklayın ve akılda kalıcı bir ad verin.
3. Anahtarı bir kez kopyalayın — yalnızca oluşturulma sırasında gösterilir.

Anahtarları parola gibi kabul edin: bunları kaynak kontrolüne asla göndermeyin, sohbette asla yapıştırmayın ve ekip arkadaşları kuruluştan ayrıldığında döndürün.

### Bir anahtarı doğrulama

Bir anahtarın geçerli olduğunu onaylamak için ping uç noktasına istek gönderin:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flowella.io/v1/ping \
    -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js Node.js theme={null}
  await fetch("https://api.flowella.io/v1/ping", {
    headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, requests

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

`{ "ok": true, "organizationId": "…" }` içeren bir `200 OK`, kimliğinizin doğrulandığı anlamına gelir.

## Hatalar

Tüm hatalar tutarlı bir zarf içinde döner:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| HTTP durumu | Ne zaman görürsünüz |
| - | - |
| `400` | Doğrulama başarısız, hatalı biçimlendirilmiş gövde veya yukarı akış Meta reddi |
| `401` | Eksik veya geçersiz API anahtarı |
| `402` | Ödeme gerekli — aboneliğiniz işlemi kapsamıyor |
| `403` | Yasak — örneğin, çıkış yapmış bir kişiye gönderim veya Meta bağlı değil |
| `404` | İstenen kanal veya kaynak yok |
| `429` | Hız sınırlı — yavaşlayın |

`error.code` alanı sabittir ve programatik olarak switch etmek için güvenlidir. `error.message` insan tarafından okunabilir ve değişebilir.

## Hız sınırları

API anahtarları kuruluş başına hız sınırlıdır. Limiti aşarsanız `RATE_LIMITED` koduyla ve `Too many requests` mesajıyla bir `429` alırsınız. Mevcut olduğunda `Retry-After` yanıt başlığı size kaç saniye beklemeniz gerektiğini bildirir. Geri çekilip üstel gecikmeyle yeniden deneyin.

Büyük toplu gönderimler yapıyorsanız, `throttlePerHour` parametresiyle **`POST /v1/templates/send`** kullanmayı tercih edin — Flowella kısıtlamayı sunucu tarafında uygular, bu nedenle istekleri kendiniz temposunu ayarlamanız gerekmez.

## Idempotency anahtarları

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

```json theme={null}
{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}
```

Flowella toplu işi arka planda teslim eder ve geçici WhatsApp hatalarını otomatik olarak yeniden dener. Alıcılar tek tek işlenir, bu nedenle bir geçersiz numara toplu işin geri kalanını engellemez. Teslimat ilerlemesini uygulamadaki şablonun **İstatistikler** sekmesinden takip edin.

Teslimat yanıttan sonra gerçekleştiği için, yeniden denemelerin güvenli olması gerekir. Her toplu işi benzersiz olarak tanımlayan bir `Idempotency-Key` başlığı (en fazla 200 karakter) geçirin:

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

Yedi gün içinde aynı anahtarın tekrarları, yeni bir gönderim oluşturmak yerine orijinal iş `id`'sini döndürür. Bir isteği zaman aşımı veya ağ hatasından sonra kimseye iki kez mesaj göndermeden güvenli bir şekilde yeniden deneyebilirsiniz.

Başlığı atlarsanız Flowella, istek gövdesinden bir anahtar türetir. Bu nedenle, kısa sürede iki kez gönderilen aynı bir toplu iş iki kez gönderilmez. Açık bir anahtar yine de daha güvenlidir, çünkü gövdedeki herhangi bir değişiklik (alıcıları yeniden sıralamak bile) yeni bir türetilmiş anahtar üretir.

## Sayfalandırma

Liste uç noktaları (`/conversations`, `/contacts`, `/templates`) **imleç sayfalandırması** kullanır:

* `limit` (1–100, varsayılan 25) ve isteğe bağlı bir `cursor` geçirin.
* Yanıt `items` içerir ve daha fazla sonuç olduğunda bir `nextCursor` içerir.
* Sonraki sayfayı almak için `nextCursor`'ı `cursor` parametresi olarak geri geçirin.
* `nextCursor` yoksa, sona ulaştınız.

```bash theme={null}
curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Tarih ve saat

Tüm zaman damgaları UTC'de ISO 8601 dizeleridir (örneğin `2025-01-15T14:30:00.000Z`). API'nin tarihleri kabul ettiği yerlerde, hem yalnızca tarih (`2025-01-15`) hem de tam ISO 8601 sunucu tarafında zorlanır.

## Telefon numaraları

Telefon numaralarını mümkün olduğunda **E.164** biçiminde (`+15551234567`) geçirin. Flowella yaygın varyasyonları sunucu tarafında normalleştirecektir, ancak E.164 en güvenlisidir.

## 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ış göndericiden göndermeyi önlemek için kimliği açıkça geçirin.

Tam URL kalıbı ve kanal değiştirme için [Çoklu kanal](/tr/essentials/multi-channel) sayfasına bakın.

## OpenAPI spesifikasyonu

Makine tarafından okunabilir spesifikasyon şu adreste bulunur:

```
/api-reference/openapi.json
```

Postman, Insomnia veya tercih ettiğiniz kod üretecinize bırakın.

<Tip>
  Bir entegrasyon mu geliştiriyorsunuz? Durumu yoklamak yerine olaylara tepki vermek için bu sayfayı [Webhooks](/tr/api-reference/webhooks) ile eşleştirin.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.