Koncept integracije

Povezavo med spletno trgovino in MK se lahko izvede na naslednje načine :

• seznam vseh artiklov in zalogo se vodi v MK. S pomočjo cenika se določijo cene objavljenih artiklov. Spletna trgovina vsake toliko časa pokliče 'get_pricelist_inventories' in s tem obnovi seznam artiklov v spletni trgovini. V spletni trgovini se potem podatki še obogatijo s slikami, dodatnimi opisi, itd. Pred potrditvijo nakupa se izvede še preverjanje zaloge preko 'check_inventories'. Po uspešno opravljenem nakupi se zabeleži nakup preko klica 'put_sales_bill'. Na koncu se za uporabnika lahko pripravi PDF dokument računa preko klica 'get_document_for_bill'.
• seznam vseh artiklov se vodi v spletni trgovini, kjer se tudi dodajajo / spreminjajo / urejajo artikli. Vsaka sprememba se pošlje na MetaKocka. Uporabnik vse artikle in cene uredi v trgovini. Po uspešno opravljenem nakupi se zabeleži nakup preko klica 'put_sales_bill'. Pred nakupom se lahko izvede preverjanje zaloge preko 'check_inventories'. Dodatni oz. novi artikli se avtomatično zabeležijo v MetaKocka. Na koncu se za uporabnika lahko pripravi PDF dokument računa preko klica 'get_document_for_bill'.
• podobno kot zgornji primer, samo da spletna trgovina v MK izdela ustrezno ponudbo (klic 'put_sales_offer'). Skrbnik MK računa potem v MK izvede prenos ponudbe na račun, natisne račun ter ga pošlje uporabniku.

Splošna oblika klicev

Za vse metode je značilno :

• podjetje identificiramo s pomočjo secret_key in company_id,
• zahtevek se vedno pošlje preko POST metode,
• URL naslov metode določi tip operacije (npr. dodajanje artikla, dodajanje računa, itd),
• odgovor vedno vsebuje naslednje parametre :

- opr_code : koda rezultata. Če je 0, potem je OK. Vse ostalo so napake,
- opr_code_app : koda aplikacijske napake, če do nje pride,
- opr_desc : tehnični opis napake v primeru sestemske napake,
- opr_desc_app : določene napake so aplikacijske in v tem primeru se izpiše enako sporočilo o napaki, kot se izpiše v MetaKocka aplikaciji.
- opr_time_ms : čas izvajanja zahtevka na strežniku v milisekundah

• opr_code - vrednosti od 0 do 100 so rezervirane za sistemske napake. Več kot 100 so aplikacijske napake, ki se navezujejo na posamezni klic.
• aplikacijske napake so v angleščini in njihov opis ni namenjen prikazu uporabniku. Po drugi strani pa so napake, ki jih sporočijo posamezni klici, skoraj vedno enaku kot tisti, ki se nahajajo v MK. Zato se jih lahko prikaže uporabniku. Primer : 'Enota mere ‘cm4’ ne obstaja v šifrantu enot mere.'

Sistemske napake :

Običajen odgovor v primeru napake :

{
    "opr_code":"2",
    "opr_desc":"artikel eshop_001",
    "opr_time_ms":"8"
}

Izvorna koda primerov

PHP

• vsi primeri so preizkušeni na PHP 5.3 in uporabljena je dodatna knjižnjica pest - https://github.com/educoder/pest,
• knjižnjico je nekoliko dopolnjena, tako da POST metoda vsebuje tudi parameter "content type",
• vsi primeri skupaj s knjižnjico so na voljo v datoteki eshop_php_samples_v2.zip

Artikli

product_add – dodajanje artiklov

Opis : Dodajanje novih artiklov. Če že obstaja artikel z enako count_code in code (to v praksi pomeni enaki artikel), dobimo napako. Ob uspešnem dodajanju dobimo tudi interno oznako artikla.
URL : https://main.metakocka.si/rest/eshop/v1/json/product_add

Primer klica

