API dokumentacija

Izrada računa

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

Pozivanje metode se vrši putem ove adrese:

API je limitiran na izradu do 300 računa mjesečno u plaćenom, tj. 3 u besplatnom paketu.

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?

Pravilo: obavezno, numerički unos

tip_racuna

Željeni tip računa.

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. 8 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 EUR.

Pravilo: nije obavezno, numerički unos

tecaj

Tečaj po kojem će se preračunati cijene usluga u odabranu valutu. Ako je EUR onda treba biti 1 (ili ostaviti prazno).
Važno: tečaj se množi s iznosima na računu, ako koristiš HNB-ov tečaj, prvo ga podijeli s 1 (npr. tečaj USD treba biti 0,94 umjesto 7,064035).

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": "Jadranska avenija 6/21, 10000 Zagreb",
    "kupac_oib": "21248839327",
    "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",
    "datum_uplate: "1.8.2016",
    "napomene": "Hvala",
    "ponavljanje": "0",
    "iban": "HR3823400091160392212",
    "jezik_racuna": "1",
    "valuta_racuna": "EUR",
    "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:

Primjer API zahtjeva u praksi

Primjer u nastavku je isključivo demonstracija metode i njenih parametara u .php skriptnom jeziku.

<?php
$url = 'https://api.solo.com.hr/racun';
// $data ne smije biti array zbog duplikata
$data = 'token=k2f85a47b75f20h21da9zg1337co5a1g' .
	'&tip_usluge=1' .
	'&tip_racuna=1' .
	'&prikazi_porez=1' .
	'&kupac_naziv=' . urlencode('COAX j.d.o.o.') .
	'&kupac_adresa=' . urlencode('Jadranska avenija 6/21, 10000 Zagreb') .
	'&kupac_oib=' . urlencode('21248839327') .
// ovdje stavi for loop za proizvode iz narudžbe
	'&usluga=1' . // ako ima više usluga, iduća treba biti 2, itd.
	'&opis_usluge_1=' . urlencode('kava') .
	'&jed_mjera_1=1' .
	'&cijena_1=76,00' .
	'&kolicina_1=1' .
	'&popust_1=0' .
	'&porez_stopa_1=25' .
	'&usluga=2' .
	'&opis_usluge_2=' . urlencode('čaj') .
	'&jed_mjera_2=1' .
	'&cijena_2=76,00' .
	'&kolicina_2=1' .
	'&popust_2=0' .
	'&porez_stopa_2=25' .
// ovdje završava for loop
	'&nacin_placanja=1' .
	'&napomene=' . urlencode('Hvala na povjerenju');
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
$response = curl_exec($curl);
curl_close($curl);
echo $response; // isključi echo nakon testiranja
?>