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. O spremembah zaloge vas Quibi lahko obvešča sam - glejte Webhooki. Bančne izpiske lahko uvažate in povezujete z dokumenti – glejte Banka.
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
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
Pri shranjevanju dokumenta (/api2/glavadokumenta/form) lahko dobite začasno napako, ko je zaloga podjetja ravno v usklajevanju ali dokument hkrati obdeluje druga operacija:
{
"error":true,
"message":"Dokument trenutno obdeluje druga operacija. Poskusite znova čez nekaj sekund.",
"request_id":"ba0b1b11ca158af9"
}
Sporočilo je lahko tudi »Zaloga artikla se trenutno usklajuje. Poskusite znova čez nekaj sekund.« V obeh primerih dokument ni bil shranjen. Zahtevek ponovite čez nekaj sekund. Vrednost request_id navedite, če napako javljate podpori.
Pri ponovitvah vedno pošljite isti external_id v Glavadokumenta. Če povezava med shranjevanjem pade (časovna omejitev odjemalca), ponovitev z istim external_id vrne že shranjen dokument in ne ustvari dvojnika. Brez external_id lahko ponovitev ustvari drugi dokument.
Uporabljajte samo klice, ki so navedeni v teh navodilih. API ne pozna drugih poti, tudi če so sestavljene po istem vzorcu.
- Oblika poti je
/api2/<sklop>/<akcija>/ID. ID nikoli ne sledi neposredno sklopu:/api2/stranka/view/123je pravilno,/api2/stranka/123ne obstaja. - Pošljite glavi
usernameinpasswordterContent-Type: application/json. GlaveAccept: application/jsonne pošiljajte: nekateri klici (na primer/api2/glavadokumenta/view) potem vrnejo odgovor, ovit v{"response": ...}. Oblika, opisana v teh navodilih, velja za zahtevke brez te glave. - Vedno preverite polje
error. Napačna prijava vrne HTTP 200 z"error": truein sporočilom »Napačni podatki za prijavo!«. - Vsak klic zahteva enako pravico kot ustrezna stran v spletnem programu (glejte tabelo spodaj). Brez pravice dobite HTTP 403 z
"error": true. Zapis drugega podjetja se obravnava kot neobstoječ. - Neobstoječa pot vrne HTTP 404:
{
"error":true,
"message":"Klic API ne obstaja. Podprti klici so opisani na https://navodila.quibi.net/za-razvijalce/",
"request_id":"ba0b1b11ca158af9"
}
- Ob nepričakovani napaki dobite HTTP 500 (ali 503, ko storitev začasno ni na voljo) z
"error": trueinrequest_id. Vrednostrequest_idnavedite, ko napako javljate podpori.
| Napačno | Pravilno |
|---|---|
/api2/stranka/ID | /api2/stranka/view/ID |
/api2/sifranti/artikli, /api2/sifranti/cena | /api2/sifranti/seznam (cene so v podatkih artikla), posamezen artikel /api2/sifranti/view/ID |
/api2/cenik/ID, /api2/cenik/view/ID, /api2/sifranti/ceniki, /api2/stranka/ceniki | /api2/cenik vrne vse cenike skupaj z artikli (Artiklicenika) |
/api2/glavadokumenta/seznam | /api2/fakture, /api2/predracuni … (glejte Seznam dokumentov) |
/api2/loti/ID | /api2/loti/index/ID_ARTIKLA |
Pri šifrantih, ki jih potrebujete za vnos dokumenta, zadošča tudi katerakoli pravica za dodajanje dokumentov (kot pri spustnih seznamih v obrazcu dokumenta).
| Metoda | URL | Pravica |
|---|---|---|
| GET | /api2/ddv, /api2/drzava, /api2/enota, /api2/addresstype | – |
| GET | /api2/tecajnice/seznamvalut, /api2/tecajnice/tecaj/OZNAKA | – |
| GET | /api2/users (samo lasten zapis) | – |
| GET | /api2/glavadokumenta/placila, /api2/glavadokumenta/vrstaprodaje | – |
| GET | /api2/skladisca | materialno poslovanje |
| GET | /api2/spaces | davčne blagajne |
| GET | /api2/stevilcenje | Številčenje ali dodajanje dokumentov |
| GET | /api2/statusi | Statusi ali dodajanje dokumentov |
| GET | /api2/stroskovnamesta | Stroškovna mesta ali dodajanje dokumentov |
| GET | /api2/analitika | Analitika ali dodajanje dokumentov |
| GET | /api2/kategorije | Kategorije ali dodajanje dokumentov |
| POST | /api2/kategorije/form, /api2/kategorije/form/ID | Kategorije |
| GET | /api2/cenik | Ceniki ali dodajanje dokumentov |
| GET | /api2/sifranti/seznam, /api2/sifranti/view/ID | Šifranti ali dodajanje dokumentov |
| POST | /api2/sifranti/form, /api2/sifranti/form/ID | Vnos šifrantov |
| GET | /api2/sifranti/trenutnazaloga/ID_SKLADIŠČA/0|1 | Poročila šifrantov, materialno poslovanje |
| GET | /api2/loti/index/ID_ARTIKLA | Šifranti |
| POST | /api2/loti/form/ID_ARTIKLA | Vnos lotov |
| GET | /api2/stranka, /api2/stranka/view/ID | Stranke ali dodajanje dokumentov |
| POST | /api2/stranka/form | Vnos strank ali dodajanje dokumentov |
| POST | /api2/stranka/form/ID | Vnos strank |
| GET | /api2/address/index/ID_STRANKE | – (stranka mora biti vaša) |
| POST | /api2/address/form | Vnos strank ali dodajanje dokumentov |
| POST | /api2/address/form/ID | Vnos strank |
| GET/POST | /api2/vozila/index/ID_STRANKE, /api2/vozila/view/ID, /api2/vozila/form | – (stranka mora biti vaša) |
| POST | /api2/fakture, /api2/predracuni … | pravica za vrsto dokumenta |
| GET | /api2/glavadokumenta/view/ID | pravica za vrsto dokumenta |
| POST | /api2/glavadokumenta/preklici/ID, /api2/glavadokumenta/zakljuci/ID | urejanje naročil kupcev |
| POST | /api2/glavadokumenta/form | dodajanje oziroma urejanje vrste dokumenta |
| POST | /api2/glavadokumenta/form/ID_IZVORNEGA_DOKUMENTA | dodajanje vrste novega dokumenta (kopija ali storno) |
| POST | /api2/glavadokumenta/pdf | pravica za vrsto dokumenta |
| POST | /api2/glavadokumenta/eslog | pravica za vrsto dokumenta |
| POST/GET | /api2/glavadokumenta/send/ID, /api2/glavadokumenta/send_status/ID | pravica za vrsto dokumenta |
| GET | /api2/delnaplacila/placiladokumenta/ID_DOKUMENTA | – (dokument mora biti vaš) |
| GET/POST | /api2/urlpovezave/index/ID_DOKUMENTA, /api2/urlpovezave/add/ID_DOKUMENTA, /api2/urlpovezave/edit/ID, /api2/urlpovezave/delete/ID | pravica za vrsto dokumenta (ogled) |
| GET/POST | /api2/transakcijskiracuni, /api2/bancniizpiski … (glejte Banka) | Banka |
| POST | /api2/delnaplacila/placilo | – (dokument mora biti vaš; plačilo na negotovinski dokument zahteva posebno nastavitev uporabnika) |
Metoda: GET URL: /api2/ddv
Metoda: GET URL: /api2/drzava
Metoda: GET URL: /api2/enota
Metoda: GET URL: /api2/glavadokumenta/placila
Metoda: GET URL: /api2/skladisca Opomba: samo v primeru, da imamo vključeno materialno poslovanje.
Metoda: GET URL: /api2/spaces Opomba: samo v primeru, če imate vključene davčne blagajne.
Metoda: GET URL: /api2/stevilcenje
Če dodate parameter ?glavadokumenta=1, potem izpiše vsa številčenja.
Metoda: GET URL: /api2/stroskovnamesta
Metoda: GET URL: /api2/addresstype
Metoda: GET URL: /api2/cenik
Vrne vse cenike podjetja, vsak s seznamom artiklov (Artiklicenika: sifranti_id, cenaBrezDDV, popust). Posameznega cenika ali cenikov stranke ne kličete posebej.
Metoda: GET URL: /api2/kategorije
Metoda: POST URL: /api2/kategorije/form
Parametri (označeni z * so obvezni):
- Kategorije:
- naziv*
Metoda: GET URL: /api2/glavadokumenta/vrstaprodaje
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)
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
- ordernumber – »Št. naročila« (točno ujemanje). Najde dokument s to številko in dokument (npr. račun ali dobavnico), izdelan iz naročila kupca s to številko.
- storniran – 0/1 – pri naročilih kupcev: ali je naročilo preklicano
- zakljucen – 0/1 – ali je dokument zaključen
- izdan – 0/1 – ali je dokument izdan
- spremenjeno_od – datum ali čas zadnje spremembe v obliki
Y-m-daliY-m-d H:i:s(vrne dokumente, spremenjene od tega trenutka)
Če ne podate nobenega filtra, API vrne dokumente tekočega leta. Neveljavna vrednost filtrov ordernumber, storniran, zakljucen, izdan ali spremenjeno_od vrne HTTP 400.
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.
Glava vsakega dokumenta vsebuje tudi:
- external_id – vaša referenca iz vnosa dokumenta
- sklic – sklic za plačilo
- ordernumber – »Št. naročila«
- izdan – ali je dokument izdan
- zakljucen – ali je dokument zaključen
- storniran – pri naročilu kupca: ali je preklicano
- created, modified – čas vnosa in zadnje spremembe
Naročilo kupca, preklicano v Quibiju (»Prekliči naročilo«), ima storniran: true. Preklicano naročilo ne rezervira več zaloge. Spremembe najlaže spremljate tako, da občasno pokličete POST /api2/narocilakupcev s filtrom spremenjeno_od (čas zadnjega preverjanja) in pregledate storniran ter zakljucen:
{"Filtriraj": {"spremenjeno_od": "2026-11-13 08:00:00", "storniran": 1}}
Metoda: GET URL: /api2/glavadokumenta/view/ID_DOKUMENTA
Glava vsebuje enaka dodatna polja kot seznam (ordernumber, izdan, zakljucen, storniran, created, modified). Odgovor poleg Dokumenti vsebuje:
Povezanidokumenti– dokumenti, iz katerih je ta dokument izdelan (npr. dobavnica ali naročilo kupca pri računu)NarocilaKupcev– naročila kupcev, povezana s tem dokumentomIzdelaniDokumenti– dokumenti, izdelani iz tega dokumenta (npr. račun in dobavnica iz naročila kupca): id, glava_id, ZapSt, datIzdRac, znesek, ordernumber, izdan, zakljucen, storniranPovezave– povezave (URL) dokumenta, enaka polja kot pri povezavah dokumenta
Iz spletnega naročila tako pridete do računa: poiščite naročilo kupca s Filtriraj.ordernumber, nato v IzdelaniDokumenti poiščite zapis z glava_id: 1 (račun). Račun lahko poiščete tudi neposredno: POST /api2/fakture s Filtriraj.ordernumber.
Metoda: POST URL: /api2/glavadokumenta/preklici/ID_DOKUMENTA
Naredi isto kot »Prekliči naročilo« v programu: naročilo dobi storniran: true in ne rezervira več zaloge. Deluje samo za naročilo kupca, zahteva pravico za urejanje naročil kupcev. Telo zahtevka ni potrebno. Ponovljen klic je varen in vrne enako stanje.
{"error":false,"message":"","data":{"Glavadokumenta":{"id":"2202401","ZapSt":"T-304\/2026","ordernumber":"2026-00001","storniran":true,"zakljucen":false,"modified":"2026-11-13 14:52:25"}}}
Za dokument druge vrste API vrne HTTP 400, za neobstoječ dokument HTTP 404, za GET HTTP 405.
Metoda: POST URL: /api2/glavadokumenta/zakljuci/ID_DOKUMENTA
Naredi isto kot »Zaključi« v programu (zakljucen: true). Pravila in odgovor so enaki kot pri preklicu.
Metoda: GET URL: /api2/delnaplacila/placiladokumenta/ID_DOKUMENTA
Dokumentu lahko dodate povezave do zunanjih strani ali datotek, npr. do primera in fotografij v vašem programu. Datoteke tako ostanejo pri vas, v Quibiju je samo povezava. Povezave so vidne v zavihku »Povezave« na dokumentu. Za vse klice potrebujete pravico za ogled vrste dokumenta, dokument mora biti vaš.
Polja povezave:
| Polje | Opis |
|---|---|
| id | id povezave v Quibiju |
| url | spletni naslov; dovoljena sta samo http:// in https://, največ 2048 znakov |
| naziv | prikazano ime povezave (neobvezno, največ 255 znakov) |
| zunanji_id | vaš ključ povezave, npr. id primera (neobvezno, največ 100 znakov) |
| user_id, dodal | uporabnik, ki je povezavo dodal, in njegovo ime |
| created, modified | čas dodajanja in zadnje spremembe |
Metoda: GET URL: /api2/urlpovezave/index/ID_DOKUMENTA
{"error":false,"message":"","data":{"Povezave":[{"id":15,"url":"https:\/\/servis.example.com\/primeri\/123","naziv":"Fotografije vozila","zunanji_id":"primer-123","user_id":42,"dodal":"Ana Novak","created":"2026-11-13 10:15:00","modified":"2026-11-13 10:15:00"}]}}
Metoda: POST URL: /api2/urlpovezave/add/ID_DOKUMENTA
{"url": "https://servis.example.com/primeri/123", "naziv": "Fotografije vozila", "zunanji_id": "primer-123"}
Če pošljete zunanji_id, ki ga dokument že ima, Quibi obstoječo povezavo posodobi (url in naziv) in ne doda nove. Tako lahko isti klic varno ponovite ali z njim posodabljate povezavo, ne da bi hranili Quibijev id. Brez zunanji_id vsak klic doda novo povezavo. Odgovor vsebuje obstaja (true, če je povezava že obstajala) in Povezava:
{"error":false,"message":"","data":{"obstaja":false,"Povezava":{"id":15,"url":"https:\/\/servis.example.com\/primeri\/123","naziv":"Fotografije vozila","zunanji_id":"primer-123","user_id":42,"dodal":"Ana Novak","created":"2026-11-13 10:15:00","modified":"2026-11-13 10:15:00"}}}
Metoda: POST URL: /api2/urlpovezave/edit/ID_POVEZAVE
{"url": "https://servis.example.com/primeri/123/priloge", "naziv": "Priloge"}
Polje, ki ga ne pošljete, ostane nespremenjeno. Odgovor je enak kot pri dodajanju.
Metoda: POST URL: /api2/urlpovezave/delete/ID_POVEZAVE
{"error":false,"message":"Povezava je odstranjena.","data":{"id":15}}
Za neveljaven URL API vrne HTTP 400 (errors vsebuje napake po poljih), za neobstoječ ali tuj dokument oziroma povezavo HTTP 404, za GET pri dodajanju, urejanju in brisanju HTTP 405. Povezave se izbrišejo skupaj z dokumentom in se ne prenesejo na dokument, narejen iz tega dokumenta.
Metoda: GET URL: /api2/stranka
Vrne vse nearhivirane stranke s podatki iz polja Stranka, državo (Drzava) in naslove (Address).
Polja Stranka:
| Polje | Opis |
|---|---|
| id, remote_id | id v Quibiju, id v vašem programu |
| naziv, popolniNaziv | naziv; naziv z oznako (P)/(F) in davčno |
| vrstastranke | 1 – kupec, 2 – dobavitelj, 3 – kupec/dobavitelj |
| pravnafizicna | 1 – pravna oseba, 2 – fizična oseba |
| drzava_id, davcna, davcniZav, maticna, pu | država, davčna številka, davčni zavezanec, matična številka, proračunski uporabnik |
| iban, bic, bic_ovojnica | TRR stranke, BIC, BIC za ovojnico e-računa |
| emajl, telst, spletnastran | kontakt |
| cenik_id | id cenika (/api2/cenik) |
| dniZapadlosti, dniZapadlostiPr | dni do zapadlosti za izdane oziroma prejete račune |
| nacinPlacila | privzeti način plačila |
| trrplacila | vaš TRR, na katerega stranka plačuje |
| jezik | jezik dokumentov (sl, en, it, hr, de); prazno – privzeti |
| prejemanjeracunov | 1 – po klasični pošti, 2 – po klasični in e-pošti, 3 – po e-pošti |
| 0 – ni določeno, 1 – PDF brez UPN QR, 2 – PDF z UPN QR | |
| eslog | 0 – ni določeno, 1 – eRačun eSlog (XML), 2 – paket UJP (ZIP), 3 – paket (ZIP) |
| vrstaReferencnegaDokumenta, stevilkaReferencnegaDokumenta, datumReferencnegaDokumenta | referenčni dokument za e-račun (npr. pogodba) |
| prikaziopozorilo, besediloopozorila, barvaopozorila | opozorilo, ki se pokaže ob izbiri stranke |
| opomba, opombe_id | opomba stranke, privzeta opomba iz šifranta opomb |
| sifratujiprogram | šifra stranke v drugem programu |
| arhivirano | ali je stranka arhivirana (v seznamu vedno 0) |
| stRacunov, stPredracunov, promet | število računov, predračunov in promet |
| created, modified | čas vnosa in zadnje spremembe |
Polja naslova (Address): id, addresstype_id (/api2/addresstype), naziv, naslov, posta, postnaSt, drzava_id, gln, emajl, telst, popolniNaziv, created, modified.
Polja, dodana kasneje, so na koncu zapisa. Vaš program naj neznana polja prezre, saj lahko dodamo nova.
Metoda: GET URL: /api2/stranka/view/ID_STRANKE
Vrne ista polja kot seznam (tudi za arhivirano stranko) in še:
Contact– kontaktne osebe: id, name, surname, jobtitle, birthday, comment; v vsakiContactphone(number, type) inContactemail(email, type)Strankeemaili– dodatni naslovi za pošiljanje dokumentov: vrsta_dokumenta (vrsta dokumenta, prazno – vsi), tip (TOaliCC), email, sortDdvclanstvo– članstvo v skupini za DDV: datum_od, datum_do,Ddvskupina(id, naziv, davcna)Tag– oznake stranke: id, naziv
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)
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
Metoda: GET URL: /api2/address/index/ID_STRANKE
Metoda: POST URL: /api2/address/form
Parametri (označeni z * so obvezni):
- Address
- stranka_id*
- naslov*
- posta
- postnaSt
- drzava_id*
- addresstype_id*
Metoda: POST URL: /api2/address/form/ID_NASLOVA
Parametri (označeni z * so obvezni):
- Address
- stranka_id*
- naslov*
- posta
- postnaSt
- drzava_id*
- addresstype_id*
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!”.
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.
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.
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).
Metoda: GET URL: /api2/sifranti/seznam
Artikli se vračajo po straneh, urejeni po ID-ju. Parametri (v URL-ju, vsi neobvezni):
- po – ID zadnjega artikla s prejšnje strani (privzeto 0 = od začetka)
- limit – število artiklov na stran, 1 do 500 (privzeto 500)
- spremenjeno_od – samo artikli, spremenjeni od tega trenutka naprej, v obliki
LLLL-MM-DD UU:MM:SS(za sprotno usklajevanje) - arhivirano – 0 (privzeto) vrne aktivne artikle, 1 arhivirane
Odgovor:
{
"error":false,
"message":"",
"data":{
"Sifranti":[
{ "Sifranti":{ "id":"1234", "sifra":"A-1", "naziv":"..." }, "Ddv":{...}, "Enota":{...}, "Kategorije":{...}, "Variableproduct":{...} }
]
},
"naslednji_po":1234,
"limit":500
}
Prvo stran dobite z GET /api2/sifranti/seznam, naslednjo z GET /api2/sifranti/seznam?po=NASLEDNJI_PO (vrednost naslednji_po iz prejšnjega odgovora). Ko je naslednji_po enak null, ste prebrali vse artikle. Napačna vrednost parametra vrne HTTP 400.
Metoda: GET URL: /api2/sifranti/view/ID_ARTIKLA
Metoda: GET URL: /api2/sifranti/trenutnazaloga/ID_SKLADIŠČA/REZERVIRANAZALOGA(0|1)
Pogoji in napake:
- ID skladišča je obvezen in mora biti skladišče vašega podjetja (sicer napaka “Žal ne najdem zahtevanega dokumenta!”).
- Uporabnik potrebuje pravico Šifranti - poročila. Brez nje dobi HTTP 403 z
{"error": true, "message": "Za dostop do te opcije nimate zadostnih pravic!"}. - Podjetje mora imeti vključeno vodenje zaloge (materialno poslovanje).
- Rezervirana zaloga je stolpec
stRezZalogein se doda samo pri vrednosti1.
Za sprotno obveščanje o spremembah zaloge in za branje stanja po straneh z različicami uporabite webhooke.
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
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
Metoda: GET URL: /api2/loti/index/ID_ARTIKLA
Metoda: POST URL: /api2/loti/form/ID_ARTIKLA
Parametri (označeni z * so obvezni):
- Loti:
- sifra*
- roktrajanja
- enota_id* – iz šifranta enot
- aktiven
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.
- address_id – naslov stranke (npr. sedež podjetja) iz
GET /api2/stranka/view/ID_STRANKE; če ga ne podate, se vzame prvi naslov stranke - prejemnik_id in prejemnikaddress_id – prejemnik in njegov naslov za dostavo (npr. lokal), velja za vse vrste dokumentov, tudi dobavnice in naročila kupcev. Stranka in njen naslov ostaneta naslov za račun. Prejemnik je lahko ista stranka z drugim naslovom. Stranke in naslovi morajo pripadati vašemu podjetju, sicer API vrne napako. Blok
Dostavaje namenjen le, kadar stranke ne podate z ID-jem: takrat Quibi naslov za dostavo išče po nazivu in ga po potrebi ustvari. - 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
- ordernumber – »Št. naročila«, na primer številka naročila v vaši spletni trgovini (besedilo). Po njem lahko kasneje iščete (glejte Seznam dokumentov).
- Postavkedokumenta
- 1
- sifra – šifra artikla
- kolicina – količina
- popust – v kolikor je popust
- ddv_id – iz šifranta DDV
- 1
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.
Namesto sifra lahko artikel podate z ID-jem v sifra_id ali sifranti_id (na primer vrednost iz GET /api2/glavadokumenta/view). Artikel mora pripadati vašemu podjetju ter ne sme biti izbrisan ali arhiviran, sicer API vrne napako za to postavko. Pri urejanju dokumenta je dovoljen tudi arhiviran artikel, če je že na tem dokumentu.
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
- cenaBrezDDV – cena za enoto brez DDV (obvezna)
Polja cenaZDDV ne pošiljajte; Quibi ga izračuna sam.
kolicina, cenaBrezDDV in popust pošljite kot JSON število (2, 2.5) ali kot niz z decimalno piko ali vejico ("2.5", "2,5"). Ločila tisočic ("1 000"), eksponent ("1e3") in drugo besedilo niso dovoljeni.
| Polje | Ni podano, null ali "" | 0 |
|---|---|---|
kolicina | Če polja ni, je količina 1. null ali "" vrne napako. | Dovoljeno. |
cenaBrezDDV (artikel iz šifranta) | Uporabi se cena iz šifranta. | Postavka ima ceno 0. |
cenaBrezDDV (postavka brez artikla) | Napaka, cena je obvezna. | Postavka ima ceno 0. |
popust | Brez popusta. | Brez popusta. |
API pred shranjevanjem preveri vse postavke. Če je katera neveljavna, ne ustvari ali spremeni ničesar, tudi nove stranke ne. Odgovor navede vse napake naenkrat:
{
"error": true,
"errors": ["Postavka 2: polje kolicina mora biti število (npr. 2 ali 2.5)."],
"field_errors": [{ "postavka": "2", "polje": "kolicina", "koda": "invalid_number" }],
"request_id": "a1b2c3d4e5f60718"
}
postavka je ključ postavke iz vašega zahtevka. Možne vrednosti koda so invalid_number, required, not_found, invalid_id, invalid_value in invalid_line. Ko prijavljate napako podpori, navedite request_id.
Č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”
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)
Ob uspehu API vrne datoteko PDF. Če manjka obvezen parameter, vrne HTTP 400, če dokumenta ni mogoče najti ali pripraviti, pa HTTP 404 – v obeh primerih z JSON odgovorom {"error": true, "errors": "..."}.
Metoda: POST URL: /api2/glavadokumenta/eslog
Enako kot »eRačun eSlog (XML)« in »eRačun paket« pri tiskanju v programu. Na voljo je za račun, predračun, dobavnico, dobropis in avansni račun.
Parametri (označeni z * so obvezni):
- Glavadokumenta
- id* – id dokumenta
- format –
xml(privzeto) alizip - ujp – samo pri
zip: 1 (privzeto) – paket UJP z ovojnico, 0 – navaden paket
{"Glavadokumenta": {"id": 2202399, "format": "xml"}}
Odgovor:
xml– datoteka eSlog 2.0 (application/xml). Za dobavnico vrne eSlog dobavnice. Če je dokument še osnutek, ga prenos izda (dodeli številko), enako kot v programu. Zato XML zahtevajte šele, ko je dokument dokončan.zip– paket z XML, PDF in ovojnico (application/zip). Paket dokumenta ne izda. Če za e-račun manjkajo podatki (npr. matična številka, IBAN ali BIC stranke), API vrne HTTP 400 in seznam manjkajočih podatkov verrors.
Ime datoteke je v glavi Content-Disposition. Napake: 400 – manjka id, napačen format ali nepodprta vrsta dokumenta; 404 – dokumenta ni; 405 – klic ni POST.
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
- potrdiprihodnjidatum – 1, če je datum plačila v prihodnosti namenoma; brez tega API plačilo z datumom po današnjem zavrne z napako v
errors.datumplacila
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
<?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));
<?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));
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.
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. Kopija prevzame »Št. naročila« (ordernumber) izvornega dokumenta, razen če ga podate v zahtevku.
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, komercialist_id in ordernumber. stevilcenje_id lahko podate le z nespremenjeno vrednostjo. Ostala polja glave API pri urejanju prezre.
Dokument stornirate tako, da iz njega ustvarite nov dokument z nasprotnimi količinami. Izvorni dokument ostane nespremenjen. Račun stornirate z dobropisom, dobavnico pa z novo dobavnico.
Metoda: POST URL: /api2/glavadokumenta/form/ID_IZVORNEGA_DOKUMENTA
Parametri v Glavadokumenta (označeni z * so obvezni):
| Polje | Opis |
|---|---|
storniraj* | Vrednost 1. |
stevilcenje_id* | Določa vrsto novega dokumenta: pri računu številčenje dobropisa, pri dobavnici številčenje dobavnice. Seznam dobite z GET /api2/stevilcenje. |
stranka_id* | Stranka se iz izvornega dokumenta ne prevzame. Namesto tega polja lahko pošljete podatke v Stranka. |
skladisca_id | Če uporabljate materialno poslovanje. Skladišče se iz izvornega dokumenta ne prevzame. |
space_id | Če uporabljate davčne blagajne. Blagajna se iz izvornega dokumenta ne prevzame. |
dobavnica | 1, če naj dobropis sam vrne artikle na zalogo. Privzeto 0. |
storno_dobavnica_id | ID storno dobavnice, ki naj se poveže z dobropisom. |
Neobvezna so še polja nacinPlacila, vrstaprodaje, datIzdRac, datValute in datstod. Če jih ne pošljete, veljajo enake privzete vrednosti kot pri novem dokumentu in se iz izvornega dokumenta ne prevzamejo. Datumi so privzeto današnji.
Postavkedokumenta ne pošiljajte. Quibi prevzame postavke in opombo iz izvornega dokumenta ter količinam obrne predznak. Dobropis se samodejno veže na račun.
Če so na dobropisu artikli z zalogo, pošljite natanko eno od polj dobavnica: 1 ali storno_dobavnica_id. Sicer API vrne napako, da morate dokumentu dodati dobavnico.
Odgovor je enak kot pri novem dokumentu in vsebuje id in ZapSt novega dokumenta.
Primer: storno računa z ID-jem 5001, ki sam vrne zalogo:
POST /api2/glavadokumenta/form/5001
{
"Glavadokumenta": {
"storniraj": 1,
"stevilcenje_id": 7,
"stranka_id": 1234,
"skladisca_id": 2,
"dobavnica": 1
}
}
Račun z ločeno dobavnico stornirate v dveh klicih. Najprej stornirajte dobavnico (ID 4001):
POST /api2/glavadokumenta/form/4001
{
"Glavadokumenta": {
"storniraj": 1,
"stevilcenje_id": 3,
"stranka_id": 1234,
"skladisca_id": 2
}
}
Nato ustvarite dobropis računa in v storno_dobavnica_id pošljite id iz odgovora prvega klica:
POST /api2/glavadokumenta/form/5001
{
"Glavadokumenta": {
"storniraj": 1,
"stevilcenje_id": 7,
"stranka_id": 1234,
"skladisca_id": 2,
"storno_dobavnica_id": 4002
}
}
ID-ji v primerih so ponazoritve.
Polja external_id pri tem klicu ne pošiljajte, saj API vrne napako »Neveljaven external_id.«. API tudi ne preveri, ali je dokument že storniran, zato vsak ponovljen klic ustvari nov storno dokument. Če se povezava prekine, pred ponovitvijo preverite, ali je dokument že nastal, na primer v seznamu /api2/dobropisi.
Ločene poti za storno (/api2/glavadokumenta/storniraj) ni. Storno računa za predplačilo in preklic naročila kupca naredite v spletnem programu.
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.
Šifrant berite po straneh z GET /api2/sifranti/seznam (glejte Seznam artiklov), 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.