Entegrasyon kurulum rehberi

1. Hangi entegrasyonları sunuyoruz?

Zetan AI'nın entegrasyon kataloğu sürekli genişliyor. Mevcut entegrasyonları üç ana grupta inceleyebiliriz: mesajlaşma kanalları, sektörel sistemler ve genel araçlar.

Listede aradığınız entegrasyon yoksa Webhook yöntemiyle hemen hemen tüm modern API'lere bağlanabilirsiniz. Daha karmaşık ihtiyaçlar için entegrasyon talebi formunu doldurabilir, ekibimizle özel bir geliştirme planı yapabilirsiniz.

2. WhatsApp Business bağlantısı (adım adım)

WhatsApp Business entegrasyonu, müşterilerinize asistan üzerinden mesaj göndermenizin en yaygın yoludur. Bağlantı süreci, Meta'nın Business Manager onayını gerektirdiği için diğer entegrasyonlardan biraz daha uzun sürer.

2.1. Ön koşullar

• Meta Business Manager hesabı (ücretsiz): business.facebook.com adresinden açılır.
• Doğrulanmış işletme: Şirketin Meta tarafından onaylanmış olması gerekir (vergi levhası veya ticaret sicil belgesi ile).
• Adına numara açılacak GSM hattı: Daha önce başka bir WhatsApp Business API hesabına bağlı olmamalı.
• İşletmenin profil resmi ve kısa açıklaması hazır bulunmalı.

2.2. Adım 1 — Entegrasyonu başlatın

Zetan AI panelinde Ayarlar → Entegrasyonlar → WhatsApp Business sayfasını açın. Sağ üstteki “Bağlantıyı başlat” butonuna tıkladığınızda Meta'nın yetkilendirme penceresi açılır.

2.3. Adım 2 — İşletmenizi seçin

Meta hesabınızla giriş yaptıktan sonra Zetan AI'ya hangi Business Manager hesabı üzerinden bağlantı kuracağınızı seçersiniz. Birden fazla hesabınız varsa dikkatli olun; yanlış hesap seçilirse mesajlar başka bir firmanın adıyla gönderilir.

2.4. Adım 3 — Telefon numarasını doğrulayın

WhatsApp Business numaranızı girip doğrulama kodunu alın. Kod SMS veya sesli arama ile gelir. Numara, daha önce kişisel WhatsApp uygulamasında kullanıldıysa, önce o cihazdan numaranın çıkarılması gerekir.

2.5. Adım 4 — Mesaj şablonlarını oluşturun

WhatsApp Business API kuralları gereği, müşteri sizinle 24 saat içinde mesajlaşmamışsa yalnızca onaylanmış şablonlar üzerinden mesaj gönderebilirsiniz. Zetan AI panelinde hazır şablonları seçip Türkçe metinleri özelleştirebilir, Meta onayına gönderebilirsiniz. Onay süresi genelde 10 dakika ile 24 saat arasında değişir.

2.6. Adım 5 — Test mesajı gönderin

Kurulum tamamlandığında “Test mesajı gönder” butonunu kullanarak kendi numaranıza bir mesaj atın. Mesaj saniyeler içinde geldiyse entegrasyon başarılı demektir.

3. PMS bağlantısı (Protel, Opera, Sirius)

Otelciler için en kritik entegrasyon PMS (Property Management System) bağlantısıdır. Zetan AI, Türkiye'de en yaygın kullanılan üç PMS ile resmi entegrasyona sahiptir: Protel, Opera Cloud ve Sirius.

3.1. Protel PMS

Protel için iki bağlantı seçeneği vardır: API anahtarı (Protel 5.x ve üzeri) veya HTNG mesajlaşma (eski sürümler). Protel destek ekibinizden, kullandığınız sürümü ve hangisinin aktif olduğunu öğrenin.

API anahtarı ile bağlamak için:

1. Protel masaüstü uygulamasında Kurulum → Sistem Parametreleri → Web Servisleri menüsünü açın.
2. “Yeni anahtar oluştur” butonuna basın. Açıklama olarak Zetan AI yazın.
3. Oluşan 64 karakterlik anahtarı kopyalayın.
4. Zetan AI panelinde Ayarlar → Entegrasyonlar → Protel sayfasında anahtarı yapıştırın.
5. Sunucu URL'sini girin (genellikle https://protel.otelinizinadi.com:443/api formatında).
6. “Bağlan” butonuna basın; başarılı bağlantıda oda tipleri ve fiyat listeleri otomatik olarak çekilir.

