Integracija preko API-ja: od demo naloga do produkcije

Praviš svoj sajt, aplikaciju ili ERP i hoćeš da izdaješ fiskalne račune preko Fiscomm-a. Ovde je redosled koraka. Polja i primeri zahteva su u dokumentaciji za programere.

Gde je dokumentacija

Početak (autentikacija, prvi test račun, prelazak na živo) je na stranici API dokumentacija. Sva polja i odgovori su u referenci API-ja. API je REST, pa ga povezuješ iz bilo kog jezika i okvira (Laravel, Node, .NET…).

Za PHP i TypeScript postoje SDK-ovi, a za integraciju uz AI alat postoji uputstvo pisano za jezičke modele. Linkovi su na dnu dokumentacije.

Da li ti treba sertifikat za test

Ne. Za test ti ne treba bezbednosni element (sertifikat od Poreske uprave, stiže kao fajl, nije kartica) ni prijava kod Poreske uprave. Demo firma ima test sertifikat: računi idu u test okruženje Poreske uprave i nisu fiskalni.

Za testFiscomm nalog i demo firma. Sertifikat i prijava kod Poreske uprave ne trebaju.
Za produkcijufirma sa svojim bezbednosnim elementom i ključ iz te firme.

Razliku između demo naloga i training računa objašnjavamo u članku API ključ, test i produkcija.

Koraci od nule do produkcije

  1. Otvori nalog na fiscomm.rs/otvori-nalog.
  2. Zatraži demo. U kasi klikni Zatražite demo u bočnom meniju (ili Zatražite demo nalog pod Zahtevi). Demo nije trenutan: kad ga odobrimo, na stranici zahteva se pojavi Otvori demo firmu.
  3. Napravi ključ u demo firmi, pod Podešavanja → API Ključ.
  4. Testiraj ceo tok: učitaj poreske oznake sa GET /receipt/tax-rates, izdaj prodaju i refundaciju, isprobaj ponavljanje zahteva i slanje računa kupcu. Šta zahtev mora da ima je u ovom članku.
  5. Pošalji nam primer jedne prodaje i jedne refundacije iz testa, da ih pogledamo pre produkcije (zašto).
  6. Pripremi produkcionu firmu. Firma za koju se izdaju računi nabavlja svoj bezbednosni element (kako) i registruje se u kasi, pod Zahtevi → Registruj firmu.
  7. Zameni ključ. U produkcionoj firmi napravi nov ključ i stavi ga umesto demo ključa. Adresa API-ja ostaje ista. Ponovo učitaj poreske oznake, jer na produkciji nisu iste kao na demou.
Najčešća greška pri prelasku: poreske oznake prepisane iz testa. Na produkciji ih uvek učitaj ponovo (poreske oznake).

Račun posle uspešne uplate karticom

Može. Fiscomm ne prima obaveštenja od payment gateway-a (npr. CorvusPay), pa poziv šalje tvoj sistem. Kad gateway javi tvom serveru da je transakcija uspešna, tvoj server pozove Fiscomm API i izda račun.

  • Poziv šalji sa servera, ne iz pregledača kupca. API ključ ne sme da bude vidljiv kupcu.
  • Kao orderNumber pošalji broj porudžbine iz svog sistema. Ako gateway javi istu uplatu dva puta, drugi zahtev sa istim brojem se odbija i ne nastaje dupli račun.
  • Da račun ode kupcu na mejl, u isti zahtev dodaj njegovu adresu. Detalji su u članku načini plaćanja i slanje računa, a tamo je i koji način plaćanja šalješ za karticu.
  • Ako poziv padne u timeout, ne šalji nov račun naslepo. Postupak je u ponovljenim zahtevima.

Platforma sa više prodavaca

Jedan ključ izdaje račune za tačno jednu prodavnicu jedne firme. Iz ključa Fiscomm zna firmu, prodavnicu i sertifikat, pa u zahtevu ne biraš za koga izdaješ. Jednim ključem zato ne možeš da izdaješ račune za više firmi.

Svaki prodavac ima svoj Fiscomm nalog i svoj bezbednosni element, jer račun izdaje on, na svoje ime. Ključ pravi u svom nalogu i daje ga tebi, a ti uz svaki zahtev šalješ ključ tog prodavca. Na koju firmu i prodavnicu je ključ vezan proveriš pozivomGET /auth/api-key/me.

Hoćeš fiskalizaciju kao deo svog proizvoda, pod svojim imenom? Pogledaj white label za partnere i piši nam, uslovi se dogovaraju.

API je prestao da radi

  1. Pogledaj status sistema.
  2. Pročitaj kod greške iz odgovora. Šta znače 401, 403 i 404 je na stranici Greške i ograničenja, a odbijene račune objašnjava članak o poreskim oznakama.
  3. Ako i dalje ne radi, piši na podrska@fiscomm.rs i pošalji correlationId iz odgovora.
Sledeći korak

Otvori nalog i zatraži demo za integraciju.

Otvori nalog