POST /dynamicqr — Dinamik QR Kod Oluşturma

📋 Genel Bilgi

Dinamik QR kod oluşturur. config gönderilirse base64 SVG QR, gönderilmezse sadece link döner.

Base URL: {{url}}/dynamicqr Method: POST Content-Type: application/json

🔐 Headers

Header	Value
Authorization	`Bearer {{masked_jwt_8}}`
Content-Type	`application/json`

📥 Request Body

{
  "terminal_code": "TERM-003",
  "store_code": "mobildev-mq",
  "redirectUri": "https://example.com/thank-you",
  "metadata": {
    "İşlem ID": "Random İşlem ID",
    "Müşteri Sadakat": "sadakat bilgileri"
  },
  "config": {
    "colorDark": "#000000",
    "colorLight": "#ffffff",
    "size": 300,
    "errorCorrection": "M"
  },
  "expireAt": ""
}

Parametreler

Alan	Tip	Zorunlu	Açıklama	Örnek
`terminal_code`	string	✅	Terminal kodu	`"TERM-003"`
`store_code`	string	✅	Mağaza kodu	`"mobildev-mq"`
`redirectUri`	string	✅	QR tarandıktan sonra yönlendirilecek URL (thank-you sayfası)	`"https://example.com/thank-you"`
`metadata`	object	❌	Müşterinin dinamik olarak göstermek istediği QR linkleri / işlem bilgileri	-
`config.colorDark`	string	❌	QR koyu renk (hex)	`"#000000"`
`config.colorLight`	string	❌	QR açık renk (hex)	`"#ffffff"`
`config.size`	integer	❌	QR boyutu (px)	`300`
`config.errorCorrection`	string	❌	Hata düzeltme seviyesi (`L`, `M`, `Q`, `H`)	`"M"`
`expireAt`	string	❌	Son kullanma tarihi (ISO 8601)	`""`

🔄 Akış Diyagramı (Dynamic QR — Uzaktan Doğrulama)

Adım Açıklamaları:

Adım	Taraf	İşlem	Açıklama
1	Terminal → API	POST `/dynamicqr`	Mağaza terminali, doğrulama için dinamik QR oluşturur. `redirectUri`, `metadata` (randevu tarihi, servis bilgisi vb.) gönderilir.
2	API → Terminal	QR kod + URL döner	Benzersiz `code`, `url` (`https://wentro.net/dq/{code}`) ve isteğe bağlı `base64` SVG QR döner.
3	Terminal → Müşteri	QR göster / link gönder	QR mağazada ekranda gösterilir veya müşteriye SMS/e-posta/WhatsApp ile link gönderilir.
4	Müşteri → QR	QR tarar / linki açar	Son kullanıcı, oluşturulan QR kodu tarar veya gönderilen `https://wentro.net/dq/{code}` linkini açar.
5	Müşteri → API	Doğrulama yapılır	Link açıldığında müşteri passkey ile doğrulama ekranı görür. Onay verildiğinde doğrulama tamamlanır.
6	API → Müşteri	`redirectUri`'ye yönlendirilir	Doğrulama başarılı olduğunda, istek sırasında belirlenen `redirectUri` (thank-you sayfası) kullanılarak müşteri yönlendirilir.
7	Thank-You → Müşteri	Sayfa gösterilir	Son kullanıcı teşekkür/sonuç sayfasını görür. İşlem tamamlanır.

Kullanım Senaryoları:

Senaryo	Açıklama
Randevu Onayı	Müşteri randevu tarihi, servis bilgisi ve tutarı metadata'ya ekler → QR oluşturur → müşteri linki açar ve onay verir.
İşlem Bazı Doğrulama	Ödeme/transfer işleminden önce "Ek Onay Gerekiyor" uyarısı verilir → Dynamic QR ile son kullanıcıdan anlık onay alınır.
KVKK / EK Onayı	Müşterinin KVKK veya Ek Onay (SMS, call, email) onayları alınmak istendiğinde kullanılır.

✅ Response — 200 OK

{
  "code": "0OTd490VcI",
  "url": "https://wentro.net/dq/0OTd490VcI",
  "base64": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMDAiIGhlaWdodD0iMzAwIiB2aWV3Qm94PSIwIDAgMzAwIDMwMCI+CiAgPHJlY3Qgd2lkdGg9IjMwMCIgaGVpZ2h0PSIzMDAiIGZpbGw9IiNmZmZmZmYiLz4KICA8cmVjdCB4PSIzNy4wIiB5PSIzNy4wIiB3aWR0aD0iMS4wIiBoZWlnaHQ9IjEuMCIgZmlsbD0iIzAwMDAwMCIvPgogIDxyZWN0IHg9IjM3LjAiIHk9IjM4LjAiIHdpZHRoPSIxLjAiIGhlaWdodD0iMS4wIiBmaWxsPSIjMDAwMDAwIi8+CiAgPHJlY3QgeD0iMjYxLjAiIHk9IjI2MC4wIiB3aWR0aD0iMS4wIiBoZWlnaHQ9IjEuMCIgZmlsbD0iIzAwMDAwMCIvPgogIDxyZWN0IHg9IjI2MS4wIiB5PSIyNjEuMCIgd2lkdGg9IjEuMCIgaGVpZ2h0PSIxLjAiIGZpbGw9IiMwMDAwMDAiLz4KPC9zdmc+"
}

