Entegrasyon Dokümanı

Yemeksepeti Entegrasyon Api

Yemeksepeti ile çalışan POS sağlayıcıları platformdaki siparişlerini, menülerini ve restoranlarını yönetmelerine olanak sağlar.

Genel Bakış

Entegrasyon için kullanılabilir API'ler 2'ye ayrılmıştır;

Integration Middleware API, Plugin(POS sağlayıcı tarafından geliştirilecek) tarafından çağırılacak endpoint uçlarını temsil eder.
Plugin API, POS sağlayıcı tarafından geliştirilecek, Yemeksepeti platformundan siparişleri ve güncellemeleri almak için kullanılacak yazılımı ifade eder.

Sipariş Yönetimi

Update Order Status (POST): Siparişi kabul etme / reddetme / restorandan teslim alındı (Restoran kuryesi tarafından taşınacak ya da müşteri tarafından alınacak siparişler) olarak güncelleme.
Mark Order as Prepared (POST): Yemeksepeti kuryeleri tarafından teslim edilecek siparişlerin 'teslim alınmaya hazır' olarak güncellenmesi. Güncellemeden sonra yemeksepeti kuryesi, siparişi restorandan alacaktır.
Order Dispatch (WebHook): Yeni siparişin bildirimi.
Order Status Update (WebHook): İptal edilen siparişlerin bildirimi. (Yemeksepeti tarafından)

Katalog Yönetimi

Not: Henüz bu özellik kullanılabilir durumda değil. Temsilcinizden destek talep edebilirsiniz.

Submit Catalog (PUT): Menü ve menü öğelerinin oluşturulması, güncellenmesi ve silinmesi.
Catalog Import Log (GET): Import statüsünü öğrenme.
Update Item Availability (POST): Ürünlerin Yemeksepeti sayfasında listelenmesini açma/kapama.
Unavailable Item (GET): Listelenmeyen ürünleri almak.
Status of a Catalog Import (WebHook): Katalog import durumunun bildirimi.
Menu Import Request (WebHook): Menü import durumunun bildirimi.

Restoran Yönetimi

Update Vendor Availability (PUT): Restoranın durumunu güncelleme (Açık, kapalı, yoğunluk)
Vendor Availability (GET): Restoranın durumunu öğrenme.

Sipariş Raporu Servisi

Order IDs (GET): 24 saat içerisindeki siparişlerin ID'lerini getirir.
Order Detail (GET): Sipariş detayını getirir.

Merkezi Mutfak İçin Katalog Aktarımı

Submit Catalog for Centralized Kitchen (PUT): Merkezi bir mutfaktan(aynı lokasyondan) yönetilen restoranların menü aktarımı.

API Dokümantasyonları

Integration Middleware API Doc

POS Plugin tarafından kullanılabilir api endpointleri.

Plugin API Doc

POS Plugin tarafından çağırılan, siparişleri ve güncellemeleri almak için uygulanan API endpointleri.

Başlarken

Geliştirme sürecine başlamadan önce lütfen emin olun:

NDA sözleşmesini tamamlamalısınız. Tamamlamadıysanız Yemeksepeti ile iletişime geçin ya da formu doldurun.

https://developers.deliveryhero.com/documentation/pos.html#request-credentials

Geliştirme sürecine başlamadan Yemeksepeti Teknik Ekibi'nden onay alın.

Süreç

Entegrasyon API'lerine erişim talep edin.
Test Entegrasyonu kurun.
Geliştirme sürecine başlayın.
Yemeksepeti ile uçtan uca test gerçekleştirin.
Production entegrasyonu kurun.
Pilot restoranlar ile entegrasyonunuzu canlı ortamda kullanmaya başlayın.
Restoran sayınızı arttırın.
Entegrasyonu güncel tutun ve Yemeksepeti tarafından sağlanan yeni özelliklere uyum sağlayın.

Erişim ve Entegrasyon Konfigürasyonu

Erişim Talebi

Entegrasyon API'larına erişim sağlamak için credentials bilgilerine (kullanıcı adı ve şifre) ihtiyacınız olacak.

