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

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?

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 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 j.d.o.o.",
    "kupac_adresa": "Gjure Szaba odvojak 8, 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:

100 Pričekaj barem 10 sekundi prije slanja novog 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.
122 Račun ne postoji.
123 Nije kreiran niti jedan račun.
124 Fiskalizirane račune nije moguće brisati.
125 Fiskalizacija nije uspjela. FINA je javila grešku.
126 Moraš uključiti fiskalizaciju za odabrani način plaćanja (gotovina, kartice, ček).
127 Popust ne može biti veći od 100%.

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('Gjure Szaba odvojak 8, 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
?>