3.2. Opera Cloud PMS

Oracle Opera Cloud için OHIP (Opera Hospitality Integration Platform) üzerinden bağlantı kurulur. Bunun için Oracle'dan OHIP yetkilendirme istemeniz gerekir; süreç genelde otel zincirinizin BT departmanı tarafından yürütülür.

Yetkilendirme alındıktan sonra Zetan AI panelinde Client ID, Client Secret, External System Code ve Hotel ID bilgilerini gireceğiniz bir form karşılar sizi. Tüm alanlar dolu olduğunda bağlantı testi yapılır.

3.3. Sirius PMS

Sirius için bağlantı en kolay olanıdır: Sirius Cloud panelinden tek tıkla “Zetan AI'ya izin ver” butonunu kullanın, ardından açılan onay sayfasında bilgilerinizi doğrulayın. İki sistem 30 saniye içinde senkronize olur.

4. SGK bağlantısı (sigorta ve eczane)

SGK entegrasyonu, sigorta acenteleri için poliçe sorgulama, eczaneler için ise MEDULA reçete sorgulama işlemlerini otomatikleştirmek için kullanılır.

4.1. Sigorta acentesi bağlantısı

Sigorta acenteleri için SGK'ya doğrudan bağlanmak yerine, anlaşmalı olduğunuz sigorta şirketlerinin acente portalları üzerinden bağlanırsınız. Zetan AI; Allianz, Anadolu, Aksigorta, AXA, HDI, Mapfre, Quick, Sompo, Türk Nippon ve Türkiye Sigorta ile entegredir.

Bağlantı için her sigorta firmasının acente kodunuzu ve API kullanıcı/şifre bilgilerini girmeniz yeterlidir. Bilgiler Zetan AI üzerinde uçtan uca şifrelenir ve yalnızca teklif/poliçe işlemleri için kullanılır.

4.2. Eczane MEDULA bağlantısı

Eczaneler için bağlantı e-Devlet üzerinden SGK MEDULA Eczane Provizyon Sistemi'ne yapılır. Bağlantı için işyeri sicil numarası, MEDULA kullanıcı adı ve şifrenizi girmeniz gerekir.

4.3. Test ortamı

Canlı SGK ortamına bağlanmadan önce test ortamında deneme yapmanızı öneririz. Test ortamında sahte bir poliçe veya reçete üzerinden tüm akışı görebilir, asistanın davranışını gözlemleyebilirsiniz. Test ortamı her workspace için varsayılan olarak açıktır.

5. E-posta SMTP yapılandırması

Müşterilerinize asistan üzerinden e-posta göndermek istiyorsanız, kendi e-posta sunucunuzu (SMTP) Zetan AI'ya tanıtmanız gerekir. Bu sayede gönderilen e-postalar sizin alan adınızdan çıkar; müşteri gözünde “ornek@firma.com” gibi güvenilir bir adres görünür.

5.1. Gerekli bilgiler

• SMTP sunucu adresi (örnek: smtp.gmail.com, smtp.office365.com, mail.firma.com)
• Port (587 / TLS, 465 / SSL, 25 yaygın değildir ve önerilmez)
• Kullanıcı adı (genellikle e-posta adresinizin tamamı)
• Şifre (Gmail / Outlook için uygulama şifresi öneririz)

5.2. Gmail ile bağlanma

Gmail için iki adımlı doğrulama açıksa, hesabınıza gelip giderken normal şifrenizi kullanamazsınız. Bunun yerine Google Hesap ayarlarından “Uygulama Şifreleri” bölümüne girerek “Zetan AI” adında 16 karakterlik bir şifre üretin ve onu kullanın.

5.3. Microsoft 365 ile bağlanma

Microsoft 365 için SMTP AUTH'un etkin olması gerekir. Yönetici hesabı ile Exchange Admin Center'a girip ilgili kullanıcı için bu özelliği açın. Bağlantı bilgileri:

5.4. Kendi sunucunuzla bağlanma

Kurumsal e-posta sunucunuz varsa (Postfix, Exim, Exchange Server vb.) sistem yöneticinizden SMTP relay yetkisi almanız gerekir. Zetan AI'nın gönderim yapacağı sabit IP listesini panel içinde bulabilirsiniz; bu IP'leri sunucunuzun beyaz listesine eklemeniz önerilir.

5.5. SPF / DKIM / DMARC