Credential Talebi Oluşturun.

PGP key pair oluşturun. Güvenlik amacıyla credential bilgilerini e-posta ile size göndermeden önce credential bilgisini şifrelemek için PGP anahtarınıza ihtiyacımız olacak. Buradan PGP anahtarı oluşturma aracını indirebilir ve bir anahtar çifti oluşturabilirsiniz.

https://gnupg.org/download/index.html

Formu doldurun: PGP Public anahatarınızla formu doldurun.

https://developers.deliveryhero.com/documentation/pos.html#request-credentials

Yemeksepeti ile iletişime geçin, talebinizi onaylatın.

Formu ilettikten sonra Yemeksepeti ile iletişime geçin. Talebinizi kontrol ettirip eksik bilgi olmadığından emin olun ve onaylatın.

Credential bilgilerini e-mail aracılığı ile alın.

Yemeksepeti talebinizi onayladığında, credential bilgilerinizi e-posta yoluyla alacaksınız. Ayrıca, e-postanın gelen kutusu yerine Spam klasörünüzde görünme olasılığını göz önünde bulundurarak Spam klasörünüzü kontrol edin.

PGP Key ile maili decrypt edin.

Credential bilgilerini çözümlemek için PGP private keyinizi kullanın.

Access Token alın.

Api kullanımı için ihtiyacınız olan token bilgisini Login endpointi aracılığı ile alın.

https://integration-middleware.stg.restaurant-partners.com/apidocs/pos-middleware-api#tag/Auth/operation/Login

Kurulum

Entegrasyonu, zincirleri, restoranları ve aralarındaki ilişkiyi anlama

Tanım

Restoran: Yemeksepeti'nde faaliyet gösteren tekil restoran.
Zincir: Genellikle aynı restoran adını paylaşan ancak farklı konumlarda bulunan bir veya daha fazla tedarikçiden oluşan bir restoran zinciridir.
Entegrasyon: Yemeksepeti'nde siparişleri, menüleri ve mağazaları programlı bir şekilde yönetmek amacıyla tarafınızca oluşturulan bir eklenti olarak tanımlanır. Bu eklenti, sipariş gönderme, sipariş durumu güncelleme vb. gibi bildirimleri almak için kullanılan bir temel URL içerir.
Bir entegrasyon, bir veya daha fazla zinciri içerebilir.
Bir zincir, bir veya daha fazla restoran içerebilir.
Restoranlar yalnızca tek bir benzersiz zincir ve entegrasyon altında olabilirler.

Entegrasyon aktivasyonu için Yemeksepeti ekibine aşağıdaki bilgileri sağlayın:

Entegrasyon

Text	Tanım	Örnek
Entegrasyon Adı	Entegrasyonunuza bir isim verin.	Yemeksepeti Test Entegrasyonu
Entegrasyon Kodu	Unique bir tanım verin.	yemeksepeti-test-entegrasyonu
Base Url	Api'nize ait base url bilgisini paylaşın. Bu url üzerinden sipariş bildirimi ve statü güncellemelerini alacaksınız.	https://test.integration.yemeksepeti.com/
Plugin Username	Size iletilen kullanıcı adı	yemeksepeti-test-entegrasyonu-username

Zincir

Text	Tanım	Örnek
Zincir Adı	Entegrasyonu kullanacak zincir adı	Yemeksepeti
Zincir Kodu(Chain Code)	Zincire ait unique bir kod belirleyin	yemeksepeti-chain-tr

Restoran

Test restoranı ihtiyacınız varsa Yemeksepeti Teknik Ekip'ten yardım talep edin.

Text	Tanım	Örnek
Restoran Kodu (Vendor Code)	Restoran tanımı için gerekli unique kod. Yemeksepetinden kodunuzu talep edin	ymks
Remote ID	Plugininiz ile kullanacabileceğiniz vendore ait unique id	123456

IP Address Whitelist

Integration Middleware aracılığı ile siparişleri alabilmek için aşağıdaki IP adreslerini whitelist e eklemelisiniz.

63.32.225.161
18.202.96.85
52.208.41.152

