# Delivery Hero — POS API Teknik Notlar

> Kaynaklar:
>
> - POS Plugin API: https://integration-middleware.stg.restaurant-partners.com/apidocs/pos-plugin-api
> - POS Middleware API: https://integration-middleware.stg.restaurant-partners.com/apidocs/pos-middleware-api
>
> **UYARI:** Yukarıdaki sayfalar JavaScript ile render edilen (Redoc/Swagger UI)
> dokümanlardır. Otomatik içerik çekimi yalnızca başlıkları döndürdü; **kesin endpoint
> yolları, request/response şemaları ve imza algoritması bu dosyada doğrulanmış
> değildir.** Uygulamaya geçmeden önce ilgili sayfalar tarayıcıda açılıp "TODO (şema)"
> olarak işaretli bölümler manuel olarak tamamlanmalıdır.

---

## 1. Yön / Mimari Farkı (önemli)

Delivery Hero entegrasyonu, projedeki mevcut **Uber Eats** entegrasyonunun **tersi**
yöndedir:

|                  | Uber Eats                                           | Delivery Hero                                                            |
| ---------------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
| Gelen sipariş    | DH/Uber bize **webhook** gönderir (biz endpoint'iz) | DH **Integration Middleware** bizim **plugin** endpoint'lerimizi çağırır |
| Kimlik doğrulama | OAuth2 (`client_credentials`)                       | Credential: **username / password / secret** (+ PGP ile teslim)          |
| Giden işlem      | Uber API'yi çağırırız (order detail, accept)        | Middleware API'yi çağırıp siparişi **accept/reject** ederiz              |

Yani iki ayrı API yüzeyi vardır:

- **POS Plugin API** → _Biz host ederiz_, DH Middleware çağırır (sipariş alma, iptal,
  voucher, ürün/kategori müsaitliği vb.).
- **POS Middleware API** → _DH host eder_, biz çağırırız (sipariş durumu accept/reject,
  vendor availability, order report).

## 2. POS Plugin API (bizim sağlayacağımız endpoint'ler)

DH Integration Middleware, sipariş yaşam döngüsünde plugin'i çağırır. Genel olarak
beklenen plugin sorumlulukları:

- Yeni siparişi alma (**receive order**) ve HTTP 2xx ile hızlıca onaylama (acknowledge).
- Sipariş iptalini alma (**cancel order**) — post-production sözleşmesinde "çalışan
  cancellation endpoint" zorunlu tutulur.
- Voucher / sipariş durum güncellemelerini alma.
- Ürün ve kategori müsaitlik güncellemelerini alma (availability).
- Plugin'in curl ile doğrulanabilir, güvenli (HTTPS + geçerli SSL) bir endpoint olması.

> Sipariş onaylandıktan (acknowledge) sonra plugin, vendor'ın siparişi karşılayıp
> karşılayamayacağını (**accept** / **reject**) POS Order Processing Service'e
> (Middleware API) bildirmek zorundadır. Kaynak: pos-plugin-api sayfası özeti.

### TODO (şema) — Plugin API

- [ ] Tam endpoint listesi ve HTTP metodları (receive / cancel / voucher / availability)
- [ ] Her endpoint için request body şeması (order payload alanları)
- [ ] Beklenen response body şeması ve durum kodları
- [ ] Plugin'e gelen isteklerin **kimlik doğrulama / imza** mekanizması
      (username/password header'ı mı, `secret` ile HMAC imza mı?)
- [ ] Zaman aşımı (acknowledge) süresi ve retry politikası

## 3. POS Middleware API (bizim çağıracağımız endpoint'ler)

- Middleware ile iletişim kurulan tüm endpoint'lere **kimlik doğrulama detayları**
  gönderilmelidir. Kaynak: pos-middleware-api sayfası özeti.
- Bilinen örnek endpoint: `POST /v2/order/status/{orderToken}` — siparişin
  accept/reject durumunu bildirmek için kullanılır.

### TODO (şema) — Middleware API

- [ ] Base URL (prod & staging)
- [ ] `POST /v2/order/status/{orderToken}` request/response şeması
- [ ] accept akışı: teslimat zamanı + vendor tarafı benzersiz sipariş kimliği formatı
      (tarih/saat formatı hatalı olursa entegrasyon reddedilir — `order_accepted`)
- [ ] reject akışı: geçerli **reject reason** listesi (`order_rejected`)
- [ ] Kimlik doğrulama başlıkları (username / password / secret kullanım şekli)
- [ ] Vendor availability (open/closed, busy, unreachable/reachable) endpoint'leri
- [ ] Order Report Service (son 24 saat) endpoint'i ve şeması

## 4. Kimlik Doğrulama / Credential

- Credential talebi için **Public PGP Key** sağlanır; DH credential'ı bu anahtarla
  şifreleyerek iletir.
- Credential üç parçadır: **Username**, **Password**, **Secret**.
- `secret`'ın imza üretiminde (HMAC) kullanılması beklenir — kesin yöntem
  swagger dokümanından doğrulanmalıdır (bkz. TODO şema).
- Plugin URL'i HTTPS + geçerli SSL sertifikası desteklemelidir.

## 5. Bu projeye entegrasyon etkisi (özet)

Mevcut `app/Services/UberEats/` deseni referans alınabilir; ana farklar:

- OAuth yerine credential + imza doğrulaması.
- **Gelen** taraf webhook değil, DH'nin çağırdığı plugin controller'ı olacaktır
  (yeni bir route grubu + controller gerekir).
- **Giden** accept/reject çağrısı için ayrı bir Middleware API istemcisi gerekir.
- `Integration` modeli ve webhook-event/idempotency desenleri yeniden kullanılabilir.

> Not (AGENTS.md): Migration'lar `admin.apper` projesinde yönetilir; bu projede
> migration oluşturulmaz ve yalnızca SELECT sorguları allowed.