E-postaların spam'e düşmemesi için alan adınızda SPF, DKIM ve DMARC kayıtlarını doğru tanımlamış olmanız önemlidir. Zetan AI üzerinden gönderilecek e-postalar için aşağıdaki SPF kaydını ekleyin:

6. Webhook ile özel entegrasyon

Hazır entegrasyonlar dışında, neredeyse tüm modern sistemlerle webhook yöntemiyle iletişim kurabilirsiniz. Bu yöntem hem giden (Zetan AI'dan dış sisteme) hem de gelen (dış sistemden Zetan AI'ya) çağrılar için kullanılır.

6.1. Giden webhook (outbound)

Asistanınız bir görev tamamladığında veya belirli bir olay gerçekleştiğinde dış bir URL'ye HTTP POST isteği gönderebilir. Örneğin yeni bir rezervasyon onaylandığında muhasebe yazılımınıza otomatik bildirim gönderebilirsiniz.

Webhook tanımlamak için Ayarlar → Entegrasyonlar → Webhook sayfasında:

1. Tetikleyici olayı seçin (örn. task.completed, reservation.created).
2. Hedef URL'yi girin (HTTPS zorunlu).
3. İsteğe bağlı HMAC gizli anahtarı tanımlayın; bu sayede dış sistem isteğin gerçekten Zetan AI'dan geldiğini doğrulayabilir.
4. “Test isteği gönder” ile bağlantıyı doğrulayın.

6.2. Örnek JSON yükü

6.3. Gelen webhook (inbound)

Dış bir sistemin Zetan AI'ya veri göndermesini sağlamak için, panelde size özel bir inbound URL oluşturulur. Bu URL https://hook.zetan.ai/in/<workspace_id>/<handler_id> formundadır.

URL'ye gelen her POST isteği, tanımladığınız otomasyon kurallarına göre işlenir. Örneğin web sitenizdeki form gönderimi geldiğinde otomatik olarak yeni bir görev oluşturabilir veya WhatsApp'tan hoş geldin mesajı tetikleyebilirsiniz.

6.4. Güvenlik

Tüm webhook trafiği HTTPS üzerinden gerçekleşir. HMAC-SHA256 imzası kullanarak isteğin bütünlüğünü doğrulayabilirsiniz; örnek doğrulama kodları panel içinde Node.js, Python, PHP ve Go için hazır olarak bulunur.

7. Sorun giderme

Entegrasyon kurulumu sırasında en sık karşılaşılan sorunlar ve çözümleri.

7.1. Bağlantı testi başarısız oluyor

• Bilgileri kontrol edin: API anahtarı, URL ve port doğru girilmiş mi? Boşluk veya satır sonu karakteri var mı?
• Güvenlik duvarı: Şirket ağınızdaki güvenlik duvarı Zetan AI sunucularının erişimini engelliyor olabilir. IP beyaz listesi ekleyin.
• Sertifika hatası: Hedef sistemin SSL sertifikası geçerli mi? Kendi imzalı sertifikalar reddedilir.

7.2. Mesajlar gönderilmiyor

• WhatsApp: Müşteri ile son mesajlaşmadan bu yana 24 saatten fazla geçtiyse yalnızca onaylı şablonları kullanabilirsiniz.
• E-posta: SPF/DKIM kayıtları doğru mu? Domain reputation skorunuz düşük olabilir.
• SMS: Bakiyenizi kontrol edin. Netgsm veya İletimerkezi paneline giriş yapıp gönderim raporlarını inceleyin.

7.3. Veriler senkronize olmuyor

PMS entegrasyonlarında veriler genelde 30 saniye - 5 dakika içinde senkronize olur. Eğer beklenenden uzun süre geçtiyse Ayarlar → Entegrasyonlar → [İlgili PMS] → Loglar bölümünden son hataları kontrol edin. Yaygın nedenler: PMS sunucusu yeniden başlatılmış olabilir, API anahtarı süresi dolmuş olabilir veya kotanız aşılmış olabilir.

7.4. Yardım alma

Tüm bu adımlara rağmen sorununuz çözülmediyse destek ekibimizle iletişime geçin. Hızlı çözüm için aşağıdaki bilgileri hazırlayın:

• Workspace adınız ve workspace ID'niz (panel ayarlarından kopyalayabilirsiniz).
• Bağlanmaya çalıştığınız entegrasyon ve adımın hangi noktasında takıldığınız.
• Hata mesajının ekran görüntüsü.
• Mümkünse, tarayıcı geliştirici konsolundan alınan hata logları.