Brzi start

Integrišite eFiskalizacija API u vaš web šop za nekoliko minuta. Ovaj vodič pokriva sve korake od dobijanja kredencijala do prvog fiskalnog računa.

Napomena: eFiskalizacija.cloud je namenjen isključivo za web šopove i daljinsku prodaju (e-commerce). Nije predviđen za maloprodajne objekte sa fizičkim POS terminalima.

1. Dobijte API kredencijale

Pošaljite email na info@efiskalizacija.cloud sa sledećim podacima:

Naziv firme - Pun naziv pravnog lica
PIB - Poreski identifikacioni broj
Kontakt - Email i telefon tehničkog lica

Nakon obrade zahteva dobijate:

API Key - Javni ključ za identifikaciju
API Secret - Tajni ključ za HMAC potpisivanje (čuvajte bezbedno!)

Upozorenje: API Secret se prikazuje samo jednom prilikom generisanja. Sačuvajte ga odmah na bezbedno mesto. Ako ga izgubite, potrebno je regenerisati nove kredencijale.

2. Pošaljite PFX sertifikat

Elektronski sertifikat (.pfx fajl) koji ste dobili od Poreske uprave Republike Srbije pošaljite na siguran način:

Enkriptovan email ili
Siguran file-sharing servis (sa lozinkom)

Uz sertifikat pošaljite i lozinku za otključavanje (odvojenim kanalom komunikacije).

Napomena: Sertifikat je neophodan za digitalno potpisivanje fiskalnih računa prema zahtevima Poreske uprave. Bez njega fiskalizacija nije moguća.

3. Testirajte integraciju

Koristite sledeći cURL primer za slanje prvog test zahteva sa HMAC autentifikacijom:

#!/bin/bash

# Vaši kredencijali
API_KEY="your-api-key"
API_SECRET="your-api-secret"

# Priprema zahteva
TIMESTAMP=$(date +%s)
BODY='{"stavke":[{"naziv":"Test proizvod","kolicina":1,"jedinicna_cena":100,"pdv_stopa":20}],"nacin_placanja":"gotovina","tip_racuna":"prodaja"}'
# Napomena: pdv_stopa je 20 za produkciju, 19 za sandbox

# HMAC potpis
BODY_HASH=$(echo -n "$BODY" | sha256sum | cut -d' ' -f1)
STRING_TO_SIGN="${TIMESTAMP}POST/api/multitenant.php/fiskalizacija${BODY_HASH}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

# Slanje zahteva
curl -X POST https://efiskalizacija.cloud/api/multitenant.php/fiskalizacija \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

Uspešan odgovor sadrži PFR broj (verifikacioni kod) fiskalnog računa:

{
  "success": true,
  "pfr_broj": "XXXXXXXX-XXXXXXXX-12345",
  "broj_racuna": "1",
  "qr_url": "https://suf.purs.gov.rs/v/?vl=..."
}

4. PHP primer

Kompletna PHP funkcija sa HMAC potpisivanjem koju možete direktno koristiti u vašem projektu:

<?php
declare(strict_types=1);

function fiskalizuj(array $stavke, string $nacinPlacanja, string $tipRacuna = 'prodaja'): array
{
    $apiKey = getenv('EFISK_API_KEY');
    $apiSecret = getenv('EFISK_API_SECRET');
    $baseUrl = 'https://efiskalizacija.cloud';
    $endpoint = '/api/multitenant.php/fiskalizacija';

    // Priprema tela zahteva
    $body = json_encode([
        'stavke' => $stavke,
        'nacin_placanja' => $nacinPlacanja,
        'tip_racuna' => $tipRacuna,
    ], JSON_UNESCAPED_UNICODE);

    // HMAC potpis
    $timestamp = (string) time();
    $bodyHash = hash('sha256', $body);
    $stringToSign = $timestamp . 'POST' . $endpoint . $bodyHash;
    $signature = base64_encode(
        hash_hmac('sha256', $stringToSign, $apiSecret, true)
    );

    // Slanje zahteva
    $ch = curl_init($baseUrl . $endpoint);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $apiKey,
            'X-Timestamp: ' . $timestamp,
            'X-Signature: ' . $signature,
        ],
        CURLOPT_TIMEOUT => 30,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new RuntimeException("Greška pri fiskalizaciji: HTTP $httpCode - $response");
    }

    return json_decode($response, true);
}

