SmartCash Everywhere REST Server > Metode de scriere SmartCash Everywhere REST Server

Metoda SaveCustomer este utilizata pentru salvarea sau actualizarea unui client in baza de date centrala a unui lant de magazine SmartCash RMS. In cazul unui rezultat pozitiv, clientul devine imediat disponibil de exemplu pentru inregistrarea unei comenzi in vederea livrarii de marfa din sistemul SmartCash RMS prin utilizarea metodei AddNewDeliveryOrder.

Pentru determinarea unui client deja existent se foloseste urmatorul algoritm:

1.Mai intai se cauta identificarea unui client in sistemul SmartCash RMS dupa IDEXTAPP (camp obligatoriu totdeauna), care reprezinta codul unic al clientului in sistemul extern;

2.Daca clientul a fost gasit dupa IDEXTAPP in sistemul SmartCash si a fost furnizata o valoare in campul IDSMARTCASH, se face o verificare suplimentara si dupa acest camp. In cazul in care nu este returnat acelasi IDSMARTCASH este ridicata o eroare si metoda esueaza.

3.In cazul in care nu s-a identificat un client dupa IDEXTAPP, se cauta clientul dupa campurile CARD si IDSUPPLIERCARD daca au fost furnizate. Aceste campuri sunt utilizate pentru site-urile care genereaza prpriile coduri de card de fidelizxare pentru clientii online.

4.Daca clientul este gasit dupa CARD si IDSUPPLIERCARD in sistemul SmartCash si a fost furnizata o valoare in campul IDSMARTCASH, se face o verificare suplimentara si dupa acest camp, care trebuie sa fie identic in sistemul SmartCash cu cel furnizat. In cazul in care nu este returnat acelasi IDSMARTCASH este ridicata o eroare si metoda esueaza.

5.In cazul in care nu s-a identificat nici un client existent nici la pasul 1 nici la pasul 4 atunci se incearca gasirea si dupa campul IDSMARTCASH daca acesta a fost furnizat.

6.In cazul in care nu s-a identificat nici un client existent la pasul 1, 4 si 5 atunci se incearca gasirea si dupa campul VAT_NUMBER daca acesta a fost furnizat (impreuna cu toate campurile adiacente).

7.In cazul in care s-a identificat un client existent la unul din pasii 1, 4, 5 si 6 acesta nu va mai fi adaugat in sistemul SmartCash, urmand a fi actualizate toate informatiile transmise. Daca campul VAT_NUMBER_TYPE = 0 sau 1, se efectueaza o verificare suplimentara dupa campul VAT_NUMBER. Daca acesta este deja asociat la un client diferit de cel curent, este ridicata o eroare si metoda esueaza. In cazul in care VAT_NUMBER nu mai exista la alt client, sunt actualizate ambele campuri: VAT_NUMBER si TRADE_NUMBER impreuna cu celelalte campuri furnizate.

8.In cazul in care nu s-a identificat un client existent la nici unul din pasii 1, 4, 5, 6 si 7, se incerca gasirea si dupa campul EMAIL daca acesta a fost furnizat. Daca clientul a fost gasit dupa EMAIL in sistemul SmartCash si a fost furnizata o valoare in campul IDSMARTCASH, se face o verificare suplimentara si dupa acest camp. In cazul in care nu este returnat acelasi IDSMARTCASH este ridicata o eroare si metoda esueaza.

9.Daca in nici o situatie de mai sus nu a fost gasit un client existent, atunci clientul este adaugat in sistemul SmartCash pe baza campurilor transmise.

10.Campurile care nu se doresc a fi actualizate si nu sunt obligatorii nu trebuiesc furnizate in cadrul parametrului de apel al metodei.

Parametri Apel

Parametru	Descriere	Tip Date
aIDAPP	ID unic alocat aplicatiei care se conecteaza la serverul REST SmartCash	Integer
aJSONObject	Parametru formatat JSON, cu o sintaxa fixa (vezi exemplu), prin care sunt furnizate toate campurile necesare pentru tipul de date adaugat in sistemul SmartCash RMS.	TJSONObject

Campuri JSON incluse in parametrul aJSONObject

