GMU

Giriş

GMU Android Sdk ve GMU Backoffice kullanımları için yapılması gereken adımlar aşağıda anlatılmıştır. Herhangi bir sorunuz olması durumunda Protein ekibi ile iletişime geçebilirsiniz.

GMU sisteminin kullanılabilmesi için öncelikle GMU sisteminde işletmeye ait bir Tenant, Store ve Device tanımlarının yapılması gerekmektedir. Aşağıda bu tanımlamaların yapılması için kullanılması gereken metotları ve akışı bulabilirsiniz.

Servis API dökümanından detayları inceleyebilirsiniz.

Yararlı Linkler

• Gmu Backoffice API Swagger(Test)

• Gmu Integration API Swagger(Test)

• Gmu Client API Swagger(Test)

• Gmu Backoffice (Test)

Not

Her bir endpointte girilmesi gereken zorunlu alanları görmek için, Swagger dokümanında ilgili endpoint altında yer alan Schema kısmına bakılmalıdır.

Not

Eğer GMUPOS uygulaması kullanılıyorsa entegrasyon GMUPOS servisleri üzerinden yapılmalıdır!

Onboarding Adımları

1. Onboarding adımlarını Integration API kullanarak gerçekleştirebilirsiniz.

   -> POST-/integrationapi/v2/Auth/AuthorizeIntegrationUser endpointi ile firmaya paylaşılan Entegrasyon kullanıcısı bilgileri kullanılarak Authorize olunur.

   • Request body içerisinde yer alan tenantId silinmelidir.

2. Alınan JWT Token ile birlikte Tenant oluşturma adımı takip edilir.

   -> POST-/integrationapi/v2/User/CustomerByIntegration endpointi ile birlikte Tenant oluşturulur. Tenant ile beraber Store da aynı istekte oluşturulmak isteniyorsa request body içerisindeki "store" alanı doldurulur.

   - İstek atılırken eklenen request body içerisinde, yer alan email ve password parametreleri ile, oluşturulan bu tenant verisine ait bir kullanıcı oluşturularak Backoffice ortamına giriş sağlanabilir.
   
   - Response body içerisinde yer alan tenantId bilgisi bir sonraki adımdaki Authorize işleminde kullanılmak üzere saklanmalıdır.
   
   - Eğer store burada oluşturulmak istenmiyorsa request body içerisindeki store alanları silinip istek gönderilir. Store oluşturmak için bir sonraki adım takip edilir.

3. Bir önceki adımda oluşturulan tenant'ın id bilgisi response body'den alınarak 1. adım tekrar edilir. Böylece, devam eden adımlarda yapılacak tüm işlemler ilgili tenant üzerinden ilerleyecektir.

   • İlk adımda silinen tenantId bu istekte doldurulmalıdır.

4. Alınan JWT Token ile birlikte Store oluşturma adımı takip edilir.

   -> POST-/integrationapi/v2/Store/ByIntegration endpointi ile store oluşturulur.

   • deviceApiAccessUsername, deviceApiAccessPassword alanları android pos clientların authorize olması için gerekli kullanıcı adı ve şifreyi ifade etmektedir. Bir store'a bağlı tüm cihazlar bu bilgilerle authorize olur. Bu bilgiler, Android Sdk login metodunda kullanıcı bilgisi olarak 7. adımda kullanılacaktır.

   • Response body içerisinde yer alan id bilgisi 5. adımdaki cihaz oluşturma aşamasında kullanılmak üzere saklanmalıdır.

5. -> POST-/integrationapi/v2/Device endpointi ile cihaz oluşturulur.

   • Bir önceki adımda alınan id request body içerisindeki storeId alanına girilmelidir.
   • Response body içerisinde dönen id bilgisi 7. adımda deviceId alanında kullanılacaktır.