Sipariş Yönetimi

Genel Bakış

Siparişleri yönetebilmek için Order Management API'yi kullanın. İlgili methodlar aşağıda listelenmiştir.

Update Order Status (POST): Siparişi kabul etme / Siparişi reddetme / Siparişi teslim alındı olarak güncelleme.
Mark Order as Prepared (POST): Siparişi 'teslim alınmaya hazır' olarak güncelleme.
Order Dispatch (WebHook): Yeni siparişin bildirimi.
Order Status Update (WebHook): İptal edilen siparişlerin bildirimi. (Yemeksepeti tarafından)

Entegrasyon Akışını Anlamak

Direct Entegrasyon

Entegrasyon siparişleri kendi POS sistemi üzerinden yönetir. Yemeksepetine ait herhangi bir yazılım kullanılmamaktadır.

Direct integration flow

Şemada direct entegrasyon akışı verilmiştir. Siparişin nasıl iletildiğini ve sipariş karşılayan taraftaki akışı gösterir.

Müşteri Yemeksepeti platformundan entegrasyona sahip restorandan bir sipariş verir.
Integratin Middleware siparişi entegrasyon pluginine iletir.
Plugin siparişi POS altyapısına iletir.
Restoran siparişi POS sistemi üzerinden kabul edebilir. Bu sayede siparişi yazdırabilir ya da arayüzünüzde görüntüleyebilirsiniz.

Not: Otomatik onay işlevi uygulanabilir, böylece sipariş otomatik olarak tedarikçinin POS sisteminde görüntülenir.

	Direct Entegrasyon
Sipariş Yönetimi	Restoran siparişleri tamamen POS sistemi üzerinden yönetir.
Otomatik Onay	Otomatik onay akışı POS sisteminde implemente edilmeli
Plugin Geliştirme Eforu	POST Update Order Status Webhook Order Dispatch Webhook Order Status Update
Sipariş Takip Uygulamasının Yedek Olarak Kullanımı (POS sisteminde sorun olması halinde)	Pos sisteminde yaşanan bir sorun anında siparişler tekrar gönderilmeye devam eder. Yanıt alınamaması durumunda sorun aralığındaki siparişler iptal olabilir. Not: Retry policy hakkında daha fazla bilgi için. https://integration-middleware.stg.restaurant-partners.com/apidocs/pos-plugin-api#tag/Plugin-Endpoints/operation/Dispatch%20Order

Katalog Yönetimi

Not: Henüz bu özellik kullanılabilir durumda değil. Temsilcinizden destek talep edebilirsiniz.

Genel Bakış

Yemeksepeti'ndeki kataloğunuzu yönetmek için Catalog Management API'yi kullanın. İlgili methodlar aşağıda listelenmiştir.

Submit Catalog (PUT): Menü ve menü öğelerinin oluşturulması, güncellenmesi ve silinmesi.
Catalog Import Log (GET): Import statüsünü öğrenme.
Update Item Availability (POST): Ürünün listelenmesini güncelleme
Unavailable Item (GET): Listelenmeyen ürünleri almak.
Status of a Catalog Import (WebHook): Katalog import durumunun bildirimi.
Menu Import Request (WebHook): Menü import durumunun bildirimi.

Catalog Import Akışı

Catalog import flow

Şemada Catalog Import akışı gösterilmiştir.

Plugin, Submit Catalog (PUT) methodunu kullanarak katalogu Integration Middleware'a iletir.
Integration Middleware validasyon kontrolü sonrası onay bilgisini döner.
Integration Middleware onaylanan katalog, Yemeksepeti Platform'una iletir ve müşteri tarafından görüntülenebilir duruma gelir. Bu süreç asenkron gerçekleşir.
Eğer katalogu iletirken callback url eklediyseniz katalog aktarım durumunu Status of Catalog Import (Webhook) ile plugininize iletir.
Opsiyonel olarak, Catalog Import Log (GET) ile aktarım durumunu sorgulayabilirsiniz.

Restoran Yönetimi

Genel Bakış

