Lead - Başvuru Oluşturma
Ödeal'da bir üye işyeri oluşturmak ve oluşturulan üye iş yerine bir terminal tanımlayabilmek için kullanılan, POST metoduyla çalışan servistir.
Servise iletilen isteğin başarılı olması durumunda, servis registerRefCode değeri döndürür. registerRefCode değeri Ödeal üzerinde oluşan Başvuru ID'sini temsil etmektedir. POST isteği başarısız olduğunda hata kodu ve mesajı response çıktısında görüntülenecektir.
Kanal Bazlı Zorunluluk:
mobilealanı tüm kanallar için zorunludur. Diğer alanların zorunluluk durumu,optionalFieldsiçindeki hangi key'lerin tanımlı olduğu ve validasyon kuralları iş ortağı özelinde kanal bazlı DB konfigürasyonuyla belirlenir. Kendi kanalınıza ait kurallara ulaşmak için Ödeal entegrasyon ekibiyle koordine edin.
Register servisinden farklı olarak bir başvuru için bir terminal talebine karşılık gelmektedir. Bir üye iş yeri için birden fazla terminal talebinde bulunmak istendiğinde Register servisi kullanılmalıdır.
Alan Listesi
Üst Seviye Alanlar
| Alan | Tür | Zorunluluk | Format / Validasyon | Açıklama | Örnek |
|---|---|---|---|---|---|
firstName | string | Kanala göre* | Maks. 100 karakter | Yetkili adı | "Ahmet" |
lastName | string | Kanala göre* | Maks. 100 karakter | Yetkili soyadı | "Yılmaz" |
tcNumber | string | Kanala göre* | Tam olarak 11 rakam | TC Kimlik Numarası | "11111111111" |
taxNumber | string | Kanala göre* | 10 veya 11 rakam | Vergi numarası | "2222222222" |
mobile | string | Zorunlu | 10 rakam, 5XXXXXXXXX formatı (başında 0 yok) | Cep telefonu numarası | "5321234567" |
owner | string | Opsiyonel | — | Başvuruyu oluşturan temsilci tanımlayıcısı | "satis-rep-01" |
optionalFields | object | Opsiyonel | Key-value çiftleri (tüm değerler string) | Kanala özel ek bilgiler | (aşağıya bakın) |
* Kanal Bazlı Zorunluluk:
firstName,lastName,tcNumber,taxNumberalanlarının zorunlu/opsiyonel olması kanal konfigürasyonunda belirlenir. Bazı kanallarda bu alanlardan biri veya birkaçı zorunlu olabilir.
optionalFields Alanları
optionalFields nesnesi, iş ortağına özel alanları içeren bir key-value haritasıdır. Tüm değerler string tipindedir. Hangi key'lerin tanımlı olduğu ve bunların zorunlu/opsiyonel olduğu kanal bazlı yapılandırılmaktadır.
| Key | Tür | Alabileceği Değerler | Validasyon | Açıklama | Örnek |
|---|---|---|---|---|---|
companyTitle | string | Serbest metin | — | Firma / tabela adı | "ABC Ticaret Ltd." |
businessType | string | "INDIVIDUAL", "CORPORATE" | Yalnızca bu iki değer | İşyeri türü (INDIVIDUAL = şahıs, CORPORATE = tüzel) | "CORPORATE" |
mccCode | string | 4 haneli sayısal kod | — | Merchant Category Code | "5411" |
posInstallmentType | string | "Tek Çekim", "Taksitli" | — | POS taksit yapılandırması | "Tek Çekim" |
iban | string | TR + 24 rakam (toplam 26 karakter) | TR ile başlamalı, 26 hane | İşyeri IBAN numarası | "TR200058307462136019246697" |
setupCity | string | Büyük/küçük harf duyarlı il adı | Ödeal il kaydında olmalı | Cihaz kurulum ili | "İstanbul" |
setupTown | string | Büyük/küçük harf duyarlı ilçe adı | İl ile tutarlı olmalı | Cihaz kurulum ilçesi | "Kadıköy" |
setupAddress | string | Serbest metin | — | Cihaz kurulum adresi | "Moda Cad. No:5 Kadıköy/İstanbul" |
terminalSerialNumber | string | Serbest metin | — | Terminal mali seri numarası (POS tanımı için) | "PAX721000018" |
routingModel | string | "MODEL0", "MODEL1", "MODEL2" | Kanal kısıtlaması geçerli | İşlem yönlendirme modeli | "MODEL1" |
salesType | string | "EDOC_POS", "PHY_POS", "SanalPOS", "CeptePOS" | — | Satış / hizmet türü | "EDOC_POS" |
cashRegisterType | string | Kanal konfigürasyonuna bağlı | Kanal kısıtlaması geçerli | Cihaz modeli | "A910" |
refundType | string | "Iban", "Odeal Kart" | — | İade / geri ödeme türü. Seçime göre ek alanlar zorunlu olur | "Iban" |
campaign | string | Serbest metin | refundType = "Iban" ise zorunlu | Kampanya kodu | "2.99" |
cardType | string | Serbest metin | refundType = "Odeal Kart" ise zorunlu | Kart türü | — |
cardDeliveryCity | string | Büyük/küçük harf duyarlı il adı | refundType = "Odeal Kart" ise zorunlu | Kart teslimat ili | "İstanbul" |
cardDeliveryTown | string | Büyük/küçük harf duyarlı ilçe adı | refundType = "Odeal Kart" ise zorunlu | Kart teslimat ilçesi | "Kadıköy" |
cardDeliveryAddress | string | Serbest metin | refundType = "Odeal Kart" ise zorunlu | Kart teslimat adresi | "Moda Cad. No:5" |
personReceivingDevice | string | Serbest metin | — | Cihazı teslim alacak kişi | "Ahmet Yılmaz" |
tcknOnCard | string | 11 rakam | refundType = "Odeal Kart" ise zorunlu | Kart üzerindeki TCKN | "11111111111" |
nameOnCard | string | Serbest metin | refundType = "Odeal Kart" ise zorunlu | Kart üzerindeki ad | "Ahmet" |
lastNameOnCard | string | Serbest metin | refundType = "Odeal Kart" ise zorunlu | Kart üzerindeki soyad | "Yılmaz" |
birthDateOnCard | string | ISO 8601 tarih-saat | refundType = "Odeal Kart" ise zorunlu | Kart sahibi doğum tarihi | "1990-05-15" |
phoneNumberOnCard | string | Serbest metin | refundType = "Odeal Kart" ise zorunlu | Kart sahibi telefon numarası | "5321234567" |
KANAL KISITLAMALARI
routingModel ve cashRegisterType alanları için izin verilen değerler iş ortağı kanalına göre kısıtlanmaktadır. Kanal dışı bir değer gönderildiğinde validasyon hatası döner.
Örneğin, kanalınız yalnızca A910 ve A920Pro modellerini destekliyorsa D230 gönderildiğinde şu hata alınır:
"Girmiş olduğunuz cashRegisterType alan değeri geçersiz. İzin verilen değerler: [A910, A920Pro]."Edge Case'ler ve Özel Davranışlar
refundType Koşullu Alanlar
refundType değerine göre ek alanlar zorunlu hale gelir:
refundType değeri | Zorunlu olan ek alanlar |
|---|---|
"Iban" | campaign |
"Odeal Kart" | cardType, cardDeliveryCity, cardDeliveryTown, cardDeliveryAddress, tcknOnCard, nameOnCard, lastNameOnCard, birthDateOnCard, phoneNumberOnCard |
optionalFields Alanı Gönderilmezse Ne Olur?
Kanal konfigürasyonunda tanımlı olan bir optionalFields key'i, request payload'ında hiç gönderilmezse, bu alanın kaydı Kiva sisteminde "İş Ortağı Özel Değer" sayfasında boş/tanımsız olarak görünür.
ÖNEMLİ DAVRANIM
Bir alanı optionalFields içine yazmamak, Kiva'da o alanın tamamen gizlenmesi anlamına gelmez. Kanalda tanımlı alanlar, değer gönderilmese dahi Kiva "İş Ortağı Özel Değer" sayfasında listelenir.
| Durum | Kiva "İş Ortağı Özel Değer" Sayfası |
|---|---|
Alan gönderildi (optionalFields içinde değer mevcut) | Alan adı ve değeri görünür |
| Alan gönderilmedi (ama kanalda tanımlı) | Alan adı görünür, değer boş |
| Alan kanal konfigürasyonunda tanımlı değil | Alan hiç görünmez |
Payload Örnekleri
Minimal Payload — Yalnızca Zorunlu Alan
{
"mobile": "5555555555"
}Full Payload — Tüm Alanlar
{
"firstName": "Ahmet",
"lastName": "Yılmaz",
"tcNumber": "11111111111",
"mobile": "5555555555",
"taxNumber": "2222222222",
"owner": "satis-temsilcisi-01",
"optionalFields": {
"companyTitle": "Yılmaz Ticaret Ltd.",
"businessType": "CORPORATE",
"mccCode": "5411",
"posInstallmentType": "Tek Çekim",
"iban": "TR200058307462136019246697",
"setupCity": "İstanbul",
"setupTown": "Kadıköy",
"setupAddress": "Moda Cad. No:5 Kadıköy/İstanbul",
"terminalSerialNumber": "PAX721000018",
"routingModel": "MODEL1",
"salesType": "EDOC_POS",
"cashRegisterType": "A910"
}
}Hatalı Payload — Geçersiz cashRegisterType
{
"mobile": "5555555555",
"optionalFields": {
"cashRegisterType": "D230"
}
}Response (400):
{
"status": false,
"message": "Alan ön kontrolleri başarısız",
"errors": [
"Girmiş olduğunuz cashRegisterType alan değeri geçersiz. İzin verilen değerler: [A910, A920Pro]."
]
}Hatalı Payload — Zorunlu Alan Eksik (mobile yok)
{
"firstName": "Ahmet",
"lastName": "Yılmaz",
"tcNumber": "11111111111"
}Response (400):
{
"status": false,
"message": "Alan ön kontrolleri başarısız",
"errors": [
"mobile alanı boş bırakılamaz"
]
}Response Örnekleri
Başarılı (200)
Request
{
"firstName": "Test",
"lastName": "Test",
"tcNumber": "11111111111",
"mobile": "5555555555",
"taxNumber": "2222222222",
"optionalFields": {
"companyTitle": "Tabela İsmi",
"businessType": "CORPORATE",
"mccCode": "3000",
"posInstallmentType": "Tek Çekim",
"iban": "TR200058307462136019246697",
"setupCity": "İstanbul",
"setupTown": "Kadıköy",
"setupAddress": "Kadıköy/İstanbul",
"terminalSerialNumber": "PAX721000018",
"routingModel": "MODEL1",
"salesType": "EDOC_POS",
"cashRegisterType": "A910S"
}
}Response
{
"status": true,
"data": {
"registerRefCode": "22820cf7-40f4-4a14-9845-46f94bd5082c"
}
}Başarısız (400)
Request
{
"firstName": "Test",
"lastName": "Test",
"tcNumber": "11111111111",
"mobile": "5555555555",
"taxNumber": "2222222222",
"optionalFields": {
"cashRegisterType": "D230"
}
}Response
{
"status": false,
"message": "Alan ön kontrolleri başarısız",
"errors": [
"Girmiş olduğunuz cashRegisterType alan değeri geçersiz. İzin verilen değerler: [A910, A920Pro]."
]
}