// Primer korišćenja:
$rezultat = fiskalizuj(
    stavke: [
        [
            'naziv' => 'Laptop ASUS VivoBook',
            'kolicina' => 1,
            'jedinicna_cena' => 89990,
            'pdv_stopa' => 20,
        ],
    ],
    nacinPlacanja: 'kartica'
);

echo "PFR broj: " . $rezultat['pfr_broj'];

Preporuka: API kredencijale čuvajte u environment varijablama (.env fajl), nikada ih ne upisujte direktno u izvorni kod.

5. Najčešći slučajevi korišćenja

Web šop - fizički proizvod

Klasičan primer za online prodavnicu koja prodaje fizičke proizvode sa dostavom:

{
  "stavke": [
    {
      "naziv": "Bežične slušalice Sony WH-1000XM5",
      "kolicina": 1,
      "jedinicna_cena": 54990,
      "pdv_stopa": 20
    },
    {
      "naziv": "Zaštitna futrola",
      "kolicina": 1,
      "jedinicna_cena": 2490,
      "pdv_stopa": 20,
      "rabat_procenat": 10
    }
  ],
  "nacin_placanja": "kartica",
  "tip_racuna": "prodaja",
  "kupac": {
    "pib": "107026577",
    "ime": "Primer d.o.o.",
    "adresa": "Bulevar Mihajla Pupina 10, Beograd"
  }
}

Digitalni proizvod

Prodaja softvera, licenci ili digitalnog sadržaja:

{
  "stavke": [
    {
      "naziv": "Premium licenca - godišnja pretplata",
      "kolicina": 1,
      "jedinicna_cena": 11880,
      "pdv_stopa": 20
    }
  ],
  "nacin_placanja": "kartica",
  "tip_racuna": "prodaja"
}

E-commerce usluge

Pružanje online usluga (konsalting, dizajn, hosting):

{
  "stavke": [
    {
      "naziv": "Web hosting - mesečni paket",
      "kolicina": 12,
      "jedinicna_cena": 990,
      "pdv_stopa": 20
    },
    {
      "naziv": "SSL sertifikat",
      "kolicina": 1,
      "jedinicna_cena": 4990,
      "pdv_stopa": 20
    }
  ],
  "nacin_placanja": "virman",
  "tip_racuna": "prodaja",
  "kupac": {
    "pib": "123456789",
    "ime": "Klijent d.o.o.",
    "adresa": "Knez Mihailova 5, Beograd"
  }
}

Napomena: Polje kupac je opciono. Obavezno je samo kada kupac zahteva račun na firmu (sa PIB-om). Za fizička lica bez identifikacije, izostavite ceo kupac objekat.

6. Često postavljana pitanja (FAQ)

Koliko traje obrada zahteva?

Prosečno vreme odgovora je 1-3 sekunde. VSDC (Virtualni Sigurni Digitalni Čip) Poreske uprave obrađuje zahtev i vraća verifikacioni kod. Preporučujemo timeout od 30 sekundi za sigurnost.

Koji su podržani načini plaćanja?

Vrednost	Opis
`gotovina`	Gotovina (pouzeće)
`kartica`	Platna kartica
`virman`	Virmansko plaćanje
`vaucer`	Vaučer / poklon kartica
`instant`	Instant plaćanje (IPS QR)
`drugo`	Drugo bezgotovinsko plaćanje

Šta ako VSDC nije dostupan?

U slučaju nedostupnosti VSDC servisa, API vraća odgovarajuću grešku. Preporučujemo implementaciju retry mehanizma sa eksponencijalnim back-off-om (npr. pokušaji nakon 5s, 15s, 45s).

Kako da testiram bez stvarne fiskalizacije?

Koristite tip računa "tip_racuna": "obuka" (Training režim). Ovi računi prolaze kroz VSDC ali nisu fiskalno validni. Na njima stoji oznaka "OVO NIJE FISKALNI RAČUN".

Da li mogu poslati više stavki u jednom računu?

Da, niz stavke može sadržati neograničen broj artikala. Svaka stavka mora imati naziv, kolicina, jedinicna_cena i pdv_stopa. Opciono možete dodati popust (fiksni iznos u RSD) ili rabat_procenat (0-100%) - ali ne oba istovremeno na istoj stavci. Sistem automatski izračunava ukupne iznose i PDV.

7. Kontakt i podrška

Za sva pitanja, tehničku podršku ili prijavu problema:

Email: info@efiskalizacija.cloud

Dodatni resursi:

Kompletna API referenca - svi endpointi i parametri
Autentifikacija (HMAC) - detaljan opis potpisivanja
Swagger UI - interaktivni API explorer
Vodič za integraciju - napredni scenariji