{
    "secret_key":"my_secreat_key",
    "company_id":"16",
    "count_code":"eshop_001",
    "code":"eshop_001_sif",
    "name":"artikel eshop_001",
    "name_desc": "artikel eshop_001 - daljsi opis",    
    "unit":"kos",
    "service":"false",
    "sales":"true",
    "purchasing":"false",
    "height":"12.23",
    "depth":"4.12",
    "weight":"6.3",
}

Primer odgovora

{
    "opr_code":"0",
    "opr_time_ms":"33",
    "mk_id":"1600001744",
    "count_code":"eshop_002"
}

Primer kode

(product_add_json.php)

<?php
    require_once("Pest.php");
 
    $url = 'https://main.metakocka.si/rest/eshop/v1/json/product_add';
    $company_id = '16';
    $secret_key = 'my_secret_key';
 
    $requestJSON = array (
        'secret_key'=>$secret_key, 'company_id'=>$company_id, 'count_code'=>'eshop_001',
        'code'=>'eshop_001_sif', 'name'=>'artikel eshop_001', 'name_desc'=>'artikel eshop_001 - daljsi opis',    
        'unit'=>'kos', 'service'=>'false', 'sales'=>'true', 'purchasing'=>'false', 'height'=>'12.23',
        'depth'=>'4.12', 'weight'=>'6.3'
    );
 
    echo '<html><body>';
    echo '<b>URL</b> : '.$url.'<br/>';
    echo '<b>POST data</b> : '.json_encode($requestJSON).'<br/>';
    echo '<hr/>';
    echo '<b>Request start...</b><br/>';
    $pest = new Pest($url);
    $thing = $pest->post('', 'application/json', json_encode($requestJSON));
 
    echo '<b>Respond : </b>'.$thing;
    echo '</body></html>';    
?>

product_update – sprememba opisa

Opis : izvedba popravkov podatkov na artiklu. V primeru konflikta s pravili za zagotavljanje konsistentnosti podatkov, metoda vrne ustrezno napako.
URL : https://main.metakocka.si/rest/eshop/v1/json/product_update

Primer klica

{
    "secret_key":"my_secreat_key",
    "company_id":"16",
    "count_code":"eshop_001",
    "code":"eshop_001_sif",
    "name":"artikel eshop_001",
    "name_desc": "artikel eshop_001 - daljsi opis",    
    "unit":"kos",
    "service":"false",
    "sales":"true",
    "purchasing":"false",
    "height":"12.23",
    "depth":"4.12",
    "weight":"6.3",
}

Opombe :

• oblika zahtevka in odgovor je praktično enako kot v primeru partner_add klica,
• edina razlika je v tem, da mora biti podani "count_code" ali "mk_id" atribut za identifikacijo artikla.

product_delete – brisanje artikla

Opis : brisanje obstoječega artikla. V primeru konflikta s pravili za zagotavljanje konsistentnosti, se vrne ustrezna napaka.
URL : https://main.metakocka.si/rest/eshop/v1/json/product_delete

Primer klica

{
    "secret_key":"my_secret_key",
    "company_id":"16",
    "count_code":"eshop_003"
}

Opombe :

• odgovori so v enaki obliki kot v primeru klica partner_add / partner_update

product_list - podatki o artiklih

Opis : izpis vseh artiklov s pripadajočimi podatki in stanjem zaloge na skladišču
URL : https://main.metakocka.si/rest/eshop/v1/json/product_list

Primer klica

{
    "secret_key":"my_secret_key",
    "company_id":"16",
    "sales":"true",
    "return_warehause_stock":"true"
}

Opombe za zahtevek:

• parametrom sales, purchase, service, work podamo lahko vrednost "true" (mora biti tega tipa), "false" (ne sme biti tega tipa) ali parametra ne nastavimo in se parameter ne bo upošteval kot pogoj
• klic vedno vrne največ 1000 zadetkov. Če je vrednost atributov "limit" in "product_list_count" enaka, potem je potrebno izvesti še dodatni klic, kjer je offset parameter nastavljen na ("prejšni offset" + "limit").

Primer odgovora

