Što je Kigo Cloud API

Kigo Cloud API je programsko sučelje (REST, format JSON) preko kojega se vanjski sustavi povezuju s vašim Kigo Cloud računom. Najčešće ga koriste webshopovi i drugi poslovni programi za automatsku razmjenu podataka: sinkronizaciju artikala i zaliha, prijenos klijenata te izradu i fiskalizaciju računa izravno iz narudžbi, bez ručnog prepisivanja.

Osnovne informacije

Do interaktivne dokumentacije dolazite i iz aplikacije: Opcije → Integracije → API Dokumentacija.

Autentikacija

Svaki poziv šalje dva zaglavlja (header):

• X-USERNAME: korisničko ime, isto ono kojim se prijavljujete u Kigo Cloud.
• X-PASSWORD: lozinka istog korisnika kao MD5 sažetak (32 znamenke), nikad kao čisti tekst.

Korisnički račun mora biti aktivan. Primjer poziva koji dohvaća popis artikala:

curl -H "X-USERNAME: vase-korisnicko-ime" -H "X-PASSWORD: md5-hash-lozinke" https://app.kigo.cloud/hr/api/v1/item/list

Svi dostupni pozivi

Grupe artikala

Artikli

Klijenti

Računi i ponude

Načini i statusi plaćanja

Izrada računa kroz API

Najvažniji poziv za webshopove je POST invoice/create. Ključna polja:

• pin: PIN aktivnog djelatnika; dokument dobiva tog operatera. Obavezno.
• pos_type: 1 račun, 2 ponuda (zadano), 3 servisna ponuda, 4 nabavna ponuda. Za pravi račun obavezno pošaljite 1.
• payment: G gotovina, T transakcijski (zadano), K kartica, O ostalo. Za karticu pošaljite i id_payment_card, a za ostalo id_payment_other: ID-evi iz paymentCard/list i paymentOther/list, nepostojeći ID vraća grešku. Gotovina, kartica i ostalo odmah se označavaju plaćenima; transakcijski račun ostaje neplaćen dok uplatu ne evidentirate. Samo dokumenti s T mogu se kasnije slati kao eRačun.
• items: stavke računa, najviše 200 po dokumentu. Artikl se traži po šifri (reference); ako šifra nije poslana, po nazivu (item_name). Ako se ne pronađe, automatski se kreira novi artikl u vašem šifrarniku: s poslanom ili dodijeljenom šifrom, PDV-om iz vat_percent ili 25% i općom grupom. Ista šifra poslana dvaput zbraja količine na jednoj stavci. Sve cijene šalju se s uključenim PDV-om; bez poslane cijene vrijedi prodajna cijena artikla. item_name uz postojeći artikl mijenja naziv samo na toj stavci računa, ne i u šifrarniku.
• Rabati: ako pošaljete discount_percent, vrijedi točno taj postotak (0 znači bez rabata). Ako rabat ne pošaljete, a poslana cijena je niža od prodajne cijene artikla, razlika se na računu automatski iskazuje kao rabat. Cijena 0 znači gratis stavku (rabat 100%). Uz apply_client_discounts stavke koje su ostale bez rabata dobivaju rabat klijenta, a ako ga klijent nema, rabat grupe artikla.
• client: obrađuje se samo ako sadrži oib; po njemu se kupac prepoznaje, a ako ne postoji, automatski se kreira iz poslanih podataka (naziv, adresa, kontakt, e-mail). Bez OIB-a račun se izdaje bez kupca, što je za maloprodajni B2C račun uredno. Novi kupac je po zadanom tvrtka; polje client_vat_type to mijenja: 0 tvrtka, 1 fizička osoba, 2 javna ustanova, 3 EU tvrtka, 4 tvrtka izvan EU. Vrsta kupca određuje fiskalizaciju transakcijskih računa, vidi f1 i F2 niže.
• internal_number: broj narudžbe iz vašeg sustava. Jedinstven po tipu dokumenta: ako dokument s istim brojem već postoji, API vraća grešku 400 i ne radi duplikat. Zato je ponavljanje poziva nakon prekida veze sigurno.

Primjer 1: gotovinski maloprodajni račun (f1), bez kupca. Odmah se fiskalizira (u odgovoru jir i zki), označava plaćenim i ulazi u blagajnu:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "items": [ { "reference": "ART-001", "quantity": 2 } ]
}

Primjer 2: transakcijski račun tvrtki (F2, eRačun). U odgovoru nema jir/zki, račun je neplaćen dok uplatu ne evidentirate, a na listi izdanih računa čeka slanje kao eRačun. U primjeru nije poslan client_vat_type, pa se novi kupac sprema kao tvrtka (zadana vrijednost 0) i upravo zato račun ide kao F2; za fizičku osobu poslali biste client_vat_type 1 i račun bi bio f1. OIB u primjeru prolazi kontrolnu znamenku: s neispravnim OIB-om kupac bi se spremio kao fizička osoba i račun bi također otišao kao f1, s fiskalizacijom:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "T",
  "internal_number": "WEB-1001",
  "due_date": "2026-09-15",
  "client": { "oib": "12345678903", "company_name": "Tvrtka d.o.o.", "street": "Ilica", "house_number": "1", "city": "Zagreb", "zip": "10000" },
  "items": [ { "reference": "ART-001", "quantity": 2, "price": 25.00 } ]
}

Primjer 3: rabati po stavkama. Prva stavka dobiva točno 10%, drugoj se rabat izračuna iz snižene cijene prema prodajnoj cijeni artikla, treća je gratis (rabat 100%), a četvrta, bez ičega poslanog, dobiva rabat grupe artikla jer je uključen apply_client_discounts; kad je na računu i kupac s rabatom, njegov rabat ima prednost pred grupnim:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "apply_client_discounts": true,
  "items": [
    { "reference": "ART-001", "quantity": 1, "discount_percent": 10 },
    { "reference": "ART-002", "quantity": 1, "price": 80.00 },
    { "reference": "ART-003", "quantity": 1, "price": 0 },
    { "reference": "ART-004", "quantity": 1 }
  ]
}

Rezultat tog zahtjeva, uz pretpostavku da artikli imaju prodajnu cijenu 100,00 (ART-003 50,00), a grupa artikla ART-004 rabat 5%:

• ART-001: rabat točno 10%, naplaćuje se 90,00.
• ART-002: poslana cijena 80,00 uz prodajnu 100,00, pa se na stavci automatski iskazuje rabat 20% i naplaćuje 80,00.
• ART-003: cijena 0 znači gratis stavku: rabat 100%, naplaćuje se 0,00.
• ART-004: ništa nije poslano, pa se zbog apply_client_discounts primjenjuje rabat grupe od 5% i naplaćuje 95,00.

Odgovor poziva: polje data sadrži id_pos, pos_number, iznose (price, tax_pdv), način i status plaćanja te fiskalne podatke jir i zki s poveznicom QR koda (qrcode_link). Popunjeno jir polje znači da je račun uspješno fiskaliziran.

PDF i slanje kupcu: odgovor ne sadrži gotov URL PDF-a. PDF dohvaćate zasebnim pozivom GET invoice/getAsPdf/{id}, gdje je {id} vrijednost id_pos iz odgovora (ne pos_number); odgovor tog poziva je sama PDF datoteka. API račun ne šalje kupcu e-mailom (email iz client bloka samo se sprema na karticu klijenta), pa slanje računa kupcu radi vaš sustav s dohvaćenim PDF-om.

Fiskalizacija: koji račun ide kao f1, koji kao F2, a koji NF

Svaki račun (pos_type 1) pri zatvaranju automatski dobiva oznaku fiskalizacije prema načinu plaćanja i vrsti kupca; ponude se ne fiskaliziraju. Iste oznake vidite i na listi izdanih računa.

• f1 (klasična fiskalizacija): računi plaćeni gotovinom, karticom ili ostalim načinima, bez obzira na kupca, te transakcijski računi izdani fizičkoj osobi ili bez kupca. Račun se odmah šalje na fiskalizaciju i dobiva ZKI i JIR: u odgovoru su polja zki i jir popunjena. Za to u aplikaciji mora biti učitan fiskalni certifikat.
• F2 (Fiskalizacija 2.0, obveza eRačuna): transakcijski račun (payment T) izdan domaćoj tvrtki ili javnoj ustanovi s ispravnim OIB-om. Ne dobiva JIR pri izdavanju (polja jir i zki u odgovoru ostaju prazna) nego se šalje kao eRačun: na listi izdanih računa nosi F2 oznaku, crvenu dok eRačun nije poslan, zelenu nakon slanja.
• NF (nefiskalizirano): račun koji ne podliježe ni jednom ni drugom, na primjer transakcijski račun stranoj tvrtki ili gotovinski račun čije su sve stavke u prijenosu porezne obveze.

Storniranje računa

Poziv POST invoice/cancel uz pin djelatnika i id_pos (ID dokumenta) radi storno dokument, jednako kao storniranje u aplikaciji, i vraća ga u odgovoru. Originalni račun tada prelazi u status 3 (storniran), a novi storno dokument nosi status 2; zaliha skinuta originalnim računom se vraća.

Ograničenja i greške

Popisi su straničeni, zadano 200 zapisa po stranici; stranicu i veličinu birate parametrima page i pageSize. Broj poziva u minuti po korisniku ograničen je paketom: Starter 5, Standard 15, Business 30, Premium 60. Iznad toga popisni pozivi vraćaju grešku 429, pričekajte minutu pa nastavite.

Isprobavanje poziva

U interaktivnoj dokumentaciji svaki poziv možete isprobati gumbom Try it out: iz padajućeg izbornika servera odaberite svoju adresu, upišite zaglavlja i parametre i odmah vidite stvarni odgovor.

Trebate pomoć?

Ako imate pitanja oko povezivanja ili vam za vaš slučaj nedostaje neki poziv, javite se na [email protected].