Camp	Descriere	Camp Obligatoriu	Tip Date
IDSMARTCASH	Codul unic al clientului in sistemul SmartCash. Campul trebuie furnizat doar daca el a fost salvat si in baza de date a aplicatiei terte. Transmiterea sa nu este obligatorie.	NU	Integer
IDEXTAPP	Codul clientului in sistemul extern. Trebuie totdeauna furnizat, indiferent daca este o adaugare de client nou sau o actualizare a datelor pentru un client existent. Totdeauna cautarea unui client in cazul acestei metode in sistemul SmartCash incepe cu acest camp si abia apoi dupa campul CARD sau IDSMARTCASH daca acestea au fost furnizate.	DA	String
NAME	Numele oficial al clientului, asa cum se doreste sa apara pe facturi. In cazul in care este o firma, in acest camp se trimite numele firmei. Poate ramane vid (in cazul unei persoane fizice nefacturabile), dar in aceste conditii trebuiesc transmise obligatoriu campurile FIRSTNAME si LASTNAME. Oricum, se va transmite obligatoriu doar in cazul adaugarii unui client nou. Daca este furnizat pentru un client existent va modifica valoarea respectiva in sistemul SmartCash. Daca nu este furnizat va fi compus automat prin concatenarea campurilor FIRSTNAME si LASTNAME.	DA/NU	String
IDCUSTOMER_TYPE	ID-ul unic in sistemul SmartCash al tipului de Client. Este obtinut prin apelarea prealabila a metodei GetCustomerTypes. Este obligatorie transmiterea lui.	DA	Integer
LISTED	Flag care semnalizeaza daca clientul este activ sau inactiv. 1=Activ, 0=Inactiv. Se foloseste pentru blocarea („stergerea”) clientilor. La adaugarea unui nou client trebuie transmis totdeauna cu valoarea 1=Activ.	DA/NU	Integer
PHONE	Nr. de Telefon	NU	String
FAX	Nr. de Fax	NU	String
GLN	Global Location Number pentru clientul respectiv (ILN/GLN)	NU	String
EMAIL	Adresa de e-mail a clientului	NU	String
VAT_NUMBER	Codul fiscal al clientului (CUI, CNP, Altele). Trebuie sa fie transmis totdeauna pentru clientii nou inserati pentru care se doreste emiterea unei facturi (impreuna cu flag-ul ALLOW_INVOICES = 1). In cazul clientilor persoane fizice facturabile care nu furnizeaza un cod CNP, campul VAT_NUMBER poate ramane necompletat cu conditia transmiterii obligatorii a campurilor TOWN, COUNTY si COUNTY_CODE. Codurile CUI (pentru VAT_NUMBER_TYPE=0) sau CNP (pentru VAT_NUMBER_TYPE=1) sunt acceptate doar dupa ce sunt validate pentru compunere corecta.	DA/NU	String
VAT_NUMBER_TYPE	Tipul codului fiscal (CUI/CNP/Altele). Trebuie sa fie transmis totdeauna. Poate avea una din valorile: 0=CUI; 1=CNP; 2=Altele.	DA	Integer
TRADE_NUMBER	Nr. Registrul Comertului. Trebuie sa fie transmis totdeauna pentru clientii nou inserati pentru care se doreste emiterea unei facturi. La o actualizare a unui client existent nu este necesar a fi retransmis.	DA/NU	String
ALLOW_INVOICES	Flag care semnalizeaza daca este permisa sau nu facturarea catre clientul respectiv. 1 = Permis, 0 = Interzis. Trebuie sa fie transmis totdeauna pentru clientii nou inserati pentru care se doreste emiterea unei facturi. La o actualizare a unui client existent nu este necesar a fi retransmis.	DA/NU	Integer
BANK_ACCOUNT	Numarul contului. Trebuie sa fie transmis totdeauna pentru clientii nou inserati pentru care se doreste emiterea unei facturi. La o actualizare a unui client existent nu este necesar a fi retransmis.	DA/NU	String
BANK_NAME	Numele Bancii la care e deschis contul clientului respectiv. Trebuie sa fie transmis totdeauna pentru clientii nou inserati pentru care se doreste emiterea unei facturi. La o actualizare a unui client existent nu este necesar a fi retransmis.	DA/NU	String
COUNTRY	Tara. In cazul in care este transmisa, denumirea trebuie sa fie identica cu cea din nomenclatorul de tari SmartCash RMS. In caz contrar metoda va esua cu un mesaj de eroare. Daca nu este furnizat este alocat automat tara Romania.	DA/NU	String
COUNTRY_CODE	Codul de Tara. In cazul in care este transmis, codul trebuie sa fie cel din nomenclatorul de tari SmartCash RMS, care este egal cu codul international din 2 litere al tarii. In caz contrar metoda va esua cu un mesaj de eroare. Daca nu este furnizat, este alocat automat codul de tara al Romaniei, care este „RO”. In cazul in care este furnizat are precedenta in localizarea tarii fata de campul COUNTRY. In cazul localizarii dupa COUNTRY_CODE campul COUNTRY este ignorat.	DA/NU	String
COUNTY	Judetul. Obligatoriu pentru clienti persoane fizice facturabile pentru care nu este furnizat un CNP. In cazul persoanelor juridice identificate dupa un cod fiscal campul nu este obligatoriu. In cazul in care este transmis, denumirea trebuie sa fie identica cu cea din nomenclatorul de judete SmartCash RMS care poate fi obtinut cu metoda GetAllLocalities. In caz contrar metoda va esua cu un mesaj de eroare.	DA/NU	String
COUNTY_CODE	Codul de Judet. Obligatoriu pentru clienti persoane fizice facturabile pentru care nu este furnizat un CNP. In cazul persoanelor juridice identificate dupa un cod fiscal campul nu este obligatoriu. In cazul in care este transmis, denumirea trebuie sa fie identica cu cea din nomenclatorul de judete SmartCash RMS, care poate fi obtinut cu metoda GetAllLocalities si este reprezentat de max. 2 litere (B, CV, HR, CJ, etc). In caz contrar metoda va esua cu un mesaj de eroare. In cazul in care este furnizat are precedenta in localizarea judetului fata de campul COUNTY. In cazul localizarii dupa COUNTY_CODE campul COUNTY este ignorat.	DA/NU	String
TOWN	Localitatea. Trebuie sa fie transmisa totdeauna pentru clientii persoane fizice nou inserati pentru care se doreste emiterea unei facturi sau transmiterea unei comenzi. La o actualizare a unui client existent campul nu este necesar a fi retransmis. In cazul persoanelor juridice identificate dupa un cod fiscal campul nu este obligatoriu. In cazul in care este transmis, denumirea trebuie sa fie identica cu cea din nomenclatorul de localitati SmartCash RMS care poate fi obtinut cu metoda GetAllLocalities. In caz contrar metoda va esua cu un mesaj de eroare.	DA/NU	String
TOWN_CODE	Codul localitatii in nomenclatorul SmartCash RMS care poate fi obtinut cu metoda GetAllLocalities. Acest cod este egal cu codul unic SIRUTA al localitatii disponibil pe site-ul Ministerului Dezvoltarii (pentru Romania). Campul nu este obligatoriu dar in cazul in care este furnizat are precedenta in localizarea localitatii fata de campul TOWN. In cazul localizarii dupa TOWN_CODE campul TOWN este ignorat.	DA/NU	String
STREET_ADDRESS	Adresa care contine informatiile de strada, numar, bloc, etaj apartament cu exceptia celor de tara, judet si localitate. Pentru site-uri online programul SmartCash RMS este configurat sa solicite adaugarea obligatorie a acestui camp. Pentru alte aplicatii validarea poate fi inlaturata prin configurarea sistemului SmartCash RMS.	DA/NU	String
POSTALCODE	Cod Postal	NU	String
LATITUDE	Latitudinea (in grade zecimale cu precizie de 7 zecimale)	NU	Float
LONGITUDE	Longitudinea (in grade zecimale cu precizie de 7 zecimale)	NU	Float
NOTES	Observatii optionale diverse de tip text.	NU	String
FIRSTNAME	Prenumele persoanei de contact fidelizate. Poate lipsi in cazul clientilor firme. In aceasta situatie insa trebuie transmis obligatoriu campul NAME.	DA/NU	String
LASTNAME	Numele de familie al persoanei de contact fidelizate. Poate lipsi in cazul clientilor firme. In aceasta situatie insa trebuie transmis obligatoriu campul NAME.	DA/NU	String
DATEOFBIRTH	Data Nasterii pentru persoana de contact	NU	Data
FACEBOOK_ID	ID Facebook	NU	String
IDSUPPLIERCARD	Codul SmartCash al Furnizorului de Fidelizare (Valoare intreaga fixa din SmartCash, 1 = Cod Card Fidelizare propriu SmartCash > 1 pentru alti furnizori de carduri). Valoarea se stabileste in SmartCash si ramane fixa pentru un furnizor anume de fidelizare. IDSUPPLIERCARD trebuie sa fie totdeauna diferit de valoarea aIDAPP.	NU	Integer
CARD	Codul de Card (sau de fidelizare) al clientului, corespunzator Furnizorului de Fidelizare cu ID-ul IDSUPPLIERCARD.	NU	String
IDFIDELITY_PROGRAM	ID-ul programului de fidelizare la care clientul sa fie asociat in urma actualizarii. Valoarea campului este fixa si este furnizata dupa definirea programului de fidelizare din SmartCash. In cazul in care campul nu este furnizat informatia de fidelizare este ignorata.	NU	Integer