{
   "opr_code":"0",
   "opr_time_ms":"11762",
   "sales":"true",
   "return_warehause_stock":"true",
   "limit":"2",
   "offset":"0",
   "product_list_count":"2",
   "product_list":[
      {
         "company_id":"0",
         "mk_id":"1600000027",
         "code":"prod sifra 1",
         "name":"naziv sifra 1",
         "unit":"kos",
         "service":"false",
         "sales":"true",
         "purchasing":"true",
         "height":"1",
         "width":"2",
         "depth":"3",
         "weight":"4",
         "amount":"-2000"
      },
      {
         "company_id":"0",
         "mk_id":"1600000028",
         "code":"pod sifra 2",
         "name":"pod naziv 2",
         "unit":"dan",
         "service":"false",
         "sales":"true",
         "purchasing":"false",
         "amount":"-10"
      }
   ]
}

Opombe za odgovor:

• vhodni parametri (sales, purchase, itd) se vedno ponovijo,
• product_list_count je število rezultatov.

Računi in Ponudbe

put_sales_bill – izdelava prodajnega računa

Opis : dodajanje novega prodajnega računa, pri katerem se avtomatično identificira obstoječega partnerja ali doda novega. Na podoben način se tudi identificirajo artikli ali dodajo novi. Za materialne artikle se samodejno generira dobavnica. Lahko se tudi doda oznaka, da je račun plačan preko banke ali blagajne.
URL : https://main.metakocka.si/rest/eshop/v1/json/put_sales_bill

Primer klica 1

{
   "secret_key":"my_secret",
   "company_id":"16",
   "foreign" : "true",   
   "count_code":"eshop001",
   "bill_date":"12.03.2011",
   "payment_date":"12.03.2011",
   "location_of_service":"Komenda",
   "warehouse":"glavno skladisce",
   "buyer_order":"narocilo 123",
   "partner":{
      "business_entity":"true",
      "taxpayer":"true",
      "foreign_county":"false",
      "tax_id_number":"SI10040073",
      "customer":"eshop 1",
      "street":"Slovenska cesta 100",
      "post_number":"1000",
      "place":"Ljubljana",
      "country":"Slovenia",
      "partner_contact": {
         "name": "Rok Doltar",
         "phone": "05 320 24 88",
         "fax": "05 320 24 84",
         "gsm": "071 333 444",
         "email": "test@test.co.uk"
       },
      "partner_delivery_address": {
         "street": "Ljubljanska 25",
         "post_number": "1001",
         "city": "Ljubljana",
         "country": "Slovenija"
      }
   },
   "mark_paid":[
      {
            "payment_type":"Transakcijski račun",
            "date":"12.03.2011"
      }
   ],
   "product_list":[
      {
         "count_code":"2",
         "amount":"10",
         "price":"11",
         "discount":"12",
         "tax":"085"         
      },
      {
         "code":"eshop_artikel_1",
         "amount":"20",
         "price_with_tax":"21",
         "discount":"22",
         "tax":"200"         
      },
      {
         "count_code":"eshop_artikel_2",
         "code":"eshop_artikel_2",
         "name":"eshop_artikel_2",
         "name_desc":"eshop_artikel_2 opis",
         "unit":"kom",
         "service":"false",
         "sales":"true",
         "purchasing":"false",
         "amount":"30",
         "price":"31",
         "discount":"32",
         "tax":"000"
      }      
   ]   
}

Opombe :

• doda se novi partner
• označi se, da je bil račun plačan 25.03.2011 preko bančne transakcije v vrednosti 12,34
• prvi artikel se poišče preko ID artikla z vrednostjo "2"
• drugi artikel se poišče po šifri artikla z vrednostjo "eshop_artikel_1"
• tretji artikel se doda kot novi artikel

Primer kode

