Kurye entegrasyonu rehberi: POS ve site siparişini kurye firmanıza otomatik iletmek

Paket servis yapan bir restoranda yoğun saatlerde en çok zaman kaybettiren işlerden biri, POS ekranına düşen siparişi kurye firmasının paneline yeniden yazmaktır. Telefon numarası, adres, tutar ve ödeme türü elle kopyalanır. Bir harf yanlış girildiğinde kurye yanlış kapıya gider, sipariş gecikir. Kurye entegrasyonu bu tekrar eden işi ortadan kaldırmak için vardır.

Otopilot'un Kurye/Kargo Entegrasyonu, restoranınızın kendi POS veya sipariş sistemindeki yeni paket siparişlerini kendi kurye ya da kargo firması hesabınıza otomatik iletir. Gönderim başarılı olduğunda ya da hata aldığında isterseniz Telegram'dan haber verir. Bu rehberde köprünün nasıl çalıştığını, kimin için uygun olduğunu, kurulumun hangi adımlardan oluştuğunu ve bilmeniz gereken sınırları anlatıyoruz.

Kurye entegrasyonu nasıl çalışır?

Köprü bir adaptör mimarisiyle çalışır. Bir uçta siparişi okuyan POS adaptörü, diğer uçta siparişi gönderen kurye adaptörü bulunur. Aradaki her sipariş ortak bir biçime çevrilir ve sunucudaki bir kuyrukta bekler.

Akış kısaca şöyledir: POS adaptörü yeni siparişi alır, sipariş müşteri adı, telefon, adres, tutar, ödeme türü, ürünler ve not alanlarıyla ortak biçime dönüşür, kuyruğa yazılır, kurye adaptörü kuyruktaki siparişi firmanıza gönderir. Gönderim başarısız olursa sipariş yeniden denenir. Belirlenen deneme sayısı dolarsa sipariş "başarısız" işaretlenir ve "elle girin" bildirimi gelir.

Kurulumu ve firma başına yapılandırmayı ekibimiz yapar. Bunun nedeni basittir: her POS ve her kurye firması farklı veri biçimi kullanır. Hazır adaptörler bu farkın büyük kısmını karşılar, kalan eşleştirme kurulum sırasında yapılır.

Elle giriş ile otomatik aktarım arasındaki fark

Elle girişte her sipariş için aynı bilgiler ikinci kez yazılır. Bu hem zaman alır hem de hata riski taşır: telefon numarasında eksik bir hane ya da adreste atlanan bir kapı numarası, kuryenin müşteriyi aramasına ve teslimatın gecikmesine yol açar. Otomatik aktarımda bilgiler POS'taki kayıttan olduğu gibi alınır. Personel siparişi mutfağa iletir, kurye çağırma işi arka planda yürür.

Bu, personelin tamamen devreden çıktığı anlamına gelmez. Başarısız bir gönderimde bildirimi gören kişi siparişi elle girer. Kuru çalıştırma döneminde de kayıtlar bir kişi tarafından kontrol edilir. Köprünün amacı tekrar eden yazma işini kaldırmak, kontrolü insanda bırakmaktır.

POS ve kurye tarafındaki adaptörler

Ürün sayfasındaki kurulum kalemlerinde POS tarafı için Adisyo, Simpra ve "kendi siteniz", kurye tarafı için CallCourier ve Byersoft ayrı ayrı listelenir. Listede olmayan bir POS ya da kurye firması seçerseniz kapsam teklifle çıkarılır. Yeni bir firma için aynı arayüzle yeni bir adaptör yazılması kurulum hizmetinin parçasıdır.

Kimler için uygun?

Kurye entegrasyonu en çok şu işletmelere zaman kazandırır:

• Site ya da POS siparişlerini kurye firmasının paneline elle giren restoranlar.
• Resmi API sunan bir kurye firmasıyla çalışan ve siparişi otomatik iletmek isteyen işletmeler.
• Kendi sipariş sistemi webhook gönderebilen ya da siparişi dosya veya SQLite veritabanı olarak tutan işletmeler.
• Byersoft paneli kullanan ve kendi hesabıyla otomatik kurye çağırmak isteyen restoranlar.