Restoran erişimini yönetmek için Store Management API'yi kullanabilirsiniz. Kullanılabilir methodlar aşağıda iletilmiştir.

Update Vendor Availability (PUT): Restoranın durumunu güncelleme (Açık, kapalı, yoğunluk)
Vendor Availability (GET): Restoranın durumunu öğrenme.

Sipariş Raporu Servisi

Genel Bakış

Tamamlanan siparişleri almak için Sipariş Raporu Servisi (Order Report Service) kullanın. Kullanılabilir methodlar aşağıda iletilmiştir.

Order IDs (GET): 24 saat içerisindeki siparişlerin ID'lerini getirir.
Order Detail (GET): Sipariş detayını getirir.

Terminoloji

POS Clients: Zincirler ya da POS sağlayıcılar (Entegrasyon firmaları); Siparişleri POS sistemine aktarmak isteyen client.
Restoranlar(Vendors): Siparişin hazırlandığı fiziksel konum.
POS System: Entegrasyon firmalarının siparişleri aldıkları ve işledikleri yazılım.
Integration Middleware:Yemeksepeti Sipariş İletim altyapısı. Siparişleri POS sistemine iletmekle görevli.
Plugin: Integration Middleware ile POS sistemi arasındaki adaptör. (Webhook)
Platform Vendor ID: Yemeksepeti tarafındaki restoran kimliği. Vendor Code olarakta adlandırılır.
Remote ID: Plugin tarafındaki restoran kimliği.

Sık Sorulan Sorular

SSL sertifikası neden gerekli?

Plugin ile Integration Middleware arasındaki iletişimin güvenliği için SSL sertifikasına ihtiyaç duyulur.
Siparişleri alabilmek için hangi IP adreslerini whiteliste almalıyım?

Aşağıdaki IP adreslerini whitelistinize eklemelisiniz.
63.32.225.161
18.202.96.85
52.208.41.152

URL port numarası içerebilir mi?

Evet

POS sistemindeki ürünler ile Yemeksepeti ürünlerini nasıl mapleyebilirim?

Katalog yönetiminde Submit Catalog (PUT) ile ürünlerinizi mapleyebilirsiniz. Bu eklentiyi kullanmak istemiyorsanız manuel mapleme ile ilgili Yemeksepeti temsilciniz ile görüşün.

Submit Catalog(PUT) methodunda image requirementlarınız neler?

Requirement detayları için:
https://integration-middleware.stg.restaurant-partners.com/apidocs/pos-middleware-api#tag/Catalog-Import/Implementation-Details

Canlıya Geçiş Sonrası

Plugin bakımlarını Yemeksepeti'ne en az 24 saat önce mail aracılığıyla bildirmelisiniz. Mailinizde çalışmanızın detaylarını ve varsa tahmini kesinti süresini belirten ingilizce olarak pos-tr-support@deliveryhero.com mail adresine iletmelisiniz.
Plugin bakımında sorumlu kişilerin listesini iletin. Plugin ile ilgili teknik bir sorun olduğunda iletişime geçilmesi için bu bilginin iletimi önemli.
Plugin ile ilgili bir sorun anında yetkili kişilere ulaşılamazsa restoranlarınız sipariş alımına durdurulabilir. Yetkililer ile görüşüldükten ve sorun giderildikten sonra sipariş alımınız tekrar aktif hale getirilecektir.
Bazı entegrasyon özellikleriniz ya da tüm entegrasyonunuz yükümlülükler yerine getirilmediği takdirde devre dışı bırakılabilir.
Bazı yaygın eksik kullanım örnekleri:

Direct Entegrasyon kullanan entegrasyonlar, bu bilgiyi Order Status Update (Webhook) üzerinden alacakları geliştirmeyi yapmalı
Bir siparişi reddederken uygun bir reddetme nedeni sağlamamak. Tüm olası nedenleri görmek için Update Order Status (POST)'un body şemasında order_rejected'e tıklayın.
Siparişi yanlış biçimlendirilmiş bir saat ile kabul etmek. Biçimlendirilmiş tarih saatini görmek için Update Order Status (POST)'un body şemasında order_accepted'e tıklayın.