<?php
    require_once("Pest.php");
 
    $url = 'https://main.metakocka.si/rest/eshop/v1/json/put_sales_bill';
    $company_id = '16';
    $secret_key = 'my_secret';
 
    $requestJSON = array (
        'secret_key'=>$secret_key, 'company_id'=>$company_id, 'count_code'=>'eshop_003', 
        'bill_date'=>'12.03.2011', 'payment_date'=>'12.03.2011', 'location_of_service'=>'Komenda', 
        'partner'=>array(
          'business_entity'=>'true',
          'taxpayer'=>'true',
          'foreign_county'=>'false',
          'tax_id_number'=>'SI10040073',
          'customer'=>'eshop 1',
          'street'=>'Slovenska cesta 100',
          'post_number'=>'1000',
          'place'=>'Ljubljana',
          'country'=>'Slovenia'
        ),
        'mark_paid'=>array(
            array(
             'payment_type'=>'Transakcijski račun',
             'date'=>'25.03.2011'
            )
        ),
        'product_list'=>array(
            array(
             'count_code'=>'2',
             'amount'=>'10',
             'price'=>'11',
             'discount'=>'12',
             'tax'=>'085'                
            ),
            array(            
             'code'=>'eshop_artikel_1',
             'amount'=>'20',
             'price'=>'21',
             'discount'=>'22',
             'tax'=>'200'                     
            ),            
            array(                        
             'count_code'=>'eshop_artikel_2',
             'code'=>'eshop_artikel_2',
             'name'=>'eshop_artikel_2',
             'name_desc'=>'eshop_artikel_2 opis',
             'unit'=>'kom',
             'service'=>'false',
             'sales'=>'true',
             'purchasing'=>'false',
             'amount'=>'30',
             'price'=>'31',
             'discount'=>'32',
             'tax'=>'000'            
            )            
        )
    );
 
    echo '<html><body>';
    echo '<b>URL</b> : '.$url.'<br/>';
    echo '<b>POST data</b> : '.json_encode($requestJSON).'<br/>';
    echo '<hr/>';
    echo '<b>Request start...</b><br/>';
    $pest = new Pest($url);
    $thing = $pest->post('', 'application/json', json_encode($requestJSON));
 
    echo '<b>Respond : </b>'.$thing;
    echo '</body></html>';    
?>

put_sales_offer – izdelava ponudbe

Opis : dodajanje nove ponudbe, pri kateri se samodejno prepozna obstoječega partnerja ali doda novega. Na podoben način se tudi prepozna artikle ali dodajo novi. Lahko se tudi doda oznaka, da je ponudba plačan preko banke ali blagajne.
URL : https://main.metakocka.si/rest/eshop/v1/json/put_sales_offer

Primer klica 1

{
   "secret_key":"test",
   "company_id":"16",
   "count_code":"eshop_offer_1",
   "date":"08.05.2011",
   "validity":"30",
   "advance_payment_percent":"10",
   "partner":{
      "business_entity":"true",
      "taxpayer":"true",
      "foreign_county":"false",
      "tax_id_number":"SI10040073",
      "customer":"eshop 1",
      "street":"Slovenska cesta 100",
      "post_number":"1000",
      "place":"Ljubljana",
      "country":"Slovenia"
   },
   "mark_paid":[
      {
          "payment_type":"Transakcijski račun",
          "date":"08.05.2011"
      }
   ],
   "product_list":[
      {
         "count_code":"2",
         "amount":"10",
         "price":"11",
         "discount":"12",
         "tax":"085"         
      },
      {
         "code":"eshop_artikel_1",
         "amount":"20",
         "price":"21",
         "discount":"22",
         "tax":"200"         
      },
      {
         "count_code":"eshop_artikel_2",
         "code":"eshop_artikel_2",
         "name":"eshop_artikel_2",
         "name_desc":"eshop_artikel_2 opis",
         "unit":"kom",
         "service":"false",
         "sales":"true",
         "purchasing":"false",
         "amount":"30",
         "price":"31",
         "discount":"32",
         "tax":"000"
      }      
   ]   
}

Opombe :

• doda se novi partner,
• 10% ponudbe je predplačilo,
• označi se, da je bila ponudba plačana 25.03.2011 preko bančne transakcije v vrednosti 12,34
• prvi artikel se poišče preko ID artikla z vrednostjo "2",
• drugi artikel se poišče po šifri artikla z vrednostjo "eshop_artikel_1",
• tretji artikel se doda kot novi artikel

Primer kode