Kendi sitenizden online sipariş alıyorsanız, köprü o siparişleri de aynı yoldan kuryeye iletebilir. WooCommerce, özel PHP ve Next.js tabanlı siteler ürünün desteklediği platformlar arasındadır. Siparişleri siteden almadan önce sitenizin bağlantı güvenliğini düşünmek isterseniz site bağlantıları rehberi eklenti, API ve webhook kurulumunda dikkat edilmesi gerekenleri anlatır.

Köprü kendi başına bir sipariş sistemi değildir. POS'unuz yoksa ya da siparişleri yalnız telefonla alıyorsanız, aktarılacak dijital bir sipariş kaydı oluşmadığı için köprü bir işe yaramaz.

Kurulum adımları: talepten canlı çalışmaya

Satın alma sonrasında süreç destek talebi üzerinden yürür. Erişim bilgilerinizi yalnız bu talep ekranından iletirsiniz; e-postayla ya da sohbetle şifre paylaşılmaz.

1. Lisansı aldıktan sonra panelde Modüller > Lisanslarım ekranını açın ve lisans kartındaki Kurulum talebini aç düğmesine basın.
2. Talepte POS sisteminizi, kurye firmanızı ve gerekli erişimleri belirtin. Kurye firmanızın API anahtarını ya da Byersoft için kendi kullanıcı bilginizi talep ekranından verirsiniz.
3. Ekibimiz ayar dosyasını oluşturur. Lisans anahtarı, webhook imza sırrı ve kurye API anahtarı gibi gizli değerler dosyaya düz yazılmaz, ortam değişkeni olarak verilir. Webhook imza sırrı en az 16 karakter olmalıdır.
4. Kullanım şartlarının kabul edildiğini gösteren onay alanı açılmadan köprü başlamaz. Byersoft kullanılacaksa kendi hesap oturumunuzla çalışmaya ayrıca açık onay verilir.
5. POS tarafında webhook, jsondir ya da sqlite seçilip ilgili alanlar doldurulur. Kurye tarafında http ya da byersoft seçilir.
6. Lisans ve adaptörler kontrol komutuyla doğrulanır.
7. İlk günler kuru çalıştırma açık bırakılır. Bu kipte siparişler kuyruğa alınır ama kuryeye gönderilmez, kayıtta "KURU" olarak görünür. Böylece eşleştirmenin doğru olduğunu gerçek bir kurye çağırmadan görürsünüz.
8. Sonuçlar doğruysa kuru çalıştırma kapatılır ve köprü sürekli çalışma kipinde, pm2 ya da systemd gibi bir servis yöneticisiyle başlatılır.

Paketle birlikte gelen testler sahte lisans, sahte POS ve sahte kuryeyle, ağa çıkmadan çalışır. Kurulum sonrasında yapılan değişikliklerin bir şeyi bozup bozmadığını görmek için kullanılır.

Kurulumdan önce hazırlamanız gerekenler

Kurulum talebini açmadan önce birkaç bilgiyi hazır tutmak süreci kısaltır. Bunlar teknik ekibin ilk soracağı sorulardır:

• POS ya da sipariş sisteminizin adı ve yeni siparişi nasıl dışarı verdiği: webhook mu gönderiyor, klasöre dosya mı bırakıyor, yoksa siparişler bir SQLite veritabanında mı duruyor?
• Kurye firmanızın resmi API belgesi ve size verdiği API anahtarı. Belge yoksa firmadan istemeniz gerekir.
• Byersoft kullanıyorsanız kendi panel kullanıcınız. Ortak ya da başkasına ait bir hesap kullanılmaz.
• Köprünün çalışacağı sunucu. Node.js 20 ya da üstü ve pm2 veya systemd kullanılabilen bir Linux sunucu yeterlidir.
• Bildirimleri almak istediğiniz Telegram grubu ve kendi Telegram botunuz.
• Hangi teslim türlerinin kuryeye gideceği. Gel-al ve masaya servis siparişleri genellikle süzgeçle dışarıda bırakılır.

