infogrambeg / efiskalizacija-php-sdk
PHP SDK za eFiskalizacija.cloud - fiskalizacija računa u Srbiji (VSDC API)
Package info
github.com/infogrambeg/efiskalizacija-php-sdk
pkg:composer/infogrambeg/efiskalizacija-php-sdk
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
PHP SDK za eFiskalizacija.cloud - fiskalizacija računa u Srbiji (VSDC API).
Zahtevi
- PHP >= 8.1
- ext-curl
- ext-json
Instalacija
composer require infogrambeg/efiskalizacija-php-sdk:^1.2
Trenutna verzija: 1.2.0 (potpis zahteva v2 od 1.1.0, vidi „Potpis zahteva (HMAC v2)“).
Verzija 1.1.0 i novije zahtevaju server sa podrškom za potpis v2 — efiskalizacija.cloud i
staging.efiskalizacija.cloud je imaju od 2026-11-13.
Brzi početak
use Efiskalizacija\EfiskalizacijaClient; use Efiskalizacija\DTO\Invoice; use Efiskalizacija\DTO\InvoiceItem; use Efiskalizacija\DTO\Customer; use Efiskalizacija\Enum\PaymentType; // Kreiranje klijenta $client = EfiskalizacijaClient::create($apiKey, $apiSecret); // Kreiranje računa $invoice = Invoice::create() ->setInvoiceNumber('SHOP-2026-001') ->setPaymentType(PaymentType::Kartica) ->setCashier('Web Shop') ->setCustomer(Customer::pravnoLice('123456789', 'Firma DOO')) ->addItem(new InvoiceItem( naziv: 'Laptop HP ProBook', kolicina: 1, jedinicnaCena: 85000.00, pdvStopa: 20, sifra: 'HP-PB-450', )); // Fiskalizacija $result = $client->fiskalizacija()->fiskalizuj($invoice); if (!$result->isSuccess()) { // Neuspeh koji server vrati kao rezultat ne baca izuzetak echo $result->poruka; // razlog (npr. odgovor Poreske uprave) echo $result->errorCode; // šifra greške ili null (vidi ispod) return; } echo $result->pfrBroj; // "AB12CD34-Ef5Gh6i7-101" echo $result->qrUrl; // adresa za proveru računa na portalu Poreske uprave echo $result->qrCode; // QR kod kao base64 PNG echo $result->racunId; // ID u sistemu echo $result->klijentskiBroj; // "SHOP-2026-001" (broj iz setInvoiceNumber()) var_dump($result->duplikat); // true: vraćen već izdat račun sa istim brojem
Rezultat (FiskalizacijaResult) nosi i success, status, brojRacuna (broj koji je
dodelio sistem), ukupanIznos, pfrDatumVreme, esirOznaka, errorCode i
existingCopyInvoiceId. errorCode (copy_already_issued / copy_in_progress) i
existingCopyInvoiceId (uz copy_already_issued) server popunjava samo za kopiju računa
poslatu sa tip_racuna: "copy" i original_broj_racuna. SDK takav zahtev šalje kad uz
InvoiceType::Kopija postavite setOriginalInvoiceNumber() (vidi „Kopija računa“); bez
broja originala su null. duplikat je null
kad zahtev nije nosio broj računa. Izuzetak se baca samo za HTTP grešku (vidi „Error handling“).
API Metode
// Fiskalizacija računa $result = $client->fiskalizacija()->fiskalizuj($invoice); // Status tenanta $status = $client->status()->fetch(); // Lista računa $list = $client->invoices()->list(limit: 20, offset: 0); // PDF preuzimanje $pdf = $client->pdf()->download($pfrBroj); $client->pdf()->downloadToFile($pfrBroj, '/path/racun.pdf'); // Slanje na email $client->email()->send($pfrBroj, 'kupac@example.com'); // Test (samo sandbox) $test = $client->test()->run();
Načini plaćanja
use Efiskalizacija\Enum\PaymentType; PaymentType::Gotovina // Gotovina PaymentType::Kartica // Platna kartica PaymentType::Virman // Virmanski prenos PaymentType::Vaucer // Vaučer PaymentType::Instant // Instant plaćanje (IPS) PaymentType::Drugo // Drugo bezgotovinsko
Split payment (podeljeno plaćanje)
use Efiskalizacija\DTO\Payment; $invoice->setSplitPayments([ new Payment(PaymentType::Gotovina, 5000.00), new Payment(PaymentType::Kartica, 7800.00), ]);
Kupac
use Efiskalizacija\DTO\Customer; // Pravno lice (PIB - 9 cifara) Customer::pravnoLice('123456789', 'Firma DOO', 'Adresa 1', 'Beograd'); // Fizičko lice (JMBG - 13 cifara) Customer::fizickoLice('1234567890123', 'Petar Petrović'); // Javni sektor (PIB i JBKJS kupca) Customer::javniSektor('54321', 'Ministarstvo', pib: '123456789'); // Anonimni kupac Customer::anonimni('email@example.com');
Identifikacija kupca se šalje kao pib, jmbg ili jbkjs (osim kod
Customer::javniSektor() bez $pib, vidi ispod); server od nje pravi oznaku kupca za
Poresku upravu (10:PIB, 11:JMBG, 12:PIB:JBKJS), a PIB (pravnoLice()) i JMBG
(fizickoLice()) čuva uz račun, kao i ime, adresu, email i telefon. Za kupca iz
Customer::javniSektor() (sa $pib i bez njega) server ne čuva PIB ni JBKJS uz račun: oni
idu samo u oznaku kupca za Poresku upravu. Mesto kupca (mesto) se šalje, ali ga server ne
čuva (ne vidi se na računu ni u listi računa).
Za kupca iz javnog sektora Poreska uprava, po tehničkom uputstvu PURS-a, traži PIB i JBKJS
kupca: Customer::javniSektor() sa $pib šalje jbkjs: "PIB:JBKJS", pa je oznaka za
primer iznad 12:123456789:54321. PIB mora imati tačno 9 cifara, a JBKJS tačno 5, bez
belina i drugih znakova; inače se baca InvalidArgumentException pre slanja. Vrednost već
u obliku PIB:JBKJS bez $pib (Customer::javniSektor('123456789:54321')) šalje se isto.
Bez $pib Customer::javniSektor() šalje kupca kao 1.1.1: tip: "javni_sektor" i
identifikator sa vrednošću kakvu ste prosledili, bez provere i bez uklanjanja belina.
Server takav račun izdaje ili odbija kao do sada: vrednost od 9 cifara izdaje sa oznakom
10:PIB, vrednost od 13 cifara sa oznakom 11:JMBG, a JBKJS od 5 cifara odbija. Za kupca
iz javnog sektora navedite i PIB.
Kod Customer::pravnoLice() i Customer::fizickoLice() razmak, tab, novi red, CR, NUL i
vertikalni tab na krajevima PIB-a, odnosno JMBG-a, uklanjaju se pre provere i ne šalju se:
Customer::pravnoLice("123456789\n") šalje pib: "123456789".
Avansni račun za kupca iz javnog sektora sa JBKJS-om server još ne prima („Kupac (PIB ili
JMBG) je obavezan za avansne račune“): za avans koristite Customer::pravnoLice() sa PIB-om
kupca.
Šifra artikla
sifra u InvoiceItem se šalje kao sifra_artikla i čuva uz stavku računa. Šifra može
imati najviše 50 znakova (InvoiceItem::MAX_SIFRA_DUZINA, prati granicu servera; razmaci
na kraju se ne broje). Šifra duža od 50 znakova se ne šalje i ne čuva, kao do 1.1.1: račun
se izdaje bez šifre te stavke, jer bi server inače odbio ceo račun. Prazna šifra ('',
npr. proizvod bez SKU-a) se ne šalje: stavka se čuva bez šifre, kao do 1.1.1. Svojstvo
sifra zadržava celu vrednost.
PDV kategorije (za 0% PDV)
use Efiskalizacija\Enum\TaxCategory; new InvoiceItem( naziv: 'Oslobođena usluga', kolicina: 1, jedinicnaCena: 5000.00, pdvStopa: 0, pdvKategorija: TaxCategory::Oslobodjen, // Oslobođen PDV-a ); new InvoiceItem( naziv: 'Van sistema PDV', kolicina: 1, jedinicnaCena: 3000.00, pdvStopa: 0, pdvKategorija: TaxCategory::NijeUPdv, // Nije u sistemu PDV-a );
Popusti
// Fiksni popust (iznos u RSD) new InvoiceItem( naziv: 'Laptop', kolicina: 1, jedinicnaCena: 85000.00, pdvStopa: 20, popust: 5000.00, ); // Procentualni popust (0-100%) new InvoiceItem( naziv: 'Miš', kolicina: 2, jedinicnaCena: 4500.00, pdvStopa: 20, rabatProcenat: 10.0, );
Avansni računi
use Efiskalizacija\Enum\InvoiceType; use Efiskalizacija\Enum\TransactionType; // 1. Avans prodaja $avans = Invoice::create() ->setInvoiceType(InvoiceType::Avans) ->setPaymentType(PaymentType::Kartica) ->setCustomer(Customer::pravnoLice('123456789')) ->addItem(new InvoiceItem(naziv: 'Avans', kolicina: 1, jedinicnaCena: 50000, pdvStopa: 20)); $avansResult = $client->fiskalizacija()->fiskalizuj($avans); if (!$avansResult->isSuccess()) { // Bez fiskalizovanog avansa nema reference za sledeći korak: stanite throw new RuntimeException('Avans nije fiskalizovan: ' . $avansResult->poruka); } // 2. Avans refundacija (referenca na poslednji avans) $refund = Invoice::create() ->setInvoiceType(InvoiceType::Avans) ->setTransactionType(TransactionType::Refund) ->setReferentDocument($avansResult->pfrBroj) ->setPaymentType(PaymentType::Kartica) ->setCustomer(Customer::pravnoLice('123456789')) ->addItem(new InvoiceItem(naziv: 'Refundacija avansa', kolicina: 1, jedinicnaCena: 50000, pdvStopa: 20)); $refundResult = $client->fiskalizacija()->fiskalizuj($refund); if (!$refundResult->isSuccess()) { throw new RuntimeException('Refundacija avansa nije fiskalizovana: ' . $refundResult->poruka); } // 3. Konačni račun (referenca na avans refundaciju) $final = Invoice::create() ->setReferentDocument($refundResult->pfrBroj) ->setPaymentType(PaymentType::Kartica) ->setCustomer(Customer::pravnoLice('123456789')) ->addItem(new InvoiceItem(naziv: 'Laptop Dell XPS', kolicina: 1, jedinicnaCena: 250000, pdvStopa: 20)); $finalResult = $client->fiskalizacija()->fiskalizuj($final); if (!$finalResult->isSuccess()) { throw new RuntimeException('Konačni račun nije fiskalizovan: ' . $finalResult->poruka); }
Neuspeh fiskalizacije nije izuzetak (vidi „Brzi početak“), pa posle svakog koraka proverite
isSuccess() i stanite pre sledećeg setReferentDocument(): neuspeo korak ima prazan
pfrBroj, pa sledeći račun ne bi imao ispravnu referencu.
Kopija računa
use Efiskalizacija\Enum\InvoiceType; $original = $client->fiskalizacija()->fiskalizuj($invoice); // račun iz „Brzi početak“ if (!$original->isSuccess()) { throw new RuntimeException('Original nije fiskalizovan: ' . $original->poruka); } $kopija = Invoice::create() ->setInvoiceNumber('SHOP-2026-001-K1') // sopstveni broj kopije, ne broj originala ->setInvoiceType(InvoiceType::Kopija) ->setOriginalInvoiceNumber($original->brojRacuna) // broj koji je sistem dodelio originalu ->setReferentDocument($original->pfrBroj) ->setPaymentType(PaymentType::Kartica) ->addItem(new InvoiceItem(naziv: 'Laptop', kolicina: 1, jedinicnaCena: 85000.00, pdvStopa: 20)); $result = $client->fiskalizacija()->fiskalizuj($kopija); if ($result->isSuccess()) { // kopija je izdata: $result->pfrBroj } elseif ($result->errorCode === 'copy_already_issued') { // kopija ovog broja je već izdata: $result->existingCopyInvoiceId } elseif ($result->errorCode === 'copy_in_progress') { // druga kopija istog broja je upravo u obradi; pokušajte ponovo kasnije } else { throw new RuntimeException('Kopija nije izdata: ' . $result->poruka); }
Kopija ima sopstveni broj računa (setInvoiceNumber()), kao svaki fiskalni dokument: isti
broj kao original server odbija („broj_racuna je već upotrebljen za drugi tip računa“,
EfiskalizacijaException sa kodom 409). Original se proverava pre kopije: brojRacuna i
pfrBroj originala koristite samo kad je njegov isSuccess() true.
Uz setOriginalInvoiceNumber() (od 1.2.0) zahtev nosi tip_racuna: "copy" i
original_broj_racuna: kopija dobija broj originala, a server drugu kopiju istog broja
odbija pre slanja Poreskoj upravi (errorCode, vidi „Brzi početak“). Broj originala je
brojRacuna iz rezultata originala (ne broj iz setInvoiceNumber()), najviše 50 znakova.
setOriginalInvoiceNumber() važi samo uz InvoiceType::Kopija: za drugi tip fiskalizuj()
baca LogicException pre slanja. Bez broja originala InvoiceType::Kopija se šalje kao
tip_racuna: "kopija" (kao do 1.1.1): server dodeljuje nov broj i druge kopije ne proverava.
Idempotency
$invoice->setInvoiceNumber('SHOP-2026-001'); // jedinstven broj iz vašeg sistema, npr. broj narudžbine
Zaštita od duplog fiskalnog računa je broj računa (setInvoiceNumber(), polje
broj_racuna): server prepoznaje već upisan račun sa istim brojem i vraća ga umesto
novog. Zato SDK POST /fiskalizacija sa nepraznim brojem sme sam da ponovi i kad se ne
zna da li je prvi zahtev obrađen (vidi „Retry logika“), a isto važi i kad vi ponovite
poziv sa istim brojem.
Zaštita ima prozor: server račun fiskalizuje pre nego što ga upiše. Kad se obrada na
serveru prekine ili ne uspe posle fiskalizacije (pad servera, istek odgovora Poreske
uprave, posle kog server vraća neuspeh), račun postoji kod Poreske uprave, ali ga server
nije upisao, pa se ne vidi ni u invoices()->list() ni u admin panelu, a ponovljen zahtev
sa istim brojem izdaje drugi račun. Provera (invoices()->list() ili admin panel) nalazi
samo upisan račun i korisna je pre svega za zahtev bez broja. Zato, kad ishod ostane
nepoznat i posle poslednjeg pokušaja, sa brojem računa ili bez njega, proverite da li je
račun izdat, a kad ga provera ne nađe, pre novog slanja obratite se podršci.
Bez broja računa svaki zahtev koji server obradi daje nov račun. Od 1.2.0 SDK takav
zahtev ne ponavlja kad ishod nije poznat (prekid veze posle slanja, 502, 503, 504), nego baca
izuzetak: pre novog slanja proverite da li je račun izdat (npr. invoices()->list() ili
admin panel).
setIdempotencyKey() / getIdempotencyKey() su od 1.2.0 zastareli (@deprecated):
ključ se čuva u objektu, ali se ne šalje serveru i ne štiti od duplog računa.
Error handling
use Efiskalizacija\Exception\AuthenticationException; use Efiskalizacija\Exception\ValidationException; use Efiskalizacija\Exception\RateLimitException; use Efiskalizacija\Exception\ServerException; use Efiskalizacija\Exception\NetworkException; try { $result = $client->fiskalizacija()->fiskalizuj($invoice); } catch (AuthenticationException $e) { // 401 - Neispravan API key ili HMAC potpis } catch (ValidationException $e) { // 400/422 - Neispravni podaci $errors = $e->getErrors(); } catch (RateLimitException $e) { // 429 - Previše zahteva $retryAfter = $e->getRetryAfter(); // sekunde } catch (ServerException $e) { // 5xx - Greška na serveru (posle automatskih ponavljanja, vidi „Retry logika“) } catch (NetworkException $e) { // Timeout, DNS, konekcija. $e->wasRequestSent(): false = zahtev nije poslat, // true ili null = možda je obrađen — bez broja računa proverite ishod pre novog slanja }
Potpis zahteva (HMAC v2)
Od verzije 1.1.0 SDK klijent svaki zahtev potpisuje potpisom v2
(HmacSigner::getAuthHeadersV2()) i šalje zaglavlje X-Signature-Version: 2:
stringToSign = "v2:" + X-Timestamp + METHOD + requestTarget + SHA256(body)
X-Signature = Base64(HMAC-SHA256(apiSecret, stringToSign))
requestTarget je putanja API-ja sa query stringom, tačno kako se šalje (npr.
/api/multitenant.php/pdf?pfr=ABC-1&download=1), bez dekodiranja, sortiranja i
normalizacije. Server proverava potpis nad sirovim REQUEST_URI, pa zahtev kome je query
izmenjen posle potpisa dobija 401.
Query string SDK kodira po RFC 3986 (razmak je %20, ~ ostaje nekodiran), a ? dodaje
samo uz neprazan query. Taj oblik Guzzle, Symfony HttpClient i WordPress HTTP API šalju
neizmenjen.
- Ako koristite sopstveni HTTP klijent (vidi „Custom HTTP klijent“), on mora poslati
$urlbajt-identično kako ga je SDK predao — bez ponovnog kodiranja ili preuređivanja parametara — i proslediti sva zaglavlja, uključujućiX-Signature-Version. - Bazni URL (
ConfigbaseUrl) treba da bude koren hosta (npr.https://efiskalizacija.cloud), jer je server uvek na/api/multitenant.php. Putanja baznog URL-a se NE potpisuje: bazni URL sa putanjom (npr.https://primer.rs/efisk) radi samo iza gateway-a koji taj prefiks skida pre servera. - Starije verzije potpisuju v1 (bez zaglavlja
X-Signature-Version). Server v1 proverava nad putanjom bez query stringa. Samo 1.0.2 pre potpisa odseca query, pa prolazi i za GET sa parametrima (/pdf,/invoice); 1.0.0 i 1.0.1 potpisuju putanju sa query-jem, pa takav GET dobija401. Server i dalje prima v1 na fiskalnim rutama, ali za nove integracije koristite 1.1.0 ili noviju.
Promene u 1.2.0
-
Rezultat fiskalizacije po stvarnim poljima servera.
FiskalizacijaResult::fromArray()čitaqr_kod(rezervnoqr_code) imessage(rezervnoporuka): do 1.1.1 suqrCodeiporukauvek bilinull. Nova svojstva (na kraju konstruktora, sa podrazumevanom vrednošćunull):success,status,brojRacuna,klijentskiBroj,duplikat,ukupanIznos,pfrDatumVreme,qrUrl,esirOznaka,errorCode,existingCopyInvoiceId, i metodaisSuccess(). Neuspeh koji server vrati kao rezultat (success: false) i dalje je rezultat, ne izuzetak. Vrednost u neočekivanom tipu (npr. broj kao tekst) prevodi se kad je to jednoznačno, a inače jenull. -
Webhook po stvarnom telu.
WebhookPayload::fromArray()čita polja izdata(invoice_id→racunId,pfr_broj,ukupan_iznos→iznos), uz rezervu na stare ključeve sa vrha. Nova svojstva:klijentskiBroj,brojRacuna(invoice_number),success,datumIzdavanja,errorMessage,timestamp.statusje izveden izsuccess(success/error) kad ga telo ne nosi.isFiscalized()iisFailed()su bez promene. Za račun izdat sa 1.2.0invoice.fiscalizednosi idata.kupac.pib/data.kupac.jmbgidata.stavke[].sifra_artikla(server ih čita iz kolona upisanih uz račun; do 1.1.1 PIB i JMBG nisu bili udata.kupac, asifra_artiklaje bionull); čitaju se izrawData. -
Invoice::setAdvertisementText()šaljereklamni_tekst: server ga čuva i štampa na računu.Invoice::setNote()je@deprecated(korenskonapomenase ne čuva uz račun); šalje se kao do sada. -
Šifra artikla se čuva.
InvoiceItemšaljesifrakaosifra_artikla, ključ koji server čuva uz stavku (do 1.1.1sifra, koju server nije čitao, pa se šifra gubila). Šifra duža od 50 znakova se ne šalje i ne čuva (kao do 1.1.1), pa račun i dalje prolazi (vidi „Šifra artikla“). -
Kupac pod ključevima koje server čita.
Customer::toArray()šaljepib,jmbgilijbkjsumestotip+identifikator(osimCustomer::javniSektor()bez$pib): server sada čuva PIB i JMBG kupca uz račun. Oznaka kupca za Poresku upravu za PIB i JMBG je ista kao ranije.mestose šalje kao do sada, ali ga server ne čuva. -
Javni sektor po uputstvu PURS-a.
Customer::javniSektor()ima nov parametar$pibna kraju. Sa njim šalje PIB i JBKJS kupca (jbkjs: "PIB:JBKJS", oznaka12:PIB:JBKJS); PIB mora imati tačno 9, a JBKJS tačno 5 cifara, inače se bacaInvalidArgumentExceptionpre slanja. Bez$pibšalje kupca bajt-isto kao 1.1.1 (tip+identifikator), pa server takav račun izdaje ili odbija kao do sada; jedini izuzetak je vrednost u oblikuPIB:JBKJS, koja se šalje kaojbkjs. Do 1.1.1 server je račun za javni sektor sa JBKJS-om odbijao (identifikatorod 5 cifara). KodpravnoLice()ifizickoLice()beline na krajevima PIB-a i JMBG-a se uklanjaju pre provere i ne šalju se. -
Kopija sa brojem originala.
Invoice::setOriginalInvoiceNumber()uzInvoiceType::Kopijašaljetip_racuna: "copy"ioriginal_broj_racuna, pa server odbija drugu kopiju istog broja i popunjavaerrorCode/existingCopyInvoiceId(vidi „Kopija računa“). Bez nje kopija se šalje kao u 1.1.1. -
TenantStatus::$unlimitedInvoices:truekad nalog nema mesečni limit računa (server šaljemax_invoices_per_month: null);maxInvoicesPerMonthje tada i dalje 0. -
Ponavljanje zahteva čiji ishod nije poznat. SDK sam ponavlja samo zahtev bezbedan za ponavljanje: GET i
POST /fiskalizacijačije telo nosibroj_racunakoji posletrimnije prazan (server prepoznaje već upisan račun sa istim brojem i vraća ga umesto novog; ostaje prozor kad se obrada na serveru prekine ili ne uspe posle fiskalizacije: server tada račun nije upisao, pa ponovljen zahtev sa istim brojem izdaje drugi račun, vidi „Idempotency“). Ostali zahtevi (fiskalizuj()bez broja računa,email()->send(),test()->run(), POST iz sopstvene podklaseAbstractApina drugu rutu ili bez broja računa) šalju se tačno jednom kad se ne zna da li ih je server obradio: posle 502, 503 i 504 i posle mrežne greške za koju nije sigurno da zahtev nije poslat. Izuzetak se baca odmah, bez pauze, uz WARNING (metoda, putanja bez query-ja, pokušaj, status ili klasa izuzetka — bez tela, ključa i potpisa). Na 429 (server ga vraća pre obrade) i kad zahtev sigurno nije poslat, ponavljaju se kao ranije. 503 ne vraća samo aplikacija: Apache ga vraća i kad je PHP zahtev već obradio, a odgovor se izgubio (prekinut radnik, istek roka obrade). Do 1.1.1 SDK je ponavljao svaki zahtev, pa jefiskalizuj()bez broja računa posle isteka roka mogao da izda dva računa. -
NetworkException::wasRequestSent(): ?bool—falsesamo kad je sigurno da zahtev nije poslat,truekad jeste,nullkad se ne zna. Konstruktor ima nov opcioni parametarrequestSent(podrazumevanonull), postojeći pozivi se ne menjaju.CurlHttpClientpostavljafalsesamo kad cURL nije poslao nijedan bajt zahteva (CURLINFO_REQUEST_SIZE= 0: zatvoren port, nerazrešiv host, neuspela TLS veza), inačetrue. -
#[\SensitiveParameter]nose i parametri sa zaglavljima i telom zahteva duž cele putanje slanja:FiskalizacijaApi::fiskalizuj,EmailApi::send,CurlHttpClient::request, telo uAbstractApi, ključ i telo uHmacSigner::sign,signV2,getAuthHeadersigetAuthHeadersV2. Na PHP ≥ 8.2 tragNetworkExceptionizCurlHttpClient(getTrace(),(string) $e) više ne sadrži API ključ, potpis ni telo zahteva. Na PHP 8.1 atribut nema efekta (uključitezend.exception_ignore_args=On). SopstveniHttpClientInterfaceatribut ne nasleđuje — dodajte ga na svoje parametre. -
Invoice::setIdempotencyKey()/getIdempotencyKey()su@deprecated: ključ se ni ranije nije slao serveru. Zaštita od duplog računa jesetInvoiceNumber(). -
Potpis zahteva (v2) je bez promene. Potpisi postojećih javnih metoda su isti, osim
Customer::javniSektor(string $jbkjs, ?string $ime = null, ?string $email = null, ?string $pib = null)(nov opcioni parametar$pibna kraju) i konstruktora koji su dobili nove opcione parametre na kraju (podrazumevanonull, pa postojeći pozivi rade bez izmene):NetworkException(requestSent, vidi gore),FiskalizacijaResult(success,status,brojRacuna,klijentskiBroj,duplikat,ukupanIznos,pfrDatumVreme,qrUrl,esirOznaka,errorCode,existingCopyInvoiceId),WebhookPayload(klijentskiBroj,brojRacuna,success,datumIzdavanja,errorMessage,timestamp) iTenantStatus(unlimitedInvoices, podrazumevanofalse). Nove metode suFiskalizacijaResult::isSuccess(),Invoice::setAdvertisementText(),Invoice::setOriginalInvoiceNumber(),FiskalizacijaResult::__unserialize(),WebhookPayload::__unserialize()iTenantStatus::__unserialize()(vidi „Nadogradnja na 1.2.0“).
Promene u 1.1.1
CurlHttpClientviše ne pozivacurl_close()(od PHP 8.0 nema efekta), pa na PHP 8.5 zahtev ne daje E_DEPRECATED „Function curl_close() is deprecated“.Configproverava konfiguraciju ponavljanja i bacaInvalidArgumentExceptionvan opsega:maxRetriesmora biti 0–10 (Config::MAX_RETRIES),retryBaseDelayMs≥ 0,retryMultiplier≥ 1. Podrazumevane vrednosti (3, 1000, 2) su u opsegu.- Pauza između pokušaja je najviše 60 s (
Config::MAX_RETRY_DELAY_MS= 60000 ms) i računa se bez prelivanja celog broja (ranije su vrlo velike vrednosti davaleTypeError). Podrazumevane pauze su iste: 1 s, 2 s, 4 s. Confignapravljen krozunserialize()(konstruktor se ne poziva, npr. objekat sačuvan sa 1.1.0) samaxRetries> 10 radi najviše 10 ponovljenih pokušaja. Sa negativnimmaxRetriespoziv bacaInvalidArgumentExceptionpre slanja (nijedan zahtev ne odlazi na server). Za takav objekat saretryBaseDelayMs< 0 pauza je 0, a saretryMultiplier< 1 svaka pauza je jednaka bazi (najviše 60 s).- API ključ i tajna u
Config::__construct,Config::sandbox,Config::production,EfiskalizacijaClient::create,EfiskalizacijaClient::sandboxiHmacSigner::__constructnose#[\SensitiveParameter]. To važi samo za trag izuzetka izConfig-a i fabrika: na PHP ≥ 8.2 taj trag (getTrace(),(string) $e) ne sadrži njihove vrednosti. Na PHP 8.1 atribut nema efekta — tamo uključitezend.exception_ignore_args=Onili ne prosleđujte trag izuzetka izConfig-a sistemu za praćenje grešaka. Atribut NE štiti izuzetke iz slanja zahteva:NetworkException::getTrace()nosi zaglavlja zahteva (X-API-Key,X-Signature) kao argument metoderequest()HTTP klijenta na svakoj verziji PHP-a, osim uzzend.exception_ignore_args=On. Posledica na PHP ≥ 8.2, samo uzzend.exception_ignore_args=0(inače trag nema argumente):serialize()izuzetka izConfig-a ili fabrika baca „Serialization of 'SensitiveParameterValue' is not allowed“. - Potpis zahteva (v2) i potpisi javnih metoda su bez promene.
Promene u 1.1.0
- Svaki zahtev SDK klijenta potpisuje se v2 (cilj sa query stringom) i nosi
X-Signature-Version: 2. - Nove metode
HmacSigner::signV2()iHmacSigner::getAuthHeadersV2(). Postojećesign()igetAuthHeaders()su nepromenjene (v1, kao u 1.0.2). - Query string se kodira po RFC 3986: razmak je
%20(ranije+),~ostaje nekodiran (ranije%7E), separator je uvek&(nezavisno odarg_separator.output), a query bez vrednosti (npr. samonull) ne dodaje?. - Ponovni pokušaj dobija strogo veći
X-Timestampod prethodnog pokušaja istog poziva (vidi „Retry logika“), bez dodatnog čekanja. AbstractApi::__construct()ima dva nova opciona parametra,$clocki$sleep(zamena sata i pauze, npr. u testovima); postojeći pozivi se ne menjaju.
Nadogradnja na 1.2.0
Za fiskalizaciju sa brojem računa (setInvoiceNumber()) i za GET metode ponavljanje
zahteva je isto kao u 1.1.1; rezultat i webhook sada nose polja koja su ranije bila null
(vidi „Promene u 1.2.0“). Izmene mogu trebati u ovim slučajevima:
fiskalizuj()bez broja računa,email()->send(),test()->run(): posle prekida veze, 502, 503 ili 504 dobijate izuzetak posle prvog pokušaja. Pre novog slanja proverite da li je zahtev obrađen; za fiskalizaciju je najbolje da uvek šaljete broj računa.- Sopstveni
HttpClientInterfacekoji bacaNetworkException: bezrequestSentSDK tretira ishod kao nepoznat i takav POST ne ponavlja. ProslediterequestSent: falsesamo kad je sigurno da nijedan bajt zahteva nije poslat. - Kod koji koristi
setIdempotencyKey()radi i dalje (zastarelo upozorenje samo u alatima za statičku analizu); dodajtesetInvoiceNumber(). - Kod koji čita
$result->qrCodeili$result->poruka: do 1.1.1 su uvek bilinull, sada nose vrednost (qrCodeje QR kod kao base64 PNG, ne adresa — adresa za proveru jeqrUrl). Grana koja je očekivalanullsada dobija vrednost. - Kod koji proverava ishod preko
pfrBroj: koristiteisSuccess(); za neuspeh jepfrBroji dalje prazan string. - Webhook handler:
pfrBroj,racunIdiiznossu do 1.1.1 za telo servera bilinull(polja su udata); sada nose vrednost. Porudžbinu povežite poklijentskiBroj. Za račune izdate sa 1.2.0rawDatanosi idata.kupac.pib/data.kupac.jmbgidata.stavke[].sifra_artikla; handler koji je očekivao da ih nema dobija vrednost. setNote(): tekst se ne čuva uz račun (ne vidi se na računu, u listi računa ni u admin panelu). Za tekst na računu koristitesetAdvertisementText()— štampa se na računu, pa ne šaljite interne beleške.- Šifra artikla (
InvoiceItemsasifra): šifra se sada čuva uz stavku. Šifra duža od 50 znakova se ne šalje i ne čuva, kao do 1.1.1 (račun se izdaje); ako je šifra potrebna uz račun, skratite je pre slanja. - Kod ili test koji čita
Customer::toArray()/InvoiceItem::toArray(): kupac nosipib,jmbgilijbkjsumestotipiidentifikator(Customer::javniSektor()bez$pibi dalje nositipiidentifikator), a stavkasifra_artiklaumestosifra. Javni konstruktori i fabrike (Customer::pravnoLice()…) su isti. Customer::javniSektor(): postojeći pozivi (bez$pib) šalju isto telo kao u 1.1.1, pa server račun izdaje ili odbija kao do sada. Za oznaku kupca12:PIB:JBKJSdodajte PIB kupca kao nov parametar na kraju:Customer::javniSektor('54321', pib: '123456789'); do 1.1.1 server je račun sa JBKJS-om odbijao. Avans za javni sektor izdajte krozCustomer::pravnoLice().- Kopija računa (
InvoiceType::Kopija): bez promene dok ne pozovetesetOriginalInvoiceNumber()(vidi „Kopija računa“). TenantStatus::$maxInvoicesPerMonthje 0 i za nalog bez limita; proverite prvounlimitedInvoices.FiskalizacijaResult,WebhookPayload,TenantStatusiliInvoicesačuvan krozserialize()(keš, red poruka, sesija) sa 1.1.1 ili starijom verzijom:unserialize()sa 1.2.0 radi, sačuvana svojstva zadržavaju vrednost, a nova (success,duplikat,klijentskiBroj…) sunull;unlimitedInvoicesjefalse, aInvoicese šalje kao ranije (bez broja originala). Kupac izCustomer::javniSektor()sačuvan sa 1.1.1 šalje se kao u 1.1.1 (tip+identifikator), osim vrednosti u oblikuPIB:JBKJS, koja ide kaojbkjs.isSuccess()za takav rezultat odlučuje popfrBroj.
Povratak na 1.1.x (composer require infogrambeg/efiskalizacija-php-sdk:1.1.1) radi:
objekat koji je serijalizovala 1.2.0, a deserijalizuje ga 1.1.x, zadržava vrednosti
svojstava koja postoje u 1.1.x. Na PHP ≥ 8.2 svako svojstvo dodato u 1.2.0 pri tome daje
E_DEPRECATED „Creation of dynamic property“ (11 kod FiskalizacijaResult, 6 kod
WebhookPayload, 1 kod TenantStatus i 2 kod Invoice); vrednosti se čitaju normalno.
Invoice sa brojem originala 1.1.x šalje kao kopiju bez broja originala
(tip_racuna: "kopija"), a 1.1.x šifru artikla i kupca šalje pod starim ključevima.
Nadogradnja sa 1.0.x
Za korisnike koji samo pozivaju metode klijenta ($client->fiskalizacija(),
->invoices(), ->pdf() …) nadogradnja ne traži izmene koda. Izmene mogu trebati u
ovim slučajevima:
- Direktan poziv
HmacSigner::sign()/getAuthHeaders()(sopstveni potpis bez SDK klijenta) i dalje radi bez izmena: obe metode potpisuju v1 bajt-isto kao 1.0.2 (query se odseca, bezX-Signature-Version). Za v2 pređite nasignV2()/getAuthHeadersV2():$targetje tačan cilj sa query-jem kako se šalje, a zahtev mora nositi zaglavljeX-Signature-Version: 2—getAuthHeadersV2()ga vraća,signV2()ne. - Sopstveni
HttpClientInterface: mora poslati$urlbez prepakivanja (vidi gore). - Bazni URL sa putanjom: vidi gore.
Configsa granicama ponavljanja van opsega:ConfigsamaxRetriesvan 0–10,retryBaseDelayMs< 0 iliretryMultiplier< 1 bacaInvalidArgumentExceptionpri konstrukciji od 1.1.1 (ranije je prihvatan). Od 1.1.1 je i pauza između pokušaja najviše 60 s (Config::MAX_RETRY_DELAY_MS), pa konfiguracija sa dužim pauzama čeka kraće.
Povratak na 1.0.2 (composer require infogrambeg/efiskalizacija-php-sdk:1.0.2) radi,
jer server i dalje prima potpis v1. Objekat koji je serijalizovala 1.1.0, a deserijalizuje
ga 1.0.2 na PHP ≥ 8.2, daje E_DEPRECATED za dinamička svojstva $clock i $sleep
(„Creation of dynamic property“); zahtevi rade.
Retry logika
SDK automatski ponavlja zahtev posle prolazne greške (exponential backoff), ali od 1.2.0
samo zahtev bezbedan za ponavljanje ili zahtev za koji je sigurno da ga server nije
obradio. Zahtev je bezbedan za
ponavljanje kad je GET ili POST /fiskalizacija čije telo nosi broj_racuna koji
posle trim nije prazan (vidi „Idempotency“). Svi ostali zahtevi — fiskalizuj() bez
broja računa, email()->send(), test()->run(), POST iz sopstvene podklase na drugu
rutu ili bez broja računa — ponavljaju se samo kad je sigurno da server zahtev nije
obradio:
| Greška | GET i POST /fiskalizacija sa brojem |
Ostali zahtevi |
|---|---|---|
| 429 (Rate Limit) | Da | Da |
| 502 (Bad Gateway) | Da | Ne |
| 503 (Unavailable) | Da | Ne |
| 504 (Gateway Timeout) | Da | Ne |
| Mrežna greška, zahtev nije poslat | Da | Da |
| Mrežna greška, ishod nepoznat | Da | Ne |
| 400 (Validacija) | Ne | Ne |
| 401 (Auth) | Ne | Ne |
| 403 (Zabranjeno) | Ne | Ne |
| 422 (Validacija) | Ne | Ne |
429 server vraća pre obrade zahteva (ograničenje učestalosti). Za 503 to ne važi: Apache
(mod_proxy_fcgi) ga vraća, kao HTML bez Retry-After, i kad je PHP zahtev već obradio,
a odgovor se izgubio (prekinut radnik, istek roka obrade). „Zahtev nije poslat“ je
NetworkException sa wasRequestSent() === false (CurlHttpClient: cURL nije poslao
nijedan bajt — zatvoren port, nerazrešiv host, neuspela TLS veza). „Ishod nepoznat“ je
svaka druga mrežna greška (npr. istek roka posle slanja). Kad SDK zahtev ne ponovi zato
što ishod nije poznat, izuzetak se baca odmah, bez pauze, uz WARNING u logger-u (bez
tela, ključa i potpisa).
Ni bezbedan zahtev nije potpuno zaštićen: kad se obrada na serveru prekine ili ne uspe
posle fiskalizacije (pad servera, istek odgovora Poreske uprave), račun postoji, ali ga
server nije upisao, pa se ne vidi ni u invoices()->list() ni u admin panelu, a ponovljen
zahtev sa istim brojem izdaje drugi račun (vidi „Idempotency“). Kad ishod ostane nepoznat i
posle poslednjeg pokušaja, sa brojem računa ili bez njega, proverite da li je račun izdat;
provera nalazi samo upisan račun, pa kad ga ne nađe, pre novog slanja obratite se podršci.
Podrazumevano: početni zahtev + do 3 ponavljanja (maxRetries: 3), pauze 1 s / 2 s / 4 s.
Konfigurisano u Config.
Svaki ponovni pokušaj se potpisuje iznova i dobija strogo veći X-Timestamp od
prethodnog pokušaja, pa nijedna dva pokušaja nemaju isti potpis: timestamp pokušaja je
max(tekući sat, prethodni + 1), bez ikakvog dodatnog čekanja. Prvi pokušaj nosi tekući
sat. Kad su pokušaji brži od 1 s (razmak ispod 1 s), timestamp može biti ispred sata
najviše za k sekundi, gde je k broj ponovljenih pokušaja do tog trenutka (najviše
maxRetries); kad sat tokom poziva skoči unazad za J sekundi, za J + k. Server prihvata
timestamp ±300 s od svog sata, pa sat servera i klijenta treba da budu sinhronizovani
(NTP).
Granica: od 1.1.1 maxRetries je najviše 10 (Config::MAX_RETRIES). Za Config
dobijen kroz unserialize() (bez konstruktora) maxRetries > 10 se ograničava na 10, a
negativan baca InvalidArgumentException pre slanja. Zato je timestamp ispred sata
najviše 10 s (uz skok sata unazad J + 10), daleko unutar tolerancije servera.
Pauza između pokušaja je najviše 60 s (Config::MAX_RETRY_DELAY_MS).
Webhook
use Efiskalizacija\Webhook\WebhookPayload; // U vašem webhook handler-u $payload = WebhookPayload::fromJson(file_get_contents('php://input')); if ($payload->isFiscalized()) { // Račun uspešno fiskalizovan; porudžbinu povežite po broju iz setInvoiceNumber() $porudzbina = $payload->klijentskiBroj; // null kad račun nije poslat sa brojem $pfr = $payload->pfrBroj; $iznos = $payload->iznos; } if ($payload->isFailed()) { // Fiskalizacija neuspešna $razlog = $payload->errorMessage; }
Server šalje polja računa u data (invoice_id, invoice_number, klijentski_broj,
success, pfr_broj, ukupan_iznos, datum_izdavanja, error_message); SDK ih čita u
racunId, brojRacuna, klijentskiBroj, success, pfrBroj, iznos, datumIzdavanja
i errorMessage. Detalji računa (stavke, kupac, nacin_placanja …) su u rawData.
Custom HTTP klijent
SDK koristi cURL po defaultu. Možete ubaciti svoj HTTP klijent (npr. za WordPress wp_remote_request):
use Efiskalizacija\Http\HttpClientInterface; use Efiskalizacija\Http\Response; class WpHttpClient implements HttpClientInterface { public function request(string $method, string $url, array $headers = [], string $body = ''): Response { $response = wp_remote_request($url, [ 'method' => $method, 'headers' => $headers, 'body' => $body, 'timeout' => 30, ]); return new Response( wp_remote_retrieve_response_code($response), wp_remote_retrieve_body($response), wp_remote_retrieve_headers($response)->getAll(), ); } } $client = new EfiskalizacijaClient($config, new WpHttpClient());
Konfiguracija
Okruženja
| Okruženje | URL | Namena |
|---|---|---|
| Production | https://efiskalizacija.cloud |
Pravi fiskalni računi |
| Sandbox | https://staging.efiskalizacija.cloud |
Testiranje integracije |
// Sandbox (testiranje) $client = EfiskalizacijaClient::sandbox($apiKey, $apiSecret); // Production (podrazumevano) $client = EfiskalizacijaClient::create($apiKey, $apiSecret);
Preporučena konfiguracija (.env)
Nikad ne čuvajte API kredencijale u kodu. Koristite environment varijable:
EFISK_API_KEY=efisk_1_abc123... EFISK_API_SECRET=your-64-char-secret EFISK_SANDBOX=true
$apiKey = $_ENV['EFISK_API_KEY'] ?? getenv('EFISK_API_KEY'); $apiSecret = $_ENV['EFISK_API_SECRET'] ?? getenv('EFISK_API_SECRET'); $sandbox = filter_var($_ENV['EFISK_SANDBOX'] ?? getenv('EFISK_SANDBOX'), FILTER_VALIDATE_BOOLEAN); $client = $sandbox ? EfiskalizacijaClient::sandbox($apiKey, $apiSecret) : EfiskalizacijaClient::create($apiKey, $apiSecret);
Napredna konfiguracija
use Efiskalizacija\Config; $config = new Config( apiKey: $apiKey, apiSecret: $apiSecret, baseUrl: 'https://efiskalizacija.cloud', // default timeout: 30, // HTTP timeout (sekunde) connectTimeout: 10, // Connection timeout (sekunde) maxRetries: 3, // Broj retry pokušaja (0–10) retryBaseDelayMs: 1000, // Početni delay (ms, ≥ 0; pauza najviše 60 s) retryMultiplier: 2, // Multiplier za exponential backoff (≥ 1) ); $client = new EfiskalizacijaClient($config);
Testiranje
composer test
Licenca
MIT