<?php
    require_once("Pest.php");
 
    $url = 'https://main.metakocka.si/rest/eshop/v1/json/put_sales_offer';
    $company_id = '16';
    $secret_key = 'my_secret';
 
    $requestJSON = array (
        'secret_key'=>$secret_key, 'company_id'=>$company_id, 'count_code'=>'eshop_offer_001', 
        'date'=>'8.5.2011', 
        'partner'=>array(
          'business_entity'=>'true',
          'taxpayer'=>'true',
          'foreign_county'=>'false',
          'tax_id_number'=>'SI10040073',
          'customer'=>'eshop 1',
          'street'=>'Slovenska cesta 100',
          'post_number'=>'1000',
          'place'=>'Ljubljana',
          'country'=>'Slovenia'
        ),
        'mark_paid'=>array(
            array(
             'payment_type=>'Transakcijski račun',
             'date'=>'8.5.2011'
            )
        ),
        'product_list'=>array(
            array(
             'count_code'=>'2',
             'amount'=>'10',
             'price'=>'11',
             'discount'=>'12',
             'tax'=>'085'                
            ),
            array(            
             'code'=>'eshop_artikel_1',
             'amount'=>'20',
             'price'=>'21',
             'discount'=>'22',
             'tax'=>'200'                     
            ),            
            array(                        
             'count_code'=>'eshop_artikel_2',
             'code'=>'eshop_artikel_2',
             'name'=>'eshop_artikel_2',
             'name_desc'=>'eshop_artikel_2 opis',
             'unit'=>'kom',
             'service'=>'false',
             'sales'=>'true',
             'purchasing'=>'false',
             'amount'=>'30',
             'price'=>'31',
             'discount'=>'32',
             'tax'=>'000'            
            )            
        )
    );
 
    echo '<html><body>';
    echo '<b>URL</b> : '.$url.'<br/>';
    echo '<b>POST data</b> : '.json_encode($requestJSON).'<br/>';
    echo '<hr/>';
    echo '<b>Request start...</b><br/>';
    $pest = new Pest($url);
    $thing = $pest->post('', 'application/json', json_encode($requestJSON));
 
    echo '<b>Respond : </b>'.$thing;
    echo '</body></html>';    
?>

report_bill in report_offer - izdelava PDF dokumentov za račun in ponudbo

Opis : izdelava PDF dokumenta računa oz. ponudbe. Enako, kot če bi v MK izbral tiskanje računa oz. ponudbe in izbral prevzeti izpis.
URL : https://main.metakocka.si/rest/eshop/v1/pdf/report_bill ali https://main.metakocka.si/rest/eshop/v1/pdf/report_offer

Primer klica 1

{
   "secret_key":"test",
   "company_id":"16",
   "count_code":"PRD_110_PRD1",
   "hide_code":"false",
   "country":"si",
   "locale":"sl"
}

Primer kode 1

<?php
    require_once("Pest.php");
 
    $url = 'https://main.metakocka.si/rest/eshop/v1/pdf/report_bill';
    $company_id = '16';
    $secret_key = 'my_key';
 
    $requestJSON = array (
        'secret_key'=>$secret_key, 'company_id'=>$company_id, 'count_code'=>'PRD_543_PRD',
        'hide_code'=>'false'
    );
 
    echo '<html><body>';
    echo '<b>URL</b> : '.$url.'<br/>';
    echo '<b>POST data</b> : '.json_encode($requestJSON).'<br/>';
    echo '<hr/>';
    echo '<b>Request start...</b><br/>';
    $pest = new Pest($url);
    $thing = $pest->post('', 'application/json', json_encode($requestJSON));
 
    // write respond into file
    $fileName = '/Users/mk_eshop/output.pdf';
    $fh = fopen($fileName, 'w');     
    fwrite($fh, $thing);
    fclose($fh);
 
    echo '<b>Write output into : '.$fileName.'</b><br/>';
 
    echo '</body></html>';    
?>

Odgovor klica je v dveh oblikah :

1. Uspešno izvedeno generiranje. Odgovor je PDF datoteka, ki jo zatem lahko posredujemo odjemalcu. Dve opozorili : iz odjemalca (recimo preko JavaScript POST zahtevka) ne smemo direktno klicati MK API, ker klic vsebuje secret_key. Vedno moramo v spletni trgovini narediti t.i. server-to-server komunikacijo zatem dokument posredovati iz spletne trgovine.
2. JSON odgovor v primeru napake. Primer :