Bu bilgiler net olduğunda kurulum çoğunlukla tek bir talep üzerinden tamamlanır. Eksik bilgi olduğunda ekip talebe soru yazar ve yanıtınızı bekler.

Önemli ayarlar

• Döngü aralığı: Köprü kuyruğu varsayılan olarak 10 saniyede bir yoklar.
• En fazla deneme: Hata alan sipariş varsayılan olarak 5 kez denenir, sonra başarısız işaretlenir.
• Teslim türü süzgeci: Yalnız belirlediğiniz teslim türlerindeki siparişler kuyruğa alınır. Boş bırakılırsa hepsi alınır. Gel-al siparişlerini kuryeye göndermemek için kullanışlıdır.
• Telegram bildirimi: Kendi Telegram botunuzun anahtarı ve sohbet kimliğiyle gönderim ve başarısızlık bildirimleri gelir.
• Gövde şablonu: Resmi API'lerde telefon, müşteri adı, adres, tutar, ödeme türü ve not gibi alanlar firmanın beklediği biçime şablonla yerleştirilir.

Güvenlik, veri ve dürüst sınırlar

Kurye entegrasyonu müşterinin adını, telefonunu ve adresini taşır. Bu yüzden güvenlik kararları varsayılan olarak sıkı tutulmuştur.

Webhook adaptörü varsayılan olarak yalnız aynı sunucudan (127.0.0.1) gelen istekleri dinler. Her istek gövdesi HMAC-SHA256 ile imzalanmalıdır; imzası tutmayan istek 401 yanıtıyla reddedilir. Siparişte numara, telefon, adres ya da sayısal tutar eksikse istek 422 yanıtı alır. Dışarıdaki bir sistemden sipariş almak gerekiyorsa dinleme adresi ya da bir ters vekil kurulum sırasında ayarlanır.

Müşteri verisi köprünün çalıştığı sunucuda işlenir ve yalnız sizin kurye firmanıza gönderilir. 6698 sayılı KVKK kapsamındaki veri sorumluluğu restoran sahibine aittir. Pakette satıcıya ait hiçbir POS ya da kurye hesabı yoktur; yetkileri siz verirsiniz.

Bilmeniz gereken sınırlar:

• Byersoft bağlantısı resmi API değildir. Sizin kendi Byersoft panel hesabınızın oturumuyla çalışır. Byersoft panelinde değişiklik olursa bağlantı bozulabilir ve güncelleme gerekebilir. Byersoft kullanım koşullarını kontrol etmek kullanıcının sorumluluğundadır.
• Sıra oluşabilir. Sürekli çalışma kipinde her döngüde kuyruktan bir sipariş iletilir. Varsayılan 10 saniyelik aralıkta, çok yoğun saatlerde siparişler kısa bir sıra bekleyebilir.
• Tek süreç. Kuyruk dosya tabanlıdır ve tek bir süreç için tasarlanmıştır. Aynı klasörle iki kopya çalıştırılmamalıdır.
• Günlük satış raporu pakette yoktur. Bildirimler yalnız tek tek sipariş gönderimi ve başarısızlık için gider.
• Süzgeç sınırı. SQLite adaptörü teslim türü alanını doldurmaz; bu durumda süzme işlemi sorgunun içinde yapılır.
• Lisans doğrulaması. Köprü her başlangıçta lisansı doğrular. Lisans sunucusuna ulaşılamazsa son başarılı doğrulamadan sonra 72 saat çalışmaya devam eder.

Resmi API sunmayan bir sistemde oturumla çalışan bir adaptör kullanmadan önce sağlayıcınızdan izin almanızı öneririz. Bu, bağlantının sözleşmenizle uyumlu kalmasını sağlar.

Diğer Otopilot özellikleriyle nasıl birleşir?