Response Alanları

Alan	Tip	Açıklama
`code`	string	QR kod benzersiz kodu (10 karakter)
`url`	string	QR kod URL'si (`https://wentro.net/dq/{code}`)
`base64`	string	Base64 encoded SVG QR kod (sadece `config` gönderildiyse)

❌ Error Responses

Tüm hata yanıtları aşağıdaki formatta döner:

{
  "Response": {
    "code": 4003,
    "description": "Either store_code or terminal_code must be set"
  },
  "Success": false
}

HTTP	code	Enum	description	Ne Zaman Oluşur
400	4003	`StoreOrTerminalCodeRequired`	Either store_code or terminal_code must be set	`store_code` ve `terminal_code` alanlarının ikisi de gönderilmemiş, ya da ikisi de boş string olarak gönderilmiş
400	4004	`QrExpirationDatePast`	QR expiration date is in the past	`expiresAt` gönderildiğinde, `UnixTime.getInstance().before(this.expiresAt)` koşulu sağlanırsa
400	4005	`QrExpirationDateTooFar`	QR code expiration date can be a maximum of 72 hours	`expiresAt` gönderildiğinde, `UnixTime.getInstance().addDate(3).after(this.expiresAt)` koşulu sağlanırsa
500	4001	`DynamicQrInsertError`	An error occurred while creating the dynamic QR code	`INSERT` sorgusu veritabanı seviyesinde başarısız olduğunda (örn. constraint ihlali, bağlantı hatası) fırlatılır
400	3001	`StoreCodeInvalid`	Invalid store code	`CacheContainer.getInstance().checkStoreBy(companyId, storeCode)` çağrısında, gönderilen `store_code` sisteme kayıtlı bir mağazaya karşılık gelmiyorsa

Örnek — 400 Store/Terminal Code Required

{
  "Response": {
    "code": 4003,
    "description": "Either store_code or terminal_code must be set"
  },
  "Success": false
}

Örnek — 400 Expiration Date Errors

{
  "Response": {
    "code": 4004,
    "description": "QR expiration date is in the past"
  },
  "Success": false
}

{
  "Response": {
    "code": 4005,
    "description": "QR code expiration date can be a maximum of 72 hours"
  },
  "Success": false
}

Örnek — 400 Invalid Store Code

{
  "Response": {
    "code": 3001,
    "description": "Invalid store code"
  },
  "Success": false
}

Örnek — 500 Insert Error

{
  "Response": {
    "code": 4001,
    "description": "An error occurred while creating the dynamic QR code"
  },
  "Success": false
}

📝 Notlar

Amaç: Dynamic QR, son kullanıcıdan uzaktan işlem bazında onay almak için kullanılır. Mağazada değil, müşterinin kendi cihazından doğrulama yapılır.
config gönderilmezse sadece link döner, base64 SVG QR oluşturulmaz.
QR kod tek kullanımlık olabilir (maxScans: 1). Bir kez tarandıktan sonra scanLimitReached: true olur ve bir daha kullanılamaz.
QR tarandıktan veya link açıldıktan sonra müşteri passkey doğrulama ekranı görür → onay verir → redirectUri'ye yönlendirilir.
Metadata alanına istediğiniz dinamik verileri ekleyebilirsiniz (randevu tarihi, servis bilgisi, tutar vb.).
expireAt boş bırakılırsa sistem varsayılan süreyi kullanır.
Hata response'larındaki code alanı AppError enum'undaki uygulama-içi hata kodudur (Response.code); tüm hata gövdesi Response adlı bir alt obje içinde döner, en dışta ayrıca Success: false alanı bulunur.

📋 Genel Bilgi​

🔐 Headers​

📥 Request Body​

Parametreler​

🔄 Akış Diyagramı (Dynamic QR — Uzaktan Doğrulama)​

✅ Response — 200 OK​

Response Alanları​

❌ Error Responses​

Örnek — 400 Store/Terminal Code Required​

Örnek — 400 Expiration Date Errors​

Örnek — 400 Invalid Store Code​

Örnek — 500 Insert Error​

📝 Notlar​