{
   "opr_code":"6",
   "opr_code_app":"201",
   "opr_time_ms":"0",
    "opr_desc_app":"Cannot find offer with count_code = PRD_110_PRD1"
}

Splošno za izdelavo računa in ponudbe

Postopek identifikacije partnerja in naslova

MetaKocka poizkuša na podlagi podanih podatkov prepoznati obstoječega partnerja. Postopek je naslednji :

• je poslovni partner (business_entity = true) in ima podano davčno številko (tax_id_number)

Naslov se določi po naslednjem postopku :

• partner ima samo en naslov - se avtomatično izbere ta naslov,
• med vhodnimi parametri ni podan parameter "street" - se avtomatično izbere prvi naslov,
• partner ima več naslovov - pravi naslov poiščemo s pomočjo podanega parametra "street". Če naslova ne najdemo, izberemo prvi naslov

V primeru, da partnerja po zgornjih kriterijih ne najdemo, dodamo novega partnerja. Za novega partnerja so na voljo naslednja polja :

Atributi objekta "partner_contact":

• name (String - predstavlja polje "kontakt" v Metakocki)
• phone (String - predstavlja polje "Telefon" v Metakovki)
• fax (String - predstavlja polje "Fax" v Metakocki)
• gsm (String - predstavlja polje "GSM" v Metakocki)
• email (String - predstavlja polje "email" v Metakocki)

Če partner v Metakocki že obstaja, se za "partner_contact" izvede naslednji postopek:

• Za obstoječega partnerja se poišče kontakt z enakim poljem "kontakt", t.j. ime in priimek kontakta.
• Če obstaja, se posodobijo vsa ostala polja kontakta z novimi vrednostmi
• Če ne obstaja, se doda nov kontakt

Atributi objekta "partner_delivery_address":

• street (String - predstavlja polje "ulica" v Metakocki)
• post_number (String - predstavlja polje "poštna št." v Metakovki)
• city (String - predstavlja polje "Kraj" v Metakocki)
• country (String - predstavlja polje "Država" v Metakocki)

Če partner v Metakocki že obstaja, se za "partner_delivery_address" izvede naslednji postopek:

• Za obstoječega partnerja se poišče naslov z enakim poljem "ulica" ter "poštna št.".
• Če obstaja, se posodobijo vsa ostala polja naslova z novimi vrednostmi
• Če ne obstaja, se doda nov naslov

Postopek identifikacije artikla

MetaKocka poizkuša na podlagi podanih podatkov identificirati obstoječi artikel. Postopek je naslednji :

• če je podan count_code atribut (Id. artikla), potem se poišče prvi artikel, ki ustreza tej vrednosti,
• če je podan code atribut (šifra artikla), potem se poišče prvi artikel, ki ustreza tej vrednosti

V primeru, da artikla po zgornjih kriterijih ne najdemo, dodamo novi artikel. Za novi artikel so na voljo naslednja polja :

Vsak dodani artikel mora vsebovati še podatke, ki so vezane na račun / ponudbo :

Primer 1 : identifikacija artikla preko 'count_code' :

{
    "count_code":"2",
    "amount":"10",
    "price":"11",
    "discount":"12",
    "tax":"085"         
}

Primer 2 : vstavljanje novega artikla :

{
    "count_code":"eshop_artikel_2",
    "code":"eshop_artikel_2",
    "name":"eshop_artikel_2",
    "name_desc":"eshop_artikel_2 opis",
    "unit":"kom",
    "service":"false",
    "sales":"true",
    "purchasing":"false",
    "amount":"30",
    "price":"31",
    "discount":"32",
    "tax":"000"
}

Številčenje računov in ponudb

Številčenje računov in ponudb je mogoče implementirati na dva načina :

• uporaba samodejnega številčenja v MetaKocka