Campuri JSON intoarse in caz de aplicare cu succes

Camp	Descriere	Tip Date
IDSMARTCASH	Codul unic al clientului in sistemul SmartCash.	Integer
IDEXTAPP	Codul clientului in sistemul extern.	String

Exemplu de formatare pentru parametrul aJSONObject al metodei SaveCustomer:

{"IDSMARTCASH":5,

"IDEXTAPP":"AVTE1098",

"NAME":"Cristescu Popa",

"TOWN":"Bucuresti",

"PHONE":"0754887889",

"FAX":"021457898",

"GLN":"CRI10",

"EMAIL":"email@noemail.ro",

"VAT_NUMBER":"RO1098766",

"VAT_NUMBER_TYPE":0,

"TRADE_NUMBER":"J/2099/1987",

"ALLOW_INVOICES":1,

"BANK_ACCOUNT":"ROIBME0099887771",

"BANK_NAME":"BCR",

"STREET":"str. Lacramioareleor",

"STREET_NUMBER":"102 Bis",

"NOTES":"",

"CARD_CODE":"1001000981112",

"IDCUSTOMER_TYPE":1,

"LISTED":1……}

Campuri JSON returnate in caz de succes:

{"result":{"IDEXTAPP":"AVTE1098","IDSMARTCASH":5,"RETURN":true}}

Campuri JSON returnate in caz de eroare (exemplu):

{"error":"invalid IDEXTAPP"}