--- title: "Mesajlaşma API Entegrasyonu: REST, SMPP ve Webhook" description: "Geliştiriciler için mesajlaşma API entegrasyon rehberi: REST, SMPP ve webhook farkları, kimlik doğrulama, idempotency, iletim raporları, yeniden deneme ve test." canonical: "https://omnichannels.ai/tr/blog/messaging-api-integration-guide/" language: "tr" updated: "2026-10-10" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "messaging api integration guide" keywords: ["sms api entegrasyonu", "sms api ve smpp farkı", "whatsapp api webhook iletim durumu", "idempotency key nedir", "iletim raporu dlr", "api rate limit 429 yeniden deneme", "mesajlaşma api sandbox testi"] published: "2026-10-09" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 9 answer: "Uygulamalarınızdan mesaj göndermek için REST API, yalnızca zaten telekom düzeyinde altyapı işlettiğiniz yüksek hacimli SMS için SMPP, iletim raporlarını ve gelen mesajları almak için ise webhook kullanın. Her çağrıyı doğrulayın, yeniden denemelerin mesajı çoğaltmaması için her gönderimde bir idempotency anahtarı yollayın, iletim durumunu asenkron kabul edin, HTTP 429 ve 5xx hatalarında geri çekilin ve canlıya geçmeden önce hata senaryolarını sandbox ortamında test edin." takeaways: ["REST çoğu uygulama entegrasyonuna uygundur; SMPP ise mesajlaşma sistemleri arasında SMS aktarım hızı için tasarlanmış kalıcı bir ikili protokoldür.", "Kabul edilen bir gönderim isteği mesajın kuyruğa alındığı anlamına gelir, iletildiği anlamına gelmez; nihai durum daha sonra webhook veya SMPP iletim raporlarıyla gelir.", "HTTP 429 Too Many Requests, RFC 6585 içinde tanımlıdır; istemciler yavaşlamalı ve varsa Retry-After başlığına uymalıdır.", "Idempotency anahtarları, zaman aşımına uğrayan bir gönderimi müşteriye aynı mesajı iki kez yollamadan güvenle yeniden denemenizi sağlar.", "Meta, WhatsApp Cloud API webhook'larını imzalar; böylece alıcı taraf olayların gerçekten Meta'dan geldiğini doğrulayabilir."] faq: - q: "Mesajlaşma sağlayıcısına REST ile mi SMPP ile mi bağlanmalıyım?" a: "Neredeyse tüm uygulama senaryolarında REST seçin: HTTPS üzerinden çalışır, güvenliği sağlamak kolaydır ve WhatsApp gibi zengin kanalları destekler. Yüksek hacimli SMS gönderiyorsanız, SMPP istemcileri zaten işletiyorsanız ve pencereleme (windowing) özellikli kalıcı bir bağlantıya ihtiyacınız varsa SMPP'yi seçin. SMPP yalnızca SMS için geçerlidir; WhatsApp, e-posta ve sosyal kanallar HTTP API kullanır." - q: "Mesajlaşma API'sinde idempotency anahtarı nedir?" a: "Idempotency anahtarı, sistemlerinizin bir istekle birlikte gönderdiği benzersiz bir değerdir; sunucu tekrarlanan istekleri bu sayede tanır. Gönderim çağrınız zaman aşımına uğrar ve aynı anahtarla yeniden denerseniz, sağlayıcı ikinci bir mesaj göndermek yerine ilk sonucu döndürür. IETF'nin Idempotency-Key HTTP başlığı için bir taslak standardı vardır, ancak sağlayıcılar anahtarları farklı şekillerde uyguladığından dokümantasyonu kontrol edin." - q: "İletim raporları neden bazen sırasız gelir?" a: "Durum olayları operatörler, Meta ve sağlayıcı gibi farklı sistemler tarafından üretilir ve yeniden denemelerle ağ üzerinden iletilir. Okundu olayı, iletildi olayından önce gelebilir ve mükerrer olaylar normaldir. Her durumu zaman damgasıyla saklayın, bir mesajı hiçbir zaman sonraki bir durumdan öncekine geri götürmeyin ve mesaj kimliği ile durum üzerinden mükerrer kayıtları ayıklayın." - q: "Uygulamam hız sınırlarını (rate limit) nasıl yönetmeli?" a: "Sağlayıcının belgelenmiş sınırlarını okuyun, giden gönderimleri kullanıcı isteklerinden doğrudan tetiklemek yerine kuyruğa alın ve kendi tarafınızda token bucket gibi bir sınırlayıcı kullanın. HTTP 429 aldığınızda duraklayın ve Retry-After başlığındaki süre kadar sonra ya da jitter ile üstel geri çekilme uygulayarak yeniden deneyin. 4xx doğrulama hatalarını yeniden denemeyin." - q: "Mesajlaşma sandbox ortamında neleri test etmeliyim?" a: "Kimlik doğrulama hatalarını, geçersiz telefon numaralarını, şablon değişkeni hatalarını, idempotent yeniden denemelerle zaman aşımlarını, mükerrer ve sırasız webhook'ları, hız sınırı yanıtlarını, uzun ve Arapça mesajları ve webhook imza doğrulamasını test edin. Ardından gerçek numaralarla küçük bir canlı pilot yapın; çünkü sandbox ortamları operatör veya Meta davranışını nadiren birebir yansıtır." sources: - title: "Cloud API webhook'ları — Meta for Developers" url: "https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks" - title: "RFC 6585: Ek HTTP durum kodları (429 Too Many Requests)" url: "https://www.rfc-editor.org/rfc/rfc6585" - title: "RFC 9110: HTTP Semantiği" url: "https://www.rfc-editor.org/rfc/rfc9110" - title: "Idempotency-Key HTTP başlık alanı — IETF taslağı" url: "https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/" - title: "SMPP protokol belirtimi kaynakları — SMPP.org" url: "https://smpp.org/" --- # Mesajlaşma API Entegrasyonu: REST, SMPP ve Webhook Canonical: https://omnichannels.ai/tr/blog/messaging-api-integration-guide/ Language: tr Publisher: OmniChannels.ai by BroadNet Technologies Bu rehber, bir uygulamayı WhatsApp, SMS veya e-posta için bir mesajlaşma sağlayıcısına bağlayan arka uç geliştiricileri, çözüm mimarları ve CTO'lar için hazırlandı. Hangi arayüzün kullanılacağını; kimlik doğrulama, idempotency, iletim raporları, yeniden denemeler, hız sınırları ve testlerin nasıl ele alınacağını, örnek istek ve yanıt yapılarıyla anlatır. Konuşmaları CRM ile senkronize etmek için [webhook'larla CRM bağlama](/blog/connect-crm-omnichannel-inbox-webhooks/) rehberine de göz atabilirsiniz. ## Hangi arayüzü kullanmalısınız: REST, SMPP veya webhook? Göndermek için REST, almak için webhook kullanın; SMPP'yi ise yalnızca zaten SMPP işlettiğiniz yüksek hacimli SMS için tercih edin. Bunlar rakip değil, birbirini tamamlayan yöntemlerdir: çoğu entegrasyon, giden tarafta REST çağrılarını, dönüş tarafında webhook'ları birlikte kullanır. | Özellik | REST API | SMPP | Webhook | |---|---|---|---| | Yön | Uygulamanız → sağlayıcı | Tek oturum üzerinden çift yönlü | Sağlayıcı → uygulamanız | | Aktarım | HTTPS istek/yanıt | Kalıcı TCP oturumu, ikili PDU'lar | Uç noktanıza HTTPS POST | | Kanallar | WhatsApp, SMS, e-posta, diğerleri | Yalnızca SMS | Tüm kanalların olayları | | Tipik kullanım | Mesaj göndermek, şablon yönetmek, durum sorgulamak | Mesajlaşma sistemleri arası toplu SMS | İletim durumu, gelen mesajlar | | Güçlü yanı | Basit, güvenlik duvarı dostu, zengin içerik | Aktarım hızı, pencereleme, telekom standardı | Gerçek zamanlı, sorgulama gerekmez | | Dikkat edilecekler | Hız sınırları, zaman aşımları | Oturum yönetimi, bind işlemleri, keep-alive | Yeniden denemeler, mükerrer olaylar, güvenlik | SMPP (Short Message Peer-to-Peer) oturumları bir bind ile (transmitter, receiver veya transceiver) başlar, mesajları `submit_sm` ile gönderir, iletim raporlarını ve gelen SMS'leri `deliver_sm` ile alır ve `enquire_link` ile canlı kalır. Verimlidir ancak işletmesi HTTPS'ten daha ağırdır. ## Kimlik doğrulama nasıl yapılmalı? Sağlayıcının sunduğu en güçlü yöntemi kullanın, gizli anahtarları koddan uzak tutun ve her iki yönü de doğrulayın. - **Giden çağrılar:** TLS üzerinden `Authorization` başlığında gönderilen API anahtarları veya OAuth 2.0 bearer token'lar. Bunları bir gizli anahtar yöneticisinde saklayın; düzenli aralıklarla ve personel değişikliklerinden sonra yenileyin. - **SMPP:** bind sırasında sistem kimliği ve parola; genellikle izin verilen IP adresleriyle sınırlandırılır ve destekleniyorsa TLS üzerinden kullanılır. - **Gelen webhook'lar:** her olayda imzayı doğrulayın. Meta, WhatsApp Cloud API webhook yüklerini uygulama gizli anahtarınızla hesaplanan, `X-Hub-Signature-256` başlığındaki bir HMAC-SHA256 imzasıyla imzalar; sağlayıcılar genellikle benzer bir şema sunar. İmzayı, içeriği ayrıştırmadan önce ham gövde üzerinden hesaplayın. Sızan bir test anahtarının canlı trafik gönderememesi için her ortam için ayrı kimlik bilgileri kullanın. ## Bir mesaj güvenli biçimde nasıl gönderilir? Kuyruk üzerinden gönderin, bir idempotency anahtarı ekleyin ve yanıtı "iletildi" değil, "kabul edildi" olarak değerlendirin. ### Örnek gönderim isteği Aşağıdaki yapı, belirli bir sağlayıcının API'si değil, açıklama amaçlı sözde JSON'dur. ```json POST /v1/messages Authorization: Bearer Idempotency-Key: 7f3c9a2e-order-55821-shipped { "channel": "whatsapp", "to": "+9715XXXXXXXX", "template": { "name": "order_shipped", "language": "ar", "variables": ["Layla", "55821", "15 March"] }, "client_reference": "order-55821", "callback_url": "https://api.example.com/webhooks/messaging" } ``` ### Örnek yanıt ```json 202 Accepted { "message_id": "msg_01HZX...", "status": "accepted", "client_reference": "order-55821", "created_at": "2026-10-09T12:00:00Z" } ``` `message_id` değerini hemen kendi referansınızla birlikte saklayın. Bundan sonra olan her şey asenkron olarak gelir. ## Idempotency neden önemlidir? Çünkü ağ zaman aşımları, sunucu işlemi zaten yaptıktan sonra gerçekleşebilir. Gönderim isteğiniz zaman aşımına uğradığında körlemesine yeniden denerseniz müşteri iki OTP veya iki kargo bildirimi alabilir. Idempotency anahtarı, sunucunun yeniden denemeyi tanımasını ve ilk sonucu döndürmesini sağlar. İşe yarayan kurallar: 1. Anahtarı her denemede rastgele bir değerden değil, iş olayından türetin (örneğin sipariş kimliği ile olay türü). 2. Aynı gönderimin her yeniden denemesinde aynı anahtarı kullanın. 3. Anahtarları, yeniden deneme pencerenizi kapsayacak kadar uzun süre saklayın. 4. Sağlayıcı anahtarları desteklemiyorsa göndermeden önce mükerrer kayıtları kendi tarafınızda ayıklayın. IETF'nin taslak Idempotency-Key başlığı bu deseni HTTP API'leri için standartlaştırır; sağlayıcıların uygulamaları farklılık gösterdiğinden dokümantasyonlarını okuyun. ## İletim raporları nasıl çalışır? İletim durumu sonradan olay olarak gelir: WhatsApp ve çoğu REST API için webhook'larla, SMPP'de ise `deliver_sm` raporlarıyla. Durumların anlamı kanala göre değişir; [mesaj iletim durumu](/blog/message-delivery-status-explained/) rehberimiz her birini açıklar. ### Örnek durum webhook'u ```json POST /webhooks/messaging X-Signature: sha256= { "event_id": "evt_9c1...", "type": "message.status", "message_id": "msg_01HZX...", "client_reference": "order-55821", "status": "delivered", "timestamp": "2026-10-09T12:00:04Z", "error": null } ``` Durum olaylarını savunmacı biçimde işleyin: - **Mükerrer olayları ayıklayın:** `event_id` üzerinden ya da mesaj kimliği artı durum üzerinden. - **Geri gitmeyin:** olaylar sırasız geldiğinde bir mesajı okundu durumundan tekrar iletildi durumuna döndürmeyin. - **Hızlıca 2xx ile yanıtlayın**, sonra işlemeyi bir kuyruktan yapın. - **Hata kodlarını kaydedin:** başarısız mesajlar için hangilerinin yeniden denenebilir olduğuna karar verin. - **Boşluklar beklenmeli:** bazı SMS rotaları sınırlı rapor döndürür; okundu durumu ise kanala ve kullanıcının ayarlarına bağlıdır. ## Yeniden denemeler ve hız sınırları nasıl yönetilmeli? Yalnızca başarılı olabilecek istekleri yeniden deneyin, jitter ile üstel geri çekilme uygulayın ve sunucunun sinyallerine uyun. | Yanıt | Anlamı | Yapılacak | |---|---|---| | 2xx | Kabul edildi | Kimliği saklayın, durumu bekleyin | | 400 / 422 | Geçersiz istek (numara, şablon, değişkenler) | Yeniden denemeyin; veriyi düzeltin | | 401 / 403 | Kimlik doğrulama veya yetki sorunu | Yeniden denemeyin; uyarı verin | | 409 | Çakışma, çoğunlukla mükerrer idempotency anahtarı | İlk sonucu getirin | | 429 | Çok fazla istek (RFC 6585) | Retry-After süresini bekleyin veya geri çekilin | | 5xx / zaman aşımı | Sunucu veya ağ hatası | Aynı idempotency anahtarı ve geri çekilmeyle yeniden deneyin | RFC 9110, saniye veya tarih taşıyabilen `Retry-After` başlığını tanımlar. Sağlayıcının belgelenmiş sınırlarını hatalar üzerinden öğrenmek yerine altında kalmak için gönderimlerinizin önüne istemci tarafında bir hız sınırlayıcı koyun. WhatsApp'ta ayrıca Meta tarafında, kaç benzersiz müşteriye mesaj atabileceğinize dair sınırlar da vardır; bunlar [mesajlaşma limitleri ve kalite puanı](/blog/whatsapp-messaging-limits-quality-rating/) yazısında anlatılır. ## Canlıya geçmeden önce nasıl test etmelisiniz? Yalnızca sorunsuz senaryoyu değil, hata senaryolarını da test edin. ### Canlı öncesi kontrol listesi 1. Her şablonu, Arapça metin dahil gerçek uzunlukta değerlerle gönderin. 2. Bir zaman aşımını zorlayın ve yeniden denemenin mesajı çoğaltmadığını doğrulayın. 3. Geçersiz bir numaraya gönderin ve hatanın yeniden deneme yapılmadan ele alındığını doğrulayın. 4. Bir webhook'u iki kez ve sırasız tekrar oynatın; tek bir nihai durum oluştuğunu doğrulayın. 5. Hatalı imzalı bir webhook gönderin; reddedildiğini doğrulayın. 6. İzin veriliyorsa sandbox'a yük testi uygulayarak 429 yanıtlarını tetikleyin. 7. Bir API anahtarını yenileyin ve kesinti olmadığını doğrulayın. 8. Günlüklerde mesaj kimliklerinin bulunduğunu, ancak tam mesaj içeriklerinin veya OTP kodlarının bulunmadığını kontrol edin. 9. Her kanalda şirket içi numaralarla küçük bir canlı pilot çalıştırın. Sandbox ortamları operatör ve Meta davranışını nadiren birebir yansıttığından, canlıya geçişin ilk haftalarında izlemeyi sürdürün. ## Uygulamalı örnek: OTP ve sipariş bildirim servisi Suudi Arabistan'da faaliyet gösteren bir kargo şirketi olan "Qafilah Logistics" (kurgusal), WhatsApp üzerinden sipariş güncellemeleri gönderiyor, SMS'i yedek olarak kullanıyor ve kimlik doğrulama OTP'leri iletiyor. - **Mimari:** sipariş olayları bir kuyruğa gider; gönderici işçi (worker), `shipment-id:event` biçimindeki idempotency anahtarıyla REST API'yi çağırır. - **Yedek:** WhatsApp kullanmayan bir kullanıcı için başarısız durumu dönerse, işçi yeni bir anahtarla (`shipment-id:event:sms`) SMS gönderir. - **OTP:** kodların süresi çabuk dolduğundan, OTP gönderimleri süre penceresi geçtikten sonra yeniden denenmez; kullanıcı yeni kod ister. [OTP kimlik doğrulama mesajları rehberine](/blog/otp-authentication-messages-guide/) bakın. - **Raporlar:** bir webhook alıcısı imzaları doğrular, mükerrer olayları ayıklar ve asla geriye gitmeyen bir durum tablosunu günceller. - **Sınırlar:** token bucket tabanlı bir sınırlayıcı, kanal başına gönderim hızını belgelenmiş sınırların altında tutar. ## Entegrasyonda sık yapılan hatalar nelerdir? - "Kabul edildi" durumunu "iletildi" sanmak. - Her denemede yeni bir idempotency anahtarıyla yeniden denemek. - Webhook isteğinin içinde ağır işlem yapmak. - Webhook'larda imza doğrulamasını atlamak. - 4xx doğrulama hatalarını döngü halinde yeniden denemek. - OTP kodlarını ve tam mesaj içeriğini günlüğe yazmak. - Test ortamlarında canlı kimlik bilgileri kullanmak. ## OmniChannels.ai nasıl yardımcı olur? BroadNet Technologies altyapısıyla çalışan OmniChannels.ai; SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, e-posta ve push kanallarını kapsayan, OpenAPI 3.1 spesifikasyonu ve TypeScript SDK'sı bulunan, herkese açık dokümante edilmiş bir REST/JSON API sunar. Buna tek dokunuşlu, sıfır dokunuşlu ve kod kopyalama OTP seçenekli WhatsApp kimlik doğrulama şablonları da dahildir. [Webhook'lar](/developers/webhooks/) iletim durumlarını tek bir normalleştirilmiş biçimde bildirir, [SMPP 3.4](/developers/smpp/) TLS üzerinden yüksek hacimli SMS'e hizmet eder ve bir [MCP sunucusu](/developers/mcp/) yapay zeka ajanlarını bağlar. Filtreli ve CSV dışa aktarımlı iletim raporları, entegrasyonunuzun gönderdiklerini mutabakata bağlamanıza yardımcı olur. [Geliştirici dokümanları](/developers/) ve [hızlı başlangıç](/developers/quickstart/) ile başlayın.