Za vsak tip dokumenta (tudi prodajnih račun / ponudbo) je v MetaKocka mogoče nastaviti pravila samodejnega številčenja. V tem primeru se bo ob klicu storitev izbrala naslednja številka računa / ponudbe.
V tem primeru uporabniku ni potrebno paziti na pravo številčenje in le te lahko izdajamo preko nakupov v spletni trgovini ali neposredno iz MetaKocke.
Izvedba : ob klicu ne smemo podati parametra "count_code". V odgovoru bomo dobili številko računa / ponudbe v parametru count_code. V primeru, da bo podan parameter "count_code", se bo le ta uporabil. Na ta način lahko obidemo obstoječi način številčenja.

• posredovanje svoje številke računa / ponudbe

V primeru že uveljavljenega načina številčenja v spletni trgovni, lahko le ta posreduje številko direktno v MetaKocko. Pri tem je potrebno paziti na to, da se številke ne bodo podvojile (v tem primeru pride do napake pri klicu storitve). Na ta način lahko implementiramo ločeno številčenje za račune / ponudbe iz spletne trgovine in tiste, ki jih direktno izdajamo iz MetaKocke.
Izvedba : ob klicu moramo podati parameter "count_code".

Izdelava dobavnice

V primeru, da na račun dodamo artikel, ki ni označen kot storitev (to pomeni, da je materialni artikel), je potrebno izdelati dobavnico. Izdelava je mogoča na naslednje načine :

• Uporabnik si v nastavitvah MetaKocka aplikacija označi, katero skladišče je prevzeto za izdelavo dobavnice. Glej "Nastavitve" in potem "Privzeto izdelaj dob. / prev.

na skladišču"

• poslani podatki vsebujejo oznako ali ime skladišča. Potrebno je uporabiti oznako "warehouse". Primer :