Kurye entegrasyonu siparişin mutfaktan kapıya giden yolunu hızlandırır. Siparişin siteye gelmesi ise ayrı bir iştir. Sitenizden randevu alıyorsanız online randevu özelliği takvim, hatırlatma ve iptal düzenini panelden yönetir; ayrıntılar online randevu rehberinde yer alıyor.

Kendi sisteminizi Otopilot'a olay bazlı bağlamak isterseniz webhook entegrasyonu sayfası genel yapıyı anlatır. Telegram bildiriminin neden kendi botunuzdan gönderildiğini ve nasıl hazırlandığını Erişim Engeli ve Index Takip Botu yazısında adım adım anlattık; aynı yöntem burada da geçerlidir.

Ürünün güncel satış durumu, fiyatı ve kurulum kalemleri Kurye/Kargo Entegrasyonu ürün sayfasında yazar. Hazır paketlere uymayan bir sipariş akışınız varsa Bot Sihirbazı ile POS, kurye firması ve bildirim kanalını seçip teklif isteyebilirsiniz. Panel paketleri için fiyatlar sayfasına bakın.

Siparişi kuryeye iletmeden önce ekibinizin yeni siparişi telefonda anında görmesini istiyorsanız sipariş bildirimi rehberi Telegram, WhatsApp ve e-posta seçeneklerini anlatır.

Sık sorulan sorular

Kurulumu kim yapıyor?

Kurulumu ve firma başına yapılandırmayı ekibimiz yapar. Siz POS ve kurye hesaplarınızın erişimini destek talebi üzerinden verirsiniz. Her POS ya da kurye firması bağlantısı ayrı bir kurulum kalemidir.

Kurye firmam listede yok, yine de bağlanabilir mi?

Firmanın resmi bir API'si varsa genel http adaptörüyle bağlanması büyük olasılıkla mümkündür. Listede olmayan firmalar için kapsam teklifle çıkarılır. Talebi Bot Sihirbazı'ndan ya da destek talebinden iletebilirsiniz.

Sipariş kuryeye gitmezse ne olur?

Sipariş belirlenen sayıda yeniden denenir. Yine iletilemezse başarısız işaretlenir ve Telegram'dan "elle girin" bildirimi gelir. Bu durumda siparişi kurye paneline elle girip kayıttaki hata mesajıyla destek talebi açmanız yeterlidir.

Köprü nerede çalışır?

Ürün iki çalışma yeriyle sunulur: kurulumu ekibimizin yaptığı "Kurulumu siz yapın" seçeneği ve köprünün bizim sunucumuzda çalıştığı "Bizde çalışsın" seçeneği. Hangisinin uygun olduğu POS sisteminizin siparişi nasıl dışarı verdiğine bağlıdır. Örneğin siparişleri yalnız dükkândaki bilgisayarda bir klasöre yazan bir POS için köprünün o ağa erişebilen bir sunucuda çalışması gerekir.

Canlıya almadan önce deneyebilir miyim?

Evet. Kuru çalıştırma kipinde siparişler kuyruğa alınır ama kuryeye gönderilmez. Kayıtta hangi siparişin nasıl gönderileceğini görür, eşleştirmeden emin olduktan sonra gerçek gönderimi açarsınız.

Müşteri verileri Otopilot'a gönderiliyor mu?

Köprü kendi sunucunuza kurulduğunda müşteri adı, telefonu ve adresi yalnız o sunucuda işlenir ve yalnız sizin kurye firmanıza gönderilir; Otopilot'a giden istek lisans doğrulamasıdır. Köprünün bizim sunucumuzda çalıştığı kurulumda ise sipariş verisi aktarım için o sunucudan geçer ve yine yalnız sizin kurye firmanıza iletilir.

Kaynaklar

• MDN: SubtleCrypto.sign() ile HMAC imzası
• MDN: HTTP 401 Unauthorized
• MDN: HTTP 422 Unprocessable Content
• MDN: HTTP yeniden deneme için Retry-After başlığı
• schema.org: Order türü