Za razvijalce

Quibi omogoča izdelavo računov in predračunov iz zunanjih programov (spletnih trgovin). V ta namen je izdelan API. Če katerega klica ni na razpolago, nam sporočite in ga bomo dodali.

Klicanje API-ja in prijava

Vsi klici zahtevajo prijavo, ki je dodana v glavo zahtevka (http header). Podatki za api so enaki, kot prijavni podatki Quibi-ja:

username: vase@uporanbisko.ime
password: VaseVarnoGeslo
Content-Type: application/json

Api kličemo preko GET ali POST (dodajanje in urejanje podatkov) metode. Vse parametre podajamo v JSON formatu.

API url: https://si.quibi.net

Odgovor

Vsi klici vračajo odgovor v sledeči obliki:

{
   "error":false,
   "message":"",
   "errors":{
      "SEZNAMNAPAK"
   },
   "data":{
      "IMEPODATKA":[
         "VREDNOSTI"
      ]
   }

Opis parametrov:

error – true/false – ali je prišlo do napake
message – sporočilo ob napaki
errors – polja, katera so napačna in napaka
data – podatki, ki smo jih zahtevali

Šifranti

Seznam ddv-jev

Metoda: GET URL: /api2/ddv

Seznam držav

Metoda: GET URL: /api2/drzava

Seznam enot

Metoda: GET URL: /api2/enota

Seznam plačil

Metoda: GET URL: /api2/glavadokumenta/placila

Seznam skladišč

Metoda: GET URL: /api2/skladisca Opomba: samo v primeru, da imamo vključeno materialno poslovanje.

Seznam davčnih blagajn

Metoda: GET URL: /api2/spaces Opomba: samo v primeru, če imate vključene davčne blagajne.

Številčenje

Metoda: GET URL: /api2/stevilcenje

Če dodate parameter ?glavadokumenta=1, potem izpiše vsa številčenja.

Stroškovna mesta

Metoda: GET URL: /api2/stroskovnamesta

Vrste naslovov

Metoda: GET URL: /api2/addresstype

Ceniki

Metoda: GET URL: /api2/cenik

Kategorije

Metoda: GET URL: /api2/kategorije

Vnos nove kategorije

Metoda: POST URL: /api2/kategorije/form

Parametri (označeni z * so obvezni):

Kategorije:
- naziv*

Vrste prodaje

Metoda: GET URL: /api2/glavadokumenta/vrstaprodaje

Statusi dokumentov

Metoda: GET URL: /api2/statusi

Vrne seznam statusov, ki jih imate določene v šifrantu Statusi. Za vsak status vrne:

id – id statusa (uporabite ga pri filtriranju dokumentov)
naziv – naziv statusa
privzeta – true/false – ali je status privzet (samodejno se nastavi na novih dokumentih)

Dokumenti

Seznam dokumentov

Metoda: POST

Parametri:

Filtriraj:
- leto – int – primer: 2019
- stranka – int – id stranke iz šifranta
- datod – date – v formatu Y-m-d
- datdo – date – v formatu Y-m-d
- sklic: iskanje po sklicu
- statusi – int ali array – id statusa (ali več statusov) iz šifranta /api2/statusi

URL klica za različne vrste dokumentov:

Fakture – /api2/fakture
Predračuni – /api2/predracuni
Dobavnice – /api2/dobavnice
Prevzemnice – /api2/prevzemnice
Dobropisi – /api2/dobropisi
Naročilnice – /api2/narocilnice
Avansni računi – /api2/predplacila
Prenos med skladišči – /pi2/prenosmedskladi
VKR – /api2/vkr
Delovni nalogi – /api2/dn
Naročila kupcev – /api2/narocilakupcev
Izdajnice – /api2/izdajnice

Vsak dokument v odgovoru vsebuje polje Glavadokumenta.statusi_id in podatek Statusi (id, naziv). Če dokument nima statusa, sta vrednosti null.

Klic posameznega dokumenta

Metoda: GET URL: /api2/glavadokumenta/view/ID_DOKUMENTA

Delna plačila dokumenta

Metoda: GET URL: /api2/delnaplacila/placiladokumenta/ID_DOKUMENTA

Stranke

Seznam strank

Metoda: GET URL: /api2/stranka

Posamezna stranka

Metoda: GET URL: /api2/stranka/view/ID_STRANKE

Dodajanje nove stranke

Metoda: POST URL: /api2/stranka/form

Parametri (označeni z * so obvezni):

Stranka:
- remote_id – id stranke v vašem programu
- drzava_id – id države iz šifranta držav, če pustimo prazno, je privzeto izbrana Slovenija
- naziv* – obvezen podatek
- naslov
- posta
- postnaSt
- davcna
- davcniZav – ali je davčni zavezanec 0/1
- maticna
- iban
- bic
- emajl – elektronski naslov stranke
- dniZapadlosti
- opomba
- telst
- pu – ali je proračunski uporabnik 0/1
- pravnafizicna – (1 = Pravna oseba, 2 = Fizična oseba)

Urejanje obstoječe stranke

Metoda: POST URL: /api2/stranka/form/ID_STRANKE

Parametri (označeni z * so obvezni):

Stranka:
- remote_id – id stranke v vašem programu
- drzava_id – id države iz šifranta držav, če pustimo prazno, je privzeto izbrana Slovenija
- naziv* – obvezen podatek
- naslov
- posta
- postnaSt
- davcna
- davcniZav – ali je davčni zavezanec 0/1
- maticna
- iban
- bic
- emajl – elektronski naslov stranke
- dniZapadlosti
- opomba
- telst
- pu – ali je proračunski uporabnik 0/1

Naslovi stranke

Metoda: GET URL: /api2/address/index/ID_STRANKE

Dodajanje novega naslova stranki

Metoda: POST URL: /api2/address/form

Parametri (označeni z * so obvezni):

Address
- stranka_id*
- naslov*
- posta
- postnaSt
- drzava_id*
- addresstype_id*

Urejanje obstoječega naslova stranke

Metoda: POST URL: /api2/address/form/ID_NASLOVA

Parametri (označeni z * so obvezni):

Address
- stranka_id*
- naslov*
- posta
- postnaSt
- drzava_id*
- addresstype_id*

Vozila stranke

Metoda: GET URL: /api2/vozila/index/ID_STRANKE

Vrne seznam vozil stranke, urejen po registrski številki. Če ID_STRANKE izpustite (/api2/vozila/index), vrne vsa vozila. Seznam vsebuje tudi neaktivna vozila (disabled = 1). Za vsako vozilo vrne podatke vozila (Vozila) in stranko (Stranka – id, naziv).

Če stranka ne obstaja, vrne napako “Žal ne najdem zahtevane stranke!”.

Posamezno vozilo

Metoda: GET URL: /api2/vozila/view/ID_VOZILA

Poleg podatkov vozila vrne še:

Stranka – id, naziv
Vdata – datumi vozila (npr. tehnični pregled), vrsta datuma je v Vdatumi.naziv
ServisnaPredloga – id, naziv

Datumi (garancijado, Vdata.datum) so v formatu d.m.Y.

Dodajanje novega vozila stranki

Metoda: POST URL: /api2/vozila/form

Parametri (označeni z * so obvezni):

Vozila
- stranka_id*
- disabled – ali je vozilo neaktivno 0/1
- registrskastevilka*
- lokacija
- proizvajalec
- model
- letnik
- internastevilka
- oprema
- opomba
- garancijado – datum v formatu d.m.Y ali Y-m-d
- opombagarancije
- pogoji
- servisna_predloga_id – id servisne predloge

V odgovoru je id novega vozila v data.Vozila.Vozilo.

Urejanje obstoječega vozila

Metoda: POST URL: /api2/vozila/form/ID_VOZILA

Parametri so enaki kot pri dodajanju vozila, vendar noben ni obvezen. Pošljete samo podatke, ki jih spreminjate, ostali ostanejo nespremenjeni. Primer, ki spremeni samo opombo:

{
   "Vozila":{
      "opomba":"Zamenjane zavorne ploščice"
   }
}

Če vozilo ne obstaja, vrne napako “Žal ne najdem zahtevanega dokumenta!” (v polju errors).

Artikli

Seznam artiklov

Metoda: GET URL: /api2/sifranti

Posamezni artikel

Metoda: GET URL: /api2/sifranti/view/ID_ARTIKLA

Stanje zaloge

Metoda: GET URL: /api2/sifranti/trenutnazaloga/ID_SKLADIŠČA/REZERVIRANAZALOGA(0|1)

Dodajanje novega artikla

Metoda: POST URL: /api2/sifranti/form

Parametri (označeni z * so obvezni):

Sifranti:
- sifra* – SKU koda oz. kot imate šifro v spletni trgovini. Mora biti unikatna za vsak izdelek.
- naziv*
- enota_id* – iz šifranta enot
- cenaBrezDDV*
- nabavnaCena – samo če je označeno polje vodiZalogo z 1
- ddv_id* – id ddv-ja iz šifranta ddv-ja
- vodiZalogo – ali vodim zalogo za artikel (samo če imam omogočeno materialno poslovanje) 0/1
- odo – obrnjena davčna obveznost
- teza – teža, v kg
- kategorije_id

Urejanje obstoječega artikla

Metoda: POST URL: /api2/sifranti/form/ID_ARTIKLA

Parametri (označeni z * so obvezni):

Sifranti:
- sifra* – SKU koda oz. kot imate šifro v spletni trgovini. Mora biti unikatna za vsak izdelek.
- naziv*
- enota_id* – iz šifranta enot
- cenaBrezDDV*
- nabavnaCena – samo če je označeno polje vodiZalogo z 1
- ddv_id* – id ddv-ja iz šifranta ddv-ja
- vodiZalogo – ali vodim zalogo za artikel (samo če imam omogočeno materialno poslovanje) 0/1
- odo – obrnjena davčna obveznost
- teza – teža, v kg

Seznam lotov

Metoda: GET URL: /api2/loti/index/ID_ARTIKLA

Dodajanje lotov

Metoda: POST URL: /api2/loti/form/ID_ARTIKLA

Parametri (označeni z * so obvezni):

Loti:
- sifra*
- roktrajanja
- enota_id* – iz šifranta enot
- aktiven

Vnos novega dokumenta (računa, predračuna)

Metoda: POST URL: /api2/glavadokumenta/form

V dokumentu mora biti obvezno podana tudi stranka. Če Quibi ne najde stranke jo ustvari. Stranko išče po polju id, remote_id oz. emajl. Stranko išče v naštetem vrstnem redu. Podan mora biti vsaj 1 parameter.

Postavke na dokumentu naštevamo. Cene in ostalih parametrov ne podajamo, saj se pobirajo direktno iz šifranta v Quibiju.

Parametri (označeni z * so obvezni):

Stranka:
- remote_id – id stranke v vašem programu
- drzava_id – id države iz šifranta držav, če pustimo prazno, je privzeto izbrana Slovenija
- stranka_id – id stranke iz šifranta strank. Če podamo to polje, ni potrebno podati ostalih polj od stranke.
- naziv* – obvezen podatek
- naslov
- posta
- postnaSt
- davcna
- davcniZav – ali je davčni zavezanec 0/1
- maticna
- iban
- bic
- emajl – elektronski naslov stranke
- dniZapadlosti
- opomba
- telst
- pu – ali je proračunski uporabnik 0/1
Dostava
- naziv
- naslov
- posta
- postnaTs
Glavadokumenta
- stevilcenje_id – id iz šifranta številčenj – glede na številčenje določimo vrsto dokumenta (račun, predračun)
- vrstaprodaje - obvezen podatek, glejte šifrant vrste prodaje
- stranka_id – če je podano to polje iz šifranta strank, potem ni potrebno podati polja Stranka, saj ga ne upošteva.
- dobavnica – če želimo razknjižit (pomanjšati) zalogo v skladišču, naredi skupaj z računom še dobavnico, v kolikor imamo materialno poslovanje – 0/1
- datIzdRac – datum izdaje dokumenta, podan v formatu Y-m-d (če ne izpolnite tega polja, bo vneslo današnji datum)
- datValute – datum valute, podan v formatu Y-m-d (če ne izpolnite tega polja, bo vneslo današnji datum)
- datstod – datum storitve od, če je dokument račun, mora biti podano to polje – datum je podan v formatu Y-m-d
- datstdo – če se gre za obdobje, izpolnimo še to polje – datum je podan v formatu Y-m-d
- kraj – kraj izdaje dokumenta
- nacinPlacila – način plačila iz šifranta način plačila
- space_id – v kolikor uporabljamo davčne blagajne, mora biti tukaj id davčne blagajne iz šifranta davčne blagajne
- skladisca_id – če uporabljamo materialno poslovanje, moramo vnesti id skladišča iz šifranta skladišč
- stroskovnamesta_id – stroškovno mesto iz šifranta stroškovnih mest
Postavkedokumenta
- 1
  - sifra – šifra artikla
  - kolicina – količina
  - popust – v kolikor je popust
  - ddv_id – iz šifranta DDV

Pri postavki dokumenta so obvezna polja sifra in kolicina. Če vodimo zalogo, lahko samo popust in ddv_id podate, v kolikor se razlikuje od original stopnje. Če se ne vodi zaloga artikla, potem so dovoljena polja še opis in cena.

Artikel seveda lahko dodate, tudi če ga nimate v šifrantu. V ta namen je potrebno podati vsa našteta polja:

enota_id
ddv_id
opis
kolicina
popust
cenaZDDV (cena je za enoto brez ddv)

Če bi radi zabeležili LOT, potem imate 2 možnosti:

Podate id lot-a: “loti_id”: 45
Podate naziv lot-a: “Loti.sifra”: “LOT-2026-001”

Prenos dokumenta (pdf)

Metoda: POST URL: /api2/glavadokumenta/pdf

Parametri (označeni z * so obvezni):

Glavadokumenta
- id* – id dokumenta
- natisni* – (1 – prikaz uporabniku, 3 – prenesi pdf)
- jezik – (sl – Slovenski, en – Angleški, it – Italjanski)

Vnos plačila

Metoda: POST URL: /api2/delnaplacila/placilo

Parametri (označeni z * so obvezni):

Delnaplacila
- model_id* – id dokumenta
- placilo* – znesek
- datumplacila* – datum placila
- nacinplacila* – iz šifranta plačil

Šifrant vrste prodaje

Opomba: aktualen seznam je vedno na voljo tudi preko GET /api2/glavadokumenta/vrstaprodaje.

1 - Dobava blaga in storitev
2 - Dobava blaga in storitev v Sloveniji od katerih obračuna DDV prejemnik
12 - Dobava storitev v druge države članice EU
3 - Dobava blaga v druge države članice EU
4 - Tristranske dobave blaga znotraj EU
5 - Dobava blaga znotraj EU po carinskih postopkih 42 in 63
6 - Dobava blaga znotraj EU po skladiščenju na odpoklic
7 - Prodaja blaga na daljavo
8 - Montaža in instaliranje blaga v drugi državi članici
15 - Lokalna dobava, reverse charge
9 - Oproščene dobave brez pravice do odbitka DDV
10 - Posebna ureditev za rabljeno blago
11 - Izvoz blaga izven EU
13 - Ne gre v knjigo DDV
14 - Oproščen promet s pravico do odbitka DDV
16 - Lokalna dobava blaga v drugi državi članici EU

Primeri (PHP)

Vnos novega dokumenta

<?php

$url = "https://si.quibi.net";
$username = "uporabniški@ime.si";
$password = "geslo";
$formdata = array(
    "Stranka" => array(
        "id" => 1,
        "naziv" => "Testna stranka"
    ) ,
    "Glavadokumenta" => array(
        "stevilcenje_id" => 1,
        "kraj" => "Kraj"
    ) ,
    "Postavkedokumenta" => array(
        1 => array(
            "sifra" => "test"
        )
    )
);
$opts = array(
    'http' => array(
        'method' => "POST",
        "content" => json_encode($formdata) ,
        'header' => "Content-Type: application/json\r\n" . "username: {$username}\r\n" . "password: {$password}\r\n"
    )
);
$ret = file_get_contents("$url/api2/glavadokumenta/form", false, stream_context_create($opts));
print_r(json_decode($ret));

Izpis šifranta številčenj

<?php

$url = "https://si.quibi.dev";
$username = "uporabniški@ime.si";
$password = "geslo";
$opts = array(
    'http' => array(
        'method' => "GET",
        'header' => "Content-Type: application/json\r\n" . "username: {$username}\r\n" . "password: {$password}\r\n"
    )
);

$ret = file_get_contents("$url/api2/stevilcenje", false, stream_context_create($opts));

print_r(json_decode($ret));

Avtomatizacija dokumentov

Za ustvarjanje dokumenta uporabite POST /api2/glavadokumenta/form. Glavadokumenta.stevilcenje_id določa vrsto dokumenta (na primer račun ali predračun); uporabnik potrebuje pravico za ustvarjanje te vrste. Uspešen odgovor vsebuje error: false, id (ID dokumenta) in ZapSt (številko). Ustrezno številčenje in pravice za integracijo nastavi skrbnik podjetja.

Za varen ponovni poskus po prekinitvi povezave pošljite svojo nespremenljivo referenco v Glavadokumenta.external_id (največ 128 znakov). Enaka referenca pri istem podjetju in enaka vsebina zahtevka vrne isti id in ZapSt ter replayed: true. Enaka referenca z drugačno vsebino vrne napako. Referenca ni obvezna za obstoječe odjemalce, vendar brez nje ponavljanje ustvarjanja ni varno. Pri ponovnem poskusu pošljite isto telo zahtevka. Referenca je ločena od uvoznega polja externalid.

Če je dokument vezan na vozilo, pošljite Glavadokumenta.vozila_id. Vozilo mora pripadati istemu podjetju in izbrani stranki. Seznam vozil dobite z GET /api2/vozila/index/ID_STRANKE, posamezno vozilo z GET /api2/vozila/view/ID_VOZILA. GET /api2/glavadokumenta/view/ID_DOKUMENTA vrne vozila_id in external_id.

{
  "Glavadokumenta": {
    "stevilcenje_id": 12,
    "vrstaprodaje": 1,
    "stranka_id": 1234,
    "vozila_id": 56,
    "external_id": "portal-potreba-567",
    "opomba": "Zajem potrebe #567"
  },
  "Postavkedokumenta": {
    "1": { "sifra": "ART-1", "kolicina": 2 }
  }
}

ID-ji in šifra v primeru so ponazoritve. Pri podanem Glavadokumenta.stranka_id mora stranka obstajati in pripadati podjetju; napačen ID vrne napako.

Urejanje dokumenta in postavk

POST /api2/glavadokumenta/form še naprej ustvarja vse vrste dokumentov glede na stevilcenje_id. Obstoječi POST /api2/glavadokumenta/form/ID_VIRNEGA_DOKUMENTA brez Glavadokumenta.id v telesu še naprej ustvari kopijo.

Za urejanje podprte vrste dokumenta pošljite Glavadokumenta.id v telesu na POST /api2/glavadokumenta/form ali POST /api2/glavadokumenta/form/ID_DOKUMENTA. Če je ID tudi v poti, se mora ujemati z ID v telesu. Pošljite celoten seznam Postavkedokumenta, ki nadomesti stare postavke; prazen seznam ni dovoljen. Zahtevana je pravica za urejanje vrste dokumenta. API preveri ista pravila urejanja kot pogled dokumenta: vrsto in stanje dokumenta, povezane dokumente, knjigo DDV, kasnejšo inventuro ter nastavitve podjetja (dovoliurejanje, dovoliurejanjedoktipi, urejajpovezanedokumente in lockdocuments). Dokumenta z dodeljenim FURS EOR in izdanega gotovinskega dokumenta ni mogoče urediti; pri drugih zaključenih ali izdanih dokumentih odločajo pravila za vrsto, datum in nastavitve. Predračuna, iz katerega je že nastal račun, ni mogoče urediti. Ob zavrnitvi API vrne razloge. Številka, številčenje in external_id ostanejo nespremenjeni. Odgovor vsebuje id in ZapSt; rezultat ponovno preberite z GET /api2/glavadokumenta/view/ID_DOKUMENTA.

Pri urejanju lahko spremenite stranka_id, vozila_id, opomba, opombaglava, datIzdRac, datValute, datstod, datstdo, kraj, vrstaprodaje, nacinPlacila, stroskovnamesta_id, poslovneenote_id in komercialist_id. stevilcenje_id lahko podate le z nespremenjeno vrednostjo. Ostala polja glave API pri urejanju prezre.

Pošiljanje dokumenta po e-pošti

POST /api2/glavadokumenta/send/ID_DOKUMENTA sprejme JSON z obveznim email ter neobveznima zadeva in vsebina. Uporabi privzetega pošiljatelja podjetja in dokument pošlje kot PDF prek obstoječega workerja. Odgovor vrne send_id in status: queued. Z GET /api2/glavadokumenta/send_status/ID_DOKUMENTA?send_id=ID_POSILJANJA preverite queued, sent ali failed in polje napaka. Brez send_id se vrne zadnji API poskus za ta dokument. sent pomeni, da je poštni strežnik sprejel sporočilo; ne potrjuje prejema ali branja pri naslovniku.

Artikli iz portala

Šifrant berite z GET /api2/sifranti, posamezen artikel z GET /api2/sifranti/view/ID_ARTIKLA. Nov artikel ustvarite z POST /api2/sifranti/form; odgovor vsebuje data.Sifranti.Sifrant (ID). Obstoječega popravite z POST /api2/sifranti/form/ID_ARTIKLA. Podajte vsaj Sifranti.sifra, naziv, enota_id, ddv_id, cenaBrezDDV in vrsto vodiZalogo; preverite vrnjene validacijske napake. Sezname dobite z GET /api2/enota, GET /api2/ddv in GET /api2/kategorije. kategorije_id je neobvezen. Pravilo predpone šifer in privzeto kategorijo določi skrbnik podjetja. API artikla ne dodeli samodejno zunanje reference; remote_id ni del dovoljenih polj za shranjevanje artikla. Sprememba cene v šifrantu ne spremeni že shranjenih cen na dokumentih. Postavka brez šifre ostane na dokumentu in ne ustvari artikla v šifrantu.

Ločen API osnutka brez številke ni dokumentiran za vse vrste dokumentov. Preizkusno okolje, omejitve pogostosti klicev in konkretne pravice uporabnika so odvisni od namestitve; za integracijo jih potrdi skrbnik Quibija pred povezavo v produkcijo.