{
   "secret_key":"test",
   .........
   "warehouse":"skladisce1",
   "partner":{
   .........
}

V primeru, da je podamo napačno ime skladišča, dobimo napako oblike :

{
   "opr_code":"2",
   "opr_desc":"Warehouse with name 'oznaka1X' does not exist.","opr_time_ms":"102"
}

V primeru, da zgornje dva pogoja nista izpolnjena, se samodejno izbere glavno skladišče. V MetaKocka mora uporabnik vedno imeti ena skladišče, ki je glavno.

Ko se izdela dobavnica, se tudi na skladišču odpiše materialno zalogo. MK prevzeto ne dovoli negativno količino. Možne rešitve :

1. če imamo dejansko zalogo na svojem skladišču, jo predhodno uvozimo s pomočjo prevzemnice.
2. na podjetju nastavimo, da ima lahko skladišče z negativno količino ('Nastavitve' -> 'Skladišče ima lahko negativno stanje')

V primeru, da pri uvozu pride do napake zaradi negativnega stanja artikla, je napaka naslednje oblike :

{
  "opr_code":"6",
  "opr_desc":"Artikel 'Kolo' ima na skladišču 'Glavno skladišče' negativnost količino z vrednostjo -1",
  "opr_time_ms":"383"
}

Primer in oblika odgovora

V primeru uspešnega sprejetja zahtevka dobimo odgovor naslednje oblike :

{
    "opr_code":"0",
    "opr_time_ms":"33",
    "mk_id":"1600001744",
    "count_code":"eshop_002"
}

Označba plačila

Na posameznih dokumentih (računi, ponudbe, naročilnice) je mogoče označiti, da je bil le ta že plačan preko izbrane vrste plačila. Pomen posameznih atributov :

Primer : celotni račun označimo kot plačan preko Transakcijskega računa

     "mark_paid":[
          {
               "payment_type":"Transakcijski račun",
               "date":"25.03.2011",
          }
     ]

Primer : 10 EUR je bilo plačanih preko gotovine

     "mark_paid":[
          {   
               "payment_type":"Gotovina",
               "date":"25.03.2011",
               "amount":"10.00"
          }
     ]

Primer : 200 EUR je bilo plačanih kot predplačilo preko Transakcijskega računa, ostalih 800 EUR pa dan pozneje preko Monete

   "mark_paid":[
     {
          "payment_type":"Transakcijski račun",
          "date":"25.03.2011",
          "mark_prepaid":"true",
          "amount" : "200"
     },
     {
          "payment_type":"Moneta",
          "date":"26.03.2011",
          "amount" : "800"
     }
   ],

Vpis potnih stroškov, kuponov, skupnih popustov, itd

Potne stroške v MK dodamo na naslednji način :

• v MK se pripravi artikel, ki ima šifro "potni_stroski" in naziv "Potni stroški", enoto mere "stor" (kot storitev) in je označen kot storitev.
• pri generiranju računa / ponudbe v MK preko klica put_sales_bill / put_sales_offer uporabimo že obstoječi artikel za potne stroške in mu dodamo samo še vrednost. Primer :

{
    "code":"potni_stroski",
    "amount":"1",
    "price":"10",
    "discount":"0",
    "tax":"020"         
}

Na podobni način lahko naredimo artikel 'skupni_popust' in ga uporabimo za nek fiksni popust na celotni račun.

Pri kuponih pa je implementacija malenkostno drugačna. Primer : uporabnik je za nakup vnovčil še kupon za 10 EUR. Potrebno je narediti naslednje :

• v MK se pripravi artikel, ki ima šifro "kupon_za_popust" in naziv "Kupon za popust", enoto mere "kos" in je označen kot storitev (ker ga ne prenašamo na skladišče).
• pri generiranju računa / ponudbe v MK preko klica put_sales_bill / put_sales_offer uporabimo že obstoječi artikel za kupon in mu dodamo negativno vrednost za kolicino ter običajno tudi davek 0%. Primer :

{
    "code":"kupon_za_popust",
    "amount":"-1",
    "price":"10",
    "discount":"0",
    "tax":"000"         
}

Skladišče

check_inventories - ali je artikel na zalogi

Opis : preveri, če je podani artikel na zalogi in vrne skupno zalogo ter zalogo po posameznih skladiščih.
URL : https://main.metakocka.si/rest/eshop/v1/json/check_inventories

Primer klica

{
    "secret_key":"test",
    "company_id":"16",
    "code":"skatla_d1"    
}

Primer odgovora

{
    "opr_code":"0",
    "opr_time_ms":"33",
    "count_code":"PRD_542_PRD",
    "code":"skatla",
    "unit":"kos",
    "all_amount":"20",
    warehouse_amount:[
        {
            "warehouse_mark":"skladisce1",
            "amount":"10"
        },
        {
            "warehouse_mark":"skladisce2",
            "amount":"20"
        }        
    ]            
}

Predvidene napake :

Ostalo o delovanju storitev

Varnost

Varnost prenešenih podatkov je zagotovljena na naslednji način :

• vsak klic vsebuje kombinacijo 'secret_key' in 'company_id'. 'secret_key' se po varni poti dostavi implementatorju spletne trgovine.
• Implementator spletne trgovine sporoči seznam IP naslovov, iz katerih bodo prihajali klici za določeno trgovino
• klici storitev se izvedejo preko HTTPS

Dosegljivost

MetaKocka ne podpira 100% uptime (recimo v času nadgradnje), zato mora spletna trgovina podpirati primere, da storitve na strani MetaKocke niso dosegljive. Možni scenariji :

• uporabnika obvesti, da nakup ni mogoče in da naj operacijo pozneje ponovi,
• zahtevek (predvsem 'put_sales_order' / 'put_sales_bill') shrani in ga pozneje ponovno pošlje. V primeru napake (recimo, da izdelka ni več na zalogi) o tem ustrezno obvesti odgovorno osebo, ki primer reši individualno.

Omejitev števila klicev

MetaKocka ima implementirane določene omejitev število klicev, da zaradi napačne ali zlonamerne uporabe ne pride do preobremenitve backend sistema. Kvota se nastavi na dovolj veliko vrednost, da ne bi smelo prihajati do težav pri običajni uporabi.

Vsak klic je svoja transakcija

Vsak klic se obravnava kot ena transakcija. Kar pomeni, da se v celoti izvede uspešno oz. se v primeru napak ne zapišejo nobene spremembe v MetaKocka.

Predvideni klici v prihodnosti

V primeru potreb so za prihodnost planirani naslednji klici:

• product_exist - preverjanje, ali obstaja v MetaKocki določen artikel
• get_pricelist_inventories - za podani artikel vrne ceno in zalogo,
• check_inventories - za podani artikel vrne samo količino