6. Android Sdk'yı kullanmaya başlamadan önceki son adım olarak, GMU backende App Version tanımlama işlemi yapılmalıdır. Bu işlemi, Backoffice API'yi kullanarak gerçekleştirebilirsiniz.

   -> POST /boapi/v2/Auth/Authorize endpointinden Protein ekibi tarafından iletilecek support kullanıcı bilgileri ile JWT token alınır.

   -> POST /boapi/v2/AppVersionInfo endpointine bir önceki adımda alınan token ile çağrı yapılır. Request body parametre açıklamaları:

   • appVersion = 1.0.0, appType = 2 verilmelidir. Bu değerler sabittir farklı değerler girilmemelidir.
   • appUniqueId ve appPublicKey parametrelerine, Android Sdk'yı kullanacağınız uygulamanın applicationId'si verilmelidir.
   • htmlContent parametresi ilgili sürümün html formatında notlarını içerir.

   Örnek request:

   {
    "appVersion": "1.0.0",
    "appPublicKey": "com.protein.poc.app",
    "appUniqueId": "com.protein.poc.app",
    "releaseDate": "2022-11-22T06:11:23.362Z",
    "approvedBy": "Fatih Çelik",
    "appType": 2,
    "htmlContent": "<html><body>Notlar</body></html>"
   }

7. Yukarıdaki adımlar ile, Android Sdk metotlarından login ve setGmuParameters içinde verilmesi gereken önemli parametreler elde edildi.

   • login -> username ve password oluşturuldu.(deviceApiAccessUsername, deviceApiAccessPassword)
   • setGmuParameters -> deviceId ve applicationId oluşturuldu.

   Detaylı Sdk method açıklamaları için GMU Module Sample Dökümantasyonunu inceleyebilirsiniz.

sequenceDiagram Admin ->> GMU: Authentication (Admin Username Password) GMU ->> Admin: Admin Token Admin ->> GMU: Create Customer GMU ->> Admin: Tenant Id ve Tenant Token(Sadece ilgili Tenant için kullanılabilir) Admin ->> GMU: Customer Autentication (Admin Username ve Password(Tenant Id)) GMU ->> Admin: Customer Token Admin ->> GMU: Create Store GMU ->> Admin: StoreID ve Device User Id Admin ->> GMU: Register Device (Store Id ve Serial Number) GMU ->> Admin: Device Id Device ->> GMU: Autorize (GMU device username ve password) GMU ->> Device: Token ve Refresh Token

Onboarding Servislerinde Kullanılan Parametreler ve Açıklamaları

Onboarding akışını yürütürken ihtiyaç duyulan ilgili servisler içindeki parametreler ve açıklamaları aşağıda belirtilmiştir.

Servis	Değişken	Tür	Açıklama	Min	Max	Zorunluluk
Tenant	email	string	Yönetici e-posta adresi	1	320	Zorunlu
	password	string	Yönetici şifresi	6	60	Zorunlu
	firstName	string	Yönetici adı	2	50	Zorunlu
	lastName	string	Yönetici soyadı	2	50	Zorunlu
	phoneNumber	string	Yönetici telefon numarası	10	13	Opsiyonel
	languageId	integer	Kullanıcının dili	-	-	Zorunlu
	companyName	string	İşletme adı	2	200	Zorunlu
	companyPhoneNumber	string	İşletme telefon numarası	10	13	Opsiyonel
	companyAddress	string	İşletme adresi	2	250	Opsiyonel
	ownerProductId	integer	Müşteri ThirdParty bir uygulama ile kaydolduysa bu uygulamayı göstermektedir	-	-	Opsiyonel
	tenantIntegrationId	string	Eğer tenant bir entegrasyon vasıtası ile açılmışsa tenantı açan taraftaki Id'si	-	100	Opsiyonel
	alternateId	string	IntegrationId'ye alternatif	-	100	Opsiyonel
	tenantOwner	string	Tenant Owner (Bayi)'nin ismi	-	-	Opsiyonel
Store	name	string	Şube adı	2	200	Zorunlu
	taxOffice	string	Vergi dairesi	2	100	Zorunlu
	website	string	Websitesi	2	150	Opsiyonel
	email	string	E-posta adresi	-	320	Opsiyonel
	phoneNumber	string	Telefon numarası	10	13	Opsiyonel
	fax	string	Fax numarası	10	13	Opsiyonel
	room	string	Daire numarası	1	5	Opsiyonel
	streetName	string	Sokak adı	2	250	Opsiyonel
	buildingName	string	Apartman	2	50	Opsiyonel
	buildingNumber	string	Bina numarası	1	5	Opsiyonel
	citySubdivisionName	string	İlçe	2	50	Opsiyonel
	cityName	string	Şehir	3	30	Zorunlu
	postalCode	string	Posta kodu	5	5	Opsiyonel
	countryName	string	Ülke	3	30	Zorunlu
	postalCode	string	Posta kodu	5	5	Opsiyonel
	tradeRegisterNo	string	Ticaret sicil numarası	0	12	Opsiyonel (Ticaret Sicil Numarası veya MERSIS alanlarından birinin doldurulması zorunludur
	mersisNo	string	MERSIS numarası	0	16	Opsiyonel (Ticaret Sicil Numarası veya MERSIS alanlarından birinin doldurulması zorunludur
	emailServiceProductId	integer	E-Posta gönderim servisi plugin Id	-	-	Opsiyonel
	accommodationTaxEnabled	boolean	Konaklama vergisinin aktif olup olmadığı bilgisi (Varsayılan false)	-	-	Opsiyonel
	accommodationTaxEnabled	boolean	Ticari Fatura desteğinin aktif olup olmadığı bilgisi (Varsayılan false)	-	-	Opsiyonel
	sendEDocumentEmailCopyTo	string	Müşteriye gidecek fatura e-postalarının bir kopyasının da üye işyerine gitmesi isteniyorsa burada e-posta adresi verilir	-	-	Opsiyonel
	docType	integer	Belge tipi (1= EInvoice 2= EArchive 4= Paper 5= EDespatch 7= Esmm 8= ECheck 9= NonFinancialSlip)	-	-	Zorunlu
	gbAlias	string	Gönderici birim etiketi	-	128	Opsiyonel
	integratorProductId	integer	Entegratör plugin Id	-	-	Zorunlu
	integratorUid	string	Entegratör kullanıcı adı	-	256	Opsiyonel
	integratorPwd	string	Entegratör şifresi	-	512	Opsiyonel
	integratorOptions	string	Entegratör ek bilgi (KASA, SUBE vb.)	-	-	Opsiyonel
	xsltFileBase64	string	E-belgeler için dükkana özel fatura xslt şablonu. Verilmezse varsayılan şablon kullanılır	-	-	Opsiyonel
	xsltLogoFileBase64	string	E-belgeler için varsa dükkana özel fatura logosu	-	-	Opsiyonel
	xsltFooterFileBase64	string	E-belgeler için varsa dükkana özel fatura altında yer alacak html şablon	-	-	Opsiyonel
	xsltSignatureFileBase64	string	E-Belgeler için varsa firmaya özel ıslak imza (resim olarak)	-	-	Opsiyonel
	languageId	integer	Bu ayarların hangi dil için yapıldığı	-	-	Opsiyonel
	emailTemplateKey	string	Doküman e-posta şablon Id'si	-	-	Opsiyonel
	cancelEmailTemplateKey	string	İptal belgesi e-posta şablon Id'si	-	-	Opsiyonel
	emailSubject	string	E-posta konusu metni	-	-	Opsiyonel
	emailingInvoiceAttachmentType	integer	Pdf= 1, Html= 2 (E-posta gönderimini GMU yapacaksa fatura e-postaya html olarak mı pdf olarak mı eklenecek bilgisi)	-	-	Opsiyonel
	taxNo	string	VKN/TCKN bilgisi	10	11	Zorunlu
	integrationId	string	Eğer dükkan bir entegrasyon vasıtası ile açılmışsa tenantı açan taraftaki Id'si	-	100	Opsiyonel
	alternateId	string	IntegrationId'ye alternatif	-	100	Opsiyonel
	deviceApiAccessUsername	string	Dükkana ait cihazlara giriş yapacak kullanıcının adı	3	254	Zorunlu
	deviceApiAccessPassword	string	Dükkana ait cihazlara giriş yapacak kullanıcının şifresi	6	60	Zorunlu
Device	serialNumber	string	Benzersiz cihaz numarası (Sistemde aynı seri noya sahip birden fazla aktif cihaz olamaz), tebliğ kapsamında zorunludur	5	128	Zorunlu
	storeId	string	Kaydın bağlı olduğu dükkanı gösteren Id	1	-	Zorunlu
	brand	string	Cihaz markası	2	50	Opsiyonel
	model	string	Cihaz modeli	1	50	Opsiyonel
	certificationType	integer	Cihazın sertifikalı olup olmadığı bilgisi (Unknown=0, 1=DeviceCertified, 2=DeviceNotCertified)	-	-	Zorunlu
	description	string	Cihaz adı	-	500	Opsiyonel
	integrationId	string	Eğer cihaz bir entegrasyon vasıtası ile açılmışsa cihaz açan taraftaki Id'si	-	100	Opsiyonel
	alternateId	string	IntegrationId'ye alternatif	-	100	Opsiyonel