API dokumentacija

Za developere.

Izrada računa

Ova metoda ti omogućuje kreiranje novog računa.

Pozivanje metode se vrši putem ove adrese:

POST https://api.solo.com.hr/racun

Parametri

Parametri predstavljaju naredbe koje šalješ u POST pozivu.

token

Tvoj tajni identifikator. Možeš pronaći svoj API token u Postavkama nakon prijave u servis.

Pravilo: obavezno

tip_usluge

ID usluge u koju spada račun. Usluge možeš pronaći pod Usluge -> Tipovi usluga nakon prijave u servis. Svaka usluga ima svoj unikatni ID.

Pravilo: obavezno, numerički unos

prikazi_porez

Želiš li prikazati PDV na računu?

Da 1
Ne 0

Pravilo: obavezno, numerički unos

tip_racuna

Željeni tip računa.

R 1
R1 2
R2 3
bez oznake 4
Avansni 5

Pravilo: obavezno, numerički unos

kupac_naziv

Naziv kupca, max. 100 znakova (s razmacima).

Pravilo: nije obavezno

kupac_adresa

Adresa kupca, max. 255 znakova (s razmacima).

Pravilo: nije obavezno

kupac_oib

Porezni broj kupca, max. 20 znakova (s razmacima).

Pravilo: nije obavezno

usluga

Redni broj usluge, _mora_ početi od broja 1.

Pravilo: obavezno, numerički unos

opis_usluge_x

x je redni broj usluge (npr. opis_usluge_1). Max. 500 znakova (s razmacima).

Pravilo: obavezno, alfanumerički unos

jed_mjera_x

x je redni broj usluge. Max. 5 znakova (bez razmaka). Ovdje pogledaj popis jediničnih mjera.

Pravilo: nije obavezno, numerički unos

cijena_x

x je redni broj usluge. Dozvoljen je ISO 4217 brojčani format (npr. 1.234,00). Decimale se odvajaju zarezom. Max. 18 znakova (bez razmaka).

Pravilo: obavezno, numerički unos, dozvoljene 2 decimale

kolicina_x

x je redni broj usluge. Max. 18 znakova (bez razmaka).

Pravilo: obavezno, numerički unos, dozvoljene 4 decimale

popust_x

x je redni broj usluge. Max. 18 znakova (bez razmaka).

Pravilo: obavezno, numerički unos, dozvoljene 4 decimale

porez_stopa_x

x je redni broj usluge. Max. 2 znaka (bez razmaka). Podržane porezne stope su 0, 5, 13 i 25.

Pravilo: obavezno, numerički unos

nacin_placanja

Odabrani način plaćanja. Ovdje provjeri podržane načine plaćanja.

Pravilo: obavezno, numerički unos

datum_racuna

Dozvoljen je ISO 8601 format datuma (npr. 2014-01-01). Dozvoljen je unos sati i minuta (npr. 2014-01-01 00:00). Ako se ne unese datum, sustav će sam dodijeliti trenutni datum i vrijeme. Računi koje fiskaliziraš s FINA certifikatom ignoriraju ovo polje i uzimaju trenutni datum i vrijeme.

Pravilo: nije obavezno

rok_placanja

Dozvoljen je ISO 8601 format datuma (npr. 2014-01-01). Dozvoljen je unos sati i minuta (npr. 2014-01-01 00:00).

Pravilo: nije obavezno

datum_isporuke

Dozvoljen je ISO 8601 format datuma (npr. 2014-01-01). Dozvoljen je unos sati i minuta (npr. 2014-01-01 00:00).

Pravilo: nije obavezno

napomene

Vidljive napomene na računu. Max. 1000 znakova (s razmacima).

Pravilo: nije obavezno, alfanumerički unos

ponavljanje

Broj dana za ponavljanje računa. Dozvoljen je samo numerički unos do 3 znamenke.

Pravilo: nije obavezno, numerički unos

iban

Odabir prvog ili drugog računa za uplatu. Dozvoljen je samo numerički unos od 1 znamenke. Ako se ne pošalje/pošalje krivi unos, sustav će sam odabrati prvi IBAN.

Pravilo: nije obavezno, numerički unos, može biti samo 1 ili 2

jezik_racuna

Ovdje pogledaj popis podržanih jezika. Dozvoljen je samo numerički unos od 1 znamenke. Ako se ne unese jezik, sustav će sam odabrati hrvatski.

Pravilo: nije obavezno, numerički unos

valuta_racuna

Ovdje pogledaj popis valuta. Dozvoljen je samo numerički unos do 2 znamenke. Ako se ne unese valuta, sustav će sam odabrati HRK.

Pravilo: nije obavezno, numerički unos

tecaj

Tečaj po kojem će se preračunati cijene usluga u odabranu valutu. Ako je HRK onda treba biti 1 (ili ostaviti prazno).

Pravilo: nije obavezno, numerički unos, dozvoljeno 6 decimala

status

Zadani status računa je "otvoreno". Ovdje provjeri podržane statuse računa i ponuda.

Pravilo: nije obavezno, numerički unos

fiskalizacija

Račun će biti fiskaliziran (ako je instaliran certifikat, prijavljena poslovnica i operater) i dobiti će ZKI i JIR.

Pravilo: nije obavezno, numerički unos, može biti samo 0 ili 1

Povratne informacije

Ovdje su navedeni mogući odgovori servisa nakon što pošalješ API zahtjev.

Odgovor na uspješan zahtjev će biti ovakav:

{
  "status": 0,
  "racun": {
    "id": "8791cae3c9b02bb8d88bf626247b4e67dfbe20e35fc0342b448f39c9264c591d",
    "broj_racuna": "1-1-1",
    "tip_usluge": "1",
    "prikazi_porez": "1",
    "tip_racuna": "R1",
    "kupac_naziv": "COAX d.o.o.",
    "kupac_adresa": "Kralja Držislava 4, 10000 Zagreb",
    "kupac_oib": "58981111611",
    "usluge": [
      {
        "broj": "1",
        "opis_usluge": "Kruške",
        "jed_mjera": "kom",
        "kolicina": "1",
        "cijena": "9,99",
        "popust": "0",
        "porez_stopa": "25",
        "suma": "9,99"
      },
      {
        "broj": "2",
        "opis_usluge": "Jabuke",
        "jed_mjera": "kom",
        "kolicina": "2",
        "cijena": "5,00",
        "popust": "0",
        "porez_stopa": "25",
        "suma": "10,00"
      }
    ],
    "neto_suma": "19,99",
    "porezi": [
      {
        "stopa": "25",
        "osnovica": "19,99",
        "porez": "5,00"
      }
    ],
    "bruto_suma": "24,99",
    "nacin_placanja": "1",
    "operater": "Ime Prezime",
    "racun_izdao": "Ime Prezime",
    "likvidator": "Ime Prezime",
    "datum_racuna": "1.8.2016. 13:00:00",
    "rok_placanja": "",
    "datum_isporuke": "1.8.2016",
    "napomene": "Hvala",
    "ponavljanje": "0",
    "iban": "HR3823400091160392212",
    "jezik_racuna": "1",
    "valuta_racuna": "HRK",
    "tecaj": "1",
    "status": "1",
    "boja": "#ffcf03",
    "zki": "e4d909c290d0fb1ca068ffaddf22cbd0",
    "jir": "2cf55235-9470-4b5c-a539-463f52b109d2",
    "pdf": "https://solo.com.hr/download/8791cae3c9b02bb8d88bf626247b4e67dfbe20e35fc0342b448f39c9264c591d"
  },
  "message": "Račun uspješno kreiran."
}
          

Kada dođe do greške u zahtjevu, sustav vraća obavijest u ovakvom obliku:

{
  "status": 101,
  "message": "Neispravan token."
}
          

Popis mogućih grešaka kod neispravnog zahtjeva:

101 Neispravan token.
102 Dosegnut mjesečni limit licence.
103 Tip usluge nije poslan ili u neispravnom formatu.
105 Tip računa nije poslan ili u neispravnom formatu.
106 Prikaz poreza nije poslan ili u neispravnom formatu.
107 Ukupan broj usluga nije poslan ili u neispravnom formatu ili veći od dozvoljenog (max. 36).
108 Broj usluge nije poslan ili u neispravnom formatu ili veći od dozvoljenog (max. 36).
109 Opis usluge nije poslan ili je duži od 1000 znakova.
110 Cijena nije poslana ili u neispravnom formatu.
111 Količina nije poslana ili u neispravnom formatu.
112 Popust nije poslan ili u neispravnom formatu.
113 Porezna stopa nije poslana ili u neispravnom formatu.
114 Način plaćanja nije poslan ili u neispravnom formatu.
115 Ponavljanje u neispravnom formatu.
116 Jezik u neispravnom formatu.
117 Valuta u neispravnom formatu.
118 Tečaj u neispravnom formatu.
119 Status u neispravnom formatu.
120 Fiskalizacija nije dozvoljena. Certifikat, poslovnica i operater moraju biti uneseni.
125 Fiskalizacija nije uspjela. FINA je javila grešku.

Primjer API zahtjeva u praksi

Primjer u nastavku je isključivo demonstracija metode i njenih parametara. Metode nikada ne bi trebale biti u ovakvom HTML formatu nego ih se generira dinamički kroz neki od programskih/skriptnih jezika.

<form action="https://api.solo.com.hr/racun" method="post">
  <input type="hidden" name="token" value="k2f85a47b75f20h21da9zg1337co5a1g">
  <input type="hidden" name="tip_usluge" value="1">
  <input type="hidden" name="prikazi_porez" value="1">
  <input type="hidden" name="tip_racuna" value="1">
  <input type="hidden" name="kupac_naziv" value="COAX d.o.o.">
  <input type="hidden" name="kupac_adresa" value="Kralja Držislava 4, 10000 Zagreb">
  <input type="hidden" name="kupac_oib" value="58981111611">
  <input type="hidden" name="usluga" value="1">
  <input type="hidden" name="opis_usluge_1" value="Kruške">
  <input type="hidden" name="jed_mjera_1" value="2">
  <input type="hidden" name="cijena_1" value="9,99">
  <input type="hidden" name="kolicina_1" value="1">
  <input type="hidden" name="popust_1" value="0">
  <input type="hidden" name="porez_stopa_1" value="25">
  <input type="hidden" name="usluga" value="2">
  <input type="hidden" name="opis_usluge_2" value="Jabuke">
  <input type="hidden" name="jed_mjera_2" value="2">
  <input type="hidden" name="cijena_2" value="5,00">
  <input type="hidden" name="kolicina_2" value="2">
  <input type="hidden" name="popust_2" value="0">
  <input type="hidden" name="porez_stopa_2" value="25">
  <input type="hidden" name="nacin_placanja" value="1">
  <input type="hidden" name="datum_racuna" value="2016-08-01 13:00">
  <input type="hidden" name="rok_placanja" value="">
  <input type="hidden" name="datum_isporuke" value="2016-08-01">
  <input type="hidden" name="napomene" value="Hvala">
  <input type="hidden" name="ponavljanje" value="0">
  <input type="hidden" name="iban" value="1">
  <input type="hidden" name="jezik_racuna" value="1">
  <input type="hidden" name="valuta_racuna" value="1">
  <input type="hidden" name="tecaj" value="1">
  <input type="hidden" name="status" value="1">
  <input type="hidden" name="fiskalizacija" value="0">
</form>