{ "openapi": "3.1.0", "info": { "title": "ZenWapp External API", "version": "1.0.0", "summary": "ZenWapp hesabınızı kendi sistemlerinizle entegre etmek için REST API.", "description": "ZenWapp External API, mesaj gönderimi, sohbet ve kişi yönetimi, şablonlar, zamanlanmış mesajlar, toplu gönderim ve webhook yönetimi için kullanılır. Tüm çağrılar API anahtarı ile kimlik doğrulaması gerektirir.", "contact": { "name": "ZenWapp Destek", "email": "info@zenwapp.com", "url": "https://zenwapp.com" } }, "servers": [ { "url": "https://api.zenwapp.com/api/v1/whatsapp/external", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "System", "x-slug": "sistem", "x-icon": "Activity", "description": "Sağlık kontrolü ve bağlı hesap bilgisi. Entegrasyonunuzu doğrulamak için ilk çağıracağınız uçlar." }, { "name": "Chats", "x-slug": "sohbetler", "x-icon": "MessagesSquare", "description": "Sohbet listesi, telefon numarasından sohbet eşleştirme ve sohbet mesaj geçmişi." }, { "name": "Messages", "x-slug": "mesajlar", "x-icon": "Send", "description": "Metin mesajı gönderimi, kuyruk ve hız limiti durumu, içerik doğrulama." }, { "name": "Media", "x-slug": "medya", "x-icon": "Image", "description": "Görsel, doküman, ses, voice ve sticker gönderimi ile medya dosyalarına erişim." }, { "name": "Contacts", "x-slug": "kisiler", "x-icon": "Users", "description": "Kişi listeleme, detay, güncelleme, silme, WhatsApp numara kontrolü ve toplu senkron." }, { "name": "Groups & Tags", "x-slug": "gruplar-etiketler", "x-icon": "Tags", "description": "Grup ve etiket listeleme/oluşturma." }, { "name": "Templates", "x-slug": "sablonlar", "x-icon": "FileText", "description": "Değişken destekli mesaj şablonlarının yönetimi ve şablonla gönderim." }, { "name": "Scheduled", "x-slug": "zamanlanmis", "x-icon": "CalendarClock", "description": "İleri tarihli mesaj planlama, listeleme, güncelleme ve iptal." }, { "name": "Auto Replies", "x-slug": "otomatik-yanitlar", "x-icon": "Zap", "description": "Anahtar kelime, regex veya mesai saatine göre tetiklenen otomatik yanıt kuralları." }, { "name": "Broadcast", "x-slug": "toplu-gonderim", "x-icon": "Megaphone", "description": "Çok alıcılı kampanya gönderimi, ilerleme takibi ve iptal." }, { "name": "Webhooks", "x-slug": "webhooks", "x-icon": "Webhook", "description": "Gerçek zamanlı olay teslimatı için webhook URL yönetimi, test ve secret rotasyonu." } ], "paths": { "/health": { "get": { "tags": [ "System" ], "operationId": "getHealth", "summary": "Sağlık kontrolü", "description": "API anahtarınızın geçerliliğini ve bağlı hesabın durumunu doğrular. Entegrasyon kurulumunda ilk çağrılması önerilen uçtur.", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "API erişilebilir ve anahtar geçerli", "content": { "application/json": { "example": { "success": true, "status": "ok", "account": { "id": "b3d1e009-...", "name": "Satış Hattı", "status": "connected" }, "timestamp": "2026-07-30T09:12:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/account": { "get": { "tags": [ "System" ], "operationId": "getAccount", "summary": "Hesap bilgisi", "description": "API anahtarının bağlı olduğu kanal hesabının profil ve bağlantı bilgilerini döndürür.", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "Hesap bilgisi", "content": { "application/json": { "example": { "success": true, "data": { "id": "b3d1e009-...", "name": "Satış Hattı", "phone_number": "905551234567", "status": "connected", "provider": "evolution" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/chats": { "get": { "tags": [ "Chats" ], "operationId": "listChats", "summary": "Sohbetleri listele", "description": "Hesaba bağlı tüm sohbetleri döndürür.", "x-permission": "chats:read", "responses": { "200": { "description": "Sohbet listesi", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "905551234567@c.us", "name": "Ahmet Yılmaz", "type": "individual", "is_muted": false, "is_archived": false, "last_message_at": "2026-07-30T08:45:12.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/chats/resolve": { "get": { "tags": [ "Chats" ], "operationId": "resolveChat", "summary": "Telefondan sohbet bul", "description": "Serbest formatlı bir telefon numarasını normalize ederek ilgili sohbeti bulur. Numara biçimi farklılıklarını (boşluk, +, 0 öneki) kendisi çözer.", "x-permission": "chats:read", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Ülke kodlu telefon numarası. `+90 555 123 45 67`, `05551234567` ve `905551234567` aynı sonucu verir.", "schema": { "type": "string", "examples": [ "905551234567" ] } } ], "responses": { "200": { "description": "Eşleşen sohbet", "content": { "application/json": { "example": { "success": true, "data": { "id": "905551234567@c.us", "name": "Ahmet Yılmaz", "phone": "905551234567" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/chats/{chatId}/messages": { "get": { "tags": [ "Chats" ], "operationId": "listChatMessages", "summary": "Sohbet mesajlarını getir", "description": "Bir sohbetin mesaj geçmişini en yeniden eskiye doğru döndürür. Sayfalama `before` imleci ile yapılır.", "x-permission": "messages:read", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "Sohbet kimliği (örn. `905551234567@c.us`).", "schema": { "type": "string", "examples": [ "905551234567@c.us" ] } }, { "name": "limit", "in": "query", "description": "Döndürülecek mesaj sayısı.", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "before", "in": "query", "description": "Bu zaman damgasından önceki mesajları getirir (ISO 8601). Sayfalama imleci.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_raw", "in": "query", "description": "Ham sağlayıcı verisini yanıta ekler.", "schema": { "type": "boolean", "default": true } }, { "name": "include_presigned_url", "in": "query", "description": "Medya mesajları için süreli indirme bağlantısı üretir.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Mesaj listesi", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "3EB0A1B2C3", "from": "905551234567@c.us", "body": "Merhaba, fiyat listesi alabilir miyim?", "type": "chat", "timestamp": 1785400000, "from_me": false, "has_media": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/messages/send": { "post": { "tags": [ "Messages" ], "operationId": "sendMessage", "summary": "Metin mesajı gönder", "description": "Varsayılan olarak asenkron çalışır: mesaj kuyruğa alınır ve `202 Accepted` döner. Teslimat durumunu webhook üzerinden takip edin. `sync: true` ile yanıtı gönderim tamamlanana kadar bekletebilirsiniz — bu mod zaman aşımına (504) açıktır, toplu işlerde kullanmayın.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "message" ], "properties": { "to": { "type": "string", "description": "Alıcı telefon numarası (ülke kodlu) veya sohbet kimliği.", "examples": [ "905551234567" ] }, "message": { "type": "string", "description": "Mesaj metni." }, "type": { "type": "string", "default": "text", "enum": [ "text" ] }, "priority": { "type": "integer", "default": 3, "description": "Kuyruk önceliği. Küçük değer daha önce gönderilir (1 = en yüksek)." }, "sync": { "type": "boolean", "default": false, "description": "true ise gönderim tamamlanana kadar bekler ve 200 döner." } } }, "example": { "to": "905551234567", "message": "Merhaba, siparişiniz kargoya verildi." } } } }, "responses": { "202": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "example": { "success": true, "queued": true, "job_id": "wa:send:8f21c0", "to": "905551234567@c.us" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "504": { "description": "`sync: true` modunda gönderim zaman aşımına uğradı. Mesaj yine de teslim edilmiş olabilir — webhook ile doğrulayın.", "content": { "application/json": { "example": { "error": "send_timeout", "message": "Message send timed out" } } } } } } }, "/messages/rate-limit": { "get": { "tags": [ "Messages" ], "operationId": "getRateLimit", "summary": "Hız limiti durumu", "description": "Hesabın anlık gönderim limiti ve kalan kotasını döndürür.", "x-permission": "messages:read", "responses": { "200": { "description": "Limit durumu", "content": { "application/json": { "example": { "success": true, "data": { "limit": 30, "remaining": 24, "window": "1m", "reset_at": "2026-07-30T09:13:00.000Z" } } } } } } } }, "/messages/queue": { "get": { "tags": [ "Messages" ], "operationId": "getQueueStatus", "summary": "Kuyruk durumu", "description": "Bekleyen, işlenen ve başarısız iş sayılarını döndürür. Toplu gönderim sırasında ilerlemeyi izlemek için kullanın.", "x-permission": "messages:read", "responses": { "200": { "description": "Kuyruk durumu", "content": { "application/json": { "example": { "success": true, "data": { "waiting": 12, "active": 1, "failed": 0, "delayed": 3 } } } } } } } }, "/messages/validate": { "post": { "tags": [ "Messages" ], "operationId": "validateMessage", "summary": "Mesaj içeriğini doğrula", "description": "Mesajı göndermeden önce içerik politikası ve uzunluk kontrolünden geçirir. Toplu gönderim öncesi ön kontrol için kullanışlıdır.", "x-permission": "messages:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "example": { "message": "Kampanya metni burada" } } } }, "responses": { "200": { "description": "Doğrulama sonucu", "content": { "application/json": { "example": { "success": true, "valid": true, "warnings": [] } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/send-media": { "post": { "tags": [ "Media" ], "operationId": "sendMedia", "summary": "Medya gönder", "description": "Görsel, video, ses veya doküman gönderir. Medyayı üç yoldan biriyle verebilirsiniz: `media_url` (uzak dosya), `media_data` (base64) veya `multipart/form-data` içinde `file` alanı. `as_document`, `as_voice`, `as_sticker` bayrakları gönderim biçimini belirler.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "examples": [ "905551234567" ] }, "media_url": { "type": "string", "description": "Herkese açık dosya URL'i." }, "media_data": { "type": "string", "description": "Base64 kodlanmış dosya içeriği." }, "mimetype": { "type": "string", "description": "`media_data` kullanıldığında zorunlu.", "examples": [ "image/jpeg" ] }, "filename": { "type": "string", "description": "Alıcıya görünecek dosya adı." }, "caption": { "type": "string", "description": "Medya açıklaması." }, "as_document": { "type": "boolean", "description": "Dosya olarak gönderir (önizleme yok)." }, "as_voice": { "type": "boolean", "description": "Sesli mesaj (PTT) olarak gönderir." }, "as_sticker": { "type": "boolean", "description": "Sticker olarak gönderir." } } }, "example": { "to": "905551234567", "media_url": "https://cdn.example.com/katalog.pdf", "filename": "katalog.pdf", "caption": "2026 ürün kataloğu" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "to", "file" ], "properties": { "to": { "type": "string" }, "file": { "type": "string", "format": "binary" }, "caption": { "type": "string" } } } } } }, "responses": { "202": { "description": "Medya kuyruğa alındı", "content": { "application/json": { "example": { "success": true, "queued": true, "job_id": "wa:media:41ab" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "504": { "description": "Gönderim zaman aşımı" } } } }, "/messages/send-image": { "post": { "tags": [ "Media" ], "operationId": "sendImage", "summary": "Görsel gönder", "description": "`/messages/send-media` ile aynı gövdeyi alır; `media_type` otomatik olarak `image` atanır.", "x-permission": "messages:send", "requestBody": { "$ref": "#/components/requestBodies/MediaShorthand" }, "responses": { "202": { "description": "Görsel kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/send-document": { "post": { "tags": [ "Media" ], "operationId": "sendDocument", "summary": "Doküman gönder", "description": "Dosyayı önizlemesiz doküman olarak gönderir (`as_document: true` kısayolu).", "x-permission": "messages:send", "requestBody": { "$ref": "#/components/requestBodies/MediaShorthand" }, "responses": { "202": { "description": "Doküman kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/send-audio": { "post": { "tags": [ "Media" ], "operationId": "sendAudio", "summary": "Ses dosyası gönder", "description": "Ses dosyasını müzik/ses eki olarak gönderir.", "x-permission": "messages:send", "requestBody": { "$ref": "#/components/requestBodies/MediaShorthand" }, "responses": { "202": { "description": "Ses kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/send-voice": { "post": { "tags": [ "Media" ], "operationId": "sendVoice", "summary": "Sesli mesaj (PTT) gönder", "description": "Ses dosyasını WhatsApp sesli mesajı olarak gönderir (`as_voice: true` kısayolu). Kaynak dosya OGG/Opus değilse dönüştürülür.", "x-permission": "messages:send", "requestBody": { "$ref": "#/components/requestBodies/MediaShorthand" }, "responses": { "202": { "description": "Sesli mesaj kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/send-sticker": { "post": { "tags": [ "Media" ], "operationId": "sendSticker", "summary": "Sticker gönder", "description": "Görseli sticker olarak gönderir (`as_sticker: true` kısayolu).", "x-permission": "messages:send", "requestBody": { "$ref": "#/components/requestBodies/MediaShorthand" }, "responses": { "202": { "description": "Sticker kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/media/{filename}": { "get": { "tags": [ "Media" ], "operationId": "getMediaFile", "summary": "Medya dosyasına eriş", "description": "Depolanan medya dosyasını döndürür. Varsayılan olarak tarayıcıda görüntülenir; `download=true` ile indirme başlığıyla servis edilir.", "x-permission": "messages:read", "parameters": [ { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "description": "`true` ise `Content-Disposition: attachment` ile döner.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Dosya içeriği (binary)" }, "400": { "description": "Geçersiz dosya adı" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/messages/{messageId}/media": { "get": { "tags": [ "Media" ], "operationId": "getMessageMedia", "summary": "Mesajın medyasına eriş", "description": "Bir mesaja ekli medyayı döndürür. `format=json` ile dosya yerine meta veri ve indirme bağlantısı alırsınız.", "x-permission": "messages:read", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "`json` ise dosya yerine meta veri döner.", "schema": { "type": "string", "enum": [ "json" ] } }, { "name": "download", "in": "query", "schema": { "type": "boolean" } }, { "name": "inline", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Dosya içeriği veya meta veri" }, "404": { "description": "Mesaj bulunamadı ya da mesajda medya yok", "content": { "application/json": { "example": { "error": "no_media", "message": "Message has no media" } } } } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "Kişileri listele", "description": "Sayfalanmış kişi listesi döndürür. Arama, etiket ve WhatsApp kullanıcı durumuna göre filtrelenebilir.", "x-permission": "chats:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "search", "in": "query", "description": "İsim veya telefonda arama.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Virgülle ayrılmış etiket adları.", "schema": { "type": "string" } }, { "name": "is_whatsapp_user", "in": "query", "schema": { "type": "boolean" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "last_message_at" } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Kişi listesi", "content": { "application/json": { "example": { "success": true, "data": [ { "phone": "905551234567", "name": "Ahmet Yılmaz", "tags": [ "bayi" ], "is_whatsapp_user": true } ], "pagination": { "page": 1, "limit": 50, "total": 128 } } } } } } } }, "/contacts/{phone}": { "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Kişi detayı", "description": "Telefon numarasına göre kişi kaydını döndürür.", "x-permission": "chats:read", "parameters": [ { "$ref": "#/components/parameters/PhonePath" } ], "responses": { "200": { "description": "Kişi detayı" }, "404": { "description": "Kişi bulunamadı", "content": { "application/json": { "example": { "error": "contact_not_found" } } } } } }, "put": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Kişiyi güncelle", "description": "Kişinin adı, etiketleri, notu, özel alanları ve engel durumu güncellenir. Yalnızca gönderilen alanlar değişir.", "x-permission": "chats:read", "parameters": [ { "$ref": "#/components/parameters/PhonePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": true }, "is_blocked": { "type": "boolean" } } }, "example": { "name": "Ahmet Yılmaz", "tags": [ "bayi", "istanbul" ] } } } }, "responses": { "200": { "description": "Güncellendi" }, "404": { "description": "Kişi bulunamadı" } } }, "delete": { "tags": [ "Contacts" ], "operationId": "deleteContact", "summary": "Kişiyi sil", "description": "Kişi kaydını siler. Sohbet geçmişi silinmez.", "x-permission": "chats:read", "parameters": [ { "$ref": "#/components/parameters/PhonePath" } ], "responses": { "200": { "description": "Silindi" }, "404": { "description": "Kişi bulunamadı" } } } }, "/contacts/{phone}/check": { "get": { "tags": [ "Contacts" ], "operationId": "checkWhatsAppNumber", "summary": "Numara WhatsApp'ta mı?", "description": "Numaranın WhatsApp'ta kayıtlı olup olmadığını canlı olarak sorgular. Hesabın bağlı (connected) olması gerekir.", "x-permission": "chats:read", "parameters": [ { "$ref": "#/components/parameters/PhonePath" } ], "responses": { "200": { "description": "Kontrol sonucu", "content": { "application/json": { "example": { "success": true, "phone": "905551234567", "is_whatsapp_user": true } } } }, "400": { "description": "Hesap bağlı değil", "content": { "application/json": { "example": { "error": "account_not_connected" } } } } } } }, "/contacts/sync": { "post": { "tags": [ "Contacts" ], "operationId": "syncContacts", "summary": "Toplu kişi senkronu", "description": "Numara listesini toplu olarak kontrol eder ve kişi kayıtlarını oluşturur/günceller. Tek çağrıda gönderilebilecek numara sayısı sınırlıdır; aşımda `too_many_phones` döner.", "x-permission": "chats:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phones" ], "properties": { "phones": { "type": "array", "items": { "type": "string" } }, "update_existing": { "type": "boolean", "default": true } } }, "example": { "phones": [ "905551234567", "905339876543" ], "update_existing": true } } } }, "responses": { "200": { "description": "Senkron sonucu" }, "400": { "description": "Geçersiz istek veya numara limiti aşıldı" } } } }, "/groups": { "get": { "tags": [ "Groups & Tags" ], "operationId": "listGroups", "summary": "Grupları listele", "x-permission": "chats:read", "responses": { "200": { "description": "Grup listesi" } } }, "post": { "tags": [ "Groups & Tags" ], "operationId": "createGroup", "summary": "Grup oluştur", "x-permission": "chats:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "type": "string", "examples": [ "#25D366" ] }, "description": { "type": "string" }, "icon": { "type": "string" } } }, "example": { "name": "Bayiler", "color": "#25D366" } } } }, "responses": { "201": { "description": "Grup oluşturuldu" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/tags": { "get": { "tags": [ "Groups & Tags" ], "operationId": "listTags", "summary": "Etiketleri listele", "x-permission": "chats:read", "responses": { "200": { "description": "Etiket listesi" } } }, "post": { "tags": [ "Groups & Tags" ], "operationId": "createTag", "summary": "Etiket oluştur", "x-permission": "chats:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "type": "string" } } }, "example": { "name": "sicak-lead", "color": "#F59E0B" } } } }, "responses": { "201": { "description": "Etiket oluşturuldu" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "operationId": "listTemplates", "summary": "Şablonları listele", "x-permission": "messages:read", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Şablon listesi" } } }, "post": { "tags": [ "Templates" ], "operationId": "createTemplate", "summary": "Şablon oluştur", "description": "Şablon içeriğinde `{{degisken}}` biçiminde yer tutucular kullanılır; gönderim sırasında `variables` ile doldurulur.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string", "default": "general" }, "language": { "type": "string", "default": "tr" }, "variables": { "type": "array", "items": { "type": "string" } } } }, "example": { "name": "kargo_bildirimi", "content": "Merhaba {{ad}}, {{siparis_no}} numaralı siparişiniz kargoya verildi.", "variables": [ "ad", "siparis_no" ] } } } }, "responses": { "201": { "description": "Şablon oluşturuldu" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "operationId": "getTemplate", "summary": "Şablon detayı", "x-permission": "messages:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Şablon detayı" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Templates" ], "operationId": "updateTemplate", "summary": "Şablonu güncelle", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string" }, "language": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "Güncellendi" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Templates" ], "operationId": "deleteTemplate", "summary": "Şablonu sil", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Silindi" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/messages/send-template": { "post": { "tags": [ "Templates" ], "operationId": "sendTemplateMessage", "summary": "Şablonla mesaj gönder", "description": "Şablonu `template_id` veya `template_name` ile seçer, `variables` içindeki değerlerle doldurup gönderir.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "template_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "description": "`template_id` yerine kullanılabilir." }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "to": "905551234567", "template_name": "kargo_bildirimi", "variables": { "ad": "Ahmet", "siparis_no": "SP-10245" } } } } }, "responses": { "202": { "description": "Kuyruğa alındı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/scheduled": { "get": { "tags": [ "Scheduled" ], "operationId": "listScheduledMessages", "summary": "Zamanlanmış mesajları listele", "x-permission": "messages:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed", "cancelled" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Zamanlanmış mesaj listesi" } } } }, "/messages/schedule": { "post": { "tags": [ "Scheduled" ], "operationId": "scheduleMessage", "summary": "Zamanlanmış mesaj oluştur", "description": "`scheduled_at` ISO 8601 biçiminde olmalıdır. Geçersiz tarihte `invalid_date` döner. Başarısız gönderimler `max_retries` kadar yeniden denenir.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "scheduled_at" ], "properties": { "to": { "type": "string" }, "message": { "type": "string" }, "message_type": { "type": "string", "default": "text" }, "media_url": { "type": "string" }, "media_caption": { "type": "string" }, "template_id": { "type": "string", "format": "uuid" }, "template_variables": { "type": "object", "additionalProperties": true }, "scheduled_at": { "type": "string", "format": "date-time" }, "max_retries": { "type": "integer", "default": 3 } } }, "example": { "to": "905551234567", "message": "Randevunuz yarın saat 14:00'te.", "scheduled_at": "2026-08-01T11:00:00.000Z" } } } }, "responses": { "201": { "description": "Zamanlandı" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/scheduled/{id}": { "get": { "tags": [ "Scheduled" ], "operationId": "getScheduledMessage", "summary": "Zamanlanmış mesaj detayı", "x-permission": "messages:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Detay" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Scheduled" ], "operationId": "updateScheduledMessage", "summary": "Zamanlanmış mesajı güncelle", "description": "Yalnızca henüz gönderilmemiş (`pending`) kayıtlar güncellenebilir.", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "max_retries": { "type": "integer" } } }, "example": { "scheduled_at": "2026-08-02T09:00:00.000Z" } } } }, "responses": { "200": { "description": "Güncellendi" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Scheduled" ], "operationId": "cancelScheduledMessage", "summary": "Zamanlanmış mesajı iptal et", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "İptal edildi" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/auto-replies": { "get": { "tags": [ "Auto Replies" ], "operationId": "listAutoReplies", "summary": "Otomatik yanıtları listele", "x-permission": "messages:read", "parameters": [ { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "trigger_type", "in": "query", "schema": { "type": "string", "enum": [ "keyword", "regex", "all", "first_message", "business_hours" ] } } ], "responses": { "200": { "description": "Kural listesi" } } }, "post": { "tags": [ "Auto Replies" ], "operationId": "createAutoReply", "summary": "Otomatik yanıt oluştur", "description": "Birden fazla kural eşleşirse `priority` değeri büyük olan kazanır. `delay_seconds` ile insan benzeri gecikme verebilirsiniz.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "trigger_type": { "type": "string", "default": "keyword", "enum": [ "keyword", "regex", "all", "first_message", "business_hours" ] }, "trigger_value": { "type": "string", "description": "Anahtar kelime veya regex deseni." }, "response_type": { "type": "string", "default": "text" }, "response_content": { "type": "string" }, "template_id": { "type": "string", "format": "uuid" }, "media_url": { "type": "string" }, "delay_seconds": { "type": "integer", "default": 0 }, "priority": { "type": "integer", "default": 0 }, "conditions": { "type": "object", "additionalProperties": true }, "is_active": { "type": "boolean", "default": true } } }, "example": { "name": "Fiyat sorusu", "trigger_type": "keyword", "trigger_value": "fiyat", "response_content": "Fiyat listemizi hemen paylaşıyorum.", "delay_seconds": 3 } } } }, "responses": { "201": { "description": "Oluşturuldu" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/auto-replies/{id}": { "get": { "tags": [ "Auto Replies" ], "operationId": "getAutoReply", "summary": "Otomatik yanıt detayı", "x-permission": "messages:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Detay" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Auto Replies" ], "operationId": "updateAutoReply", "summary": "Otomatik yanıtı güncelle", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "Güncellendi" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Auto Replies" ], "operationId": "deleteAutoReply", "summary": "Otomatik yanıtı sil", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Silindi" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/broadcasts": { "get": { "tags": [ "Broadcast" ], "operationId": "listBroadcasts", "summary": "Toplu gönderimleri listele", "x-permission": "messages:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Kampanya listesi" } } } }, "/messages/broadcast": { "post": { "tags": [ "Broadcast" ], "operationId": "createBroadcast", "summary": "Toplu mesaj gönder", "description": "Alıcıları `phones` dizisiyle ya da `recipient_filter` ile (etiket, arama vb.) belirtin — en az biri zorunludur. `delay_between_messages` gönderimler arası bekleme süresidir; hesabın engellenmemesi için düşük değer vermeyin.", "x-permission": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Kampanya adı." }, "message": { "type": "string" }, "message_type": { "type": "string", "default": "text" }, "media_url": { "type": "string" }, "media_caption": { "type": "string" }, "template_id": { "type": "string", "format": "uuid" }, "template_variables": { "type": "object", "additionalProperties": true }, "phones": { "type": "array", "items": { "type": "string" } }, "recipient_filter": { "type": "object", "additionalProperties": true }, "scheduled_at": { "type": "string", "format": "date-time" }, "delay_between_messages": { "type": "integer", "default": 2000, "description": "Milisaniye." } } }, "example": { "name": "Ağustos kampanyası", "message": "Ağustos'a özel %20 indirim!", "phones": [ "905551234567", "905339876543" ], "delay_between_messages": 4000 } } } }, "responses": { "201": { "description": "Kampanya oluşturuldu" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/broadcasts/{id}": { "get": { "tags": [ "Broadcast" ], "operationId": "getBroadcast", "summary": "Kampanya detayı", "description": "Kampanyanın ilerleme sayaçlarını (gönderilen, başarısız, bekleyen) içerir.", "x-permission": "messages:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Detay" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Broadcast" ], "operationId": "cancelBroadcast", "summary": "Kampanyayı iptal et", "description": "Henüz gönderilmemiş alıcılar iptal edilir; gönderilmiş mesajlar geri alınamaz.", "x-permission": "messages:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "İptal edildi" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/broadcasts/{id}/recipients": { "get": { "tags": [ "Broadcast" ], "operationId": "listBroadcastRecipients", "summary": "Kampanya alıcılarını listele", "x-permission": "messages:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Alıcı listesi" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Webhook ayarını getir", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "Aktif webhook ayarı", "content": { "application/json": { "example": { "success": true, "data": { "url": "https://partner.example.com/zenwapp/webhook", "events": [ "message.received", "message.status" ], "is_active": true, "timeout_seconds": 30 } } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "setWebhook", "summary": "Webhook tanımla/güncelle", "description": "Production ortamında webhook URL'i **HTTPS olmak zorundadır**. Geçersiz event adı gönderilirse istek reddedilir ve geçerli event listesi yanıtta döner.", "x-permission": "API anahtarı doğrulaması", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "default": [ "message.received", "message.sent", "message.status" ], "items": { "type": "string", "enum": [ "message.received", "message.sent", "message.status", "connection.connected", "connection.disconnected" ] } }, "timeout_seconds": { "type": "integer", "default": 30 } } }, "example": { "url": "https://partner.example.com/zenwapp/webhook", "events": [ "message.received", "message.status" ], "timeout_seconds": 30 } } } }, "responses": { "200": { "description": "Webhook kaydedildi" }, "400": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Webhook'u devre dışı bırak", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "Devre dışı bırakıldı" } } } }, "/webhooks/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Test olayı gönder", "description": "Kayıtlı webhook URL'ine örnek bir olay gönderir. İmza doğrulama kurulumunuzu canlı trafikten önce sınamak için kullanın.", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "Test olayı gönderildi" } } } }, "/webhooks/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Secret'ı yenile", "description": "İmzalama secret'ını yeniler ve yanıtta **yalnızca bir kez** döndürür. Yeni secret devreye girdiği anda eski imzalar geçersiz olur.", "x-permission": "API anahtarı doğrulaması", "responses": { "200": { "description": "Yeni secret", "content": { "application/json": { "example": { "success": true, "secret": "whsec_..." } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Panelden oluşturduğunuz API anahtarı. `wa_live_` veya `zw_` ile başlar." } }, "parameters": { "PhonePath": { "name": "phone", "in": "path", "required": true, "description": "Ülke kodlu telefon numarası.", "schema": { "type": "string", "examples": [ "905551234567" ] } }, "IdPath": { "name": "id", "in": "path", "required": true, "description": "Kaynak kimliği (UUID).", "schema": { "type": "string", "format": "uuid" } } }, "requestBodies": { "MediaShorthand": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "media_url": { "type": "string" }, "media_data": { "type": "string", "description": "Base64 içerik." }, "mimetype": { "type": "string" }, "filename": { "type": "string" }, "caption": { "type": "string" } } }, "example": { "to": "905551234567", "media_url": "https://cdn.example.com/gorsel.jpg", "caption": "Yeni ürün" } } } } }, "responses": { "Unauthorized": { "description": "API anahtarı eksik veya geçersiz", "content": { "application/json": { "example": { "error": "invalid_api_key", "message": "API key is missing or invalid" } } } }, "Forbidden": { "description": "API anahtarının bu uç için yetkisi yok", "content": { "application/json": { "example": { "error": "forbidden", "message": "Missing permission: messages:send" } } } }, "ValidationError": { "description": "Gövde veya sorgu parametreleri geçersiz", "content": { "application/json": { "example": { "error": "validation_error", "message": "Missing required field: to" } } } }, "NotFound": { "description": "Kaynak bulunamadı", "content": { "application/json": { "example": { "error": "not_found", "message": "Resource not found" } } } }, "RateLimited": { "description": "Hız limiti aşıldı. `X-RateLimit-Reset` başlığındaki ana kadar bekleyin.", "content": { "application/json": { "example": { "error": "rate_limit_exceeded", "message": "Too many requests" } } } } } } }