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.

1Dobijte 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!)

2Pošaljite PEM sertifikat

Elektronski sertifikat u PEM formatu 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).

3Testirajte 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: jedinicna_cena je cena BEZ PDV-a (osnovica). PDV se obračunava na vrhu.
# pdv_stopa: 20 za produkciju (https://efiskalizacija.cloud), 19 za sandbox/test (https://staging.efiskalizacija.cloud)

# 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 ima sledeću strukturu:

{
  "success": true,
  "data": {
    "tenant": "Naziv firme d.o.o.",
    "rezultat": {
      "success": true,
      "racun_id": 123,
      "broj_racuna": "1",
      "ukupan_iznos": 120.00,
      "pfr_broj": "XXXXXXXX-XXXXXXXX-12345",
      "pfr_datum_vreme": "2026-01-05T10:30:00+01:00",
      "qr_kod": "data:image/png;base64,...",
      "status": "success",
      "message": "Fiskalizacija uspešno izvršena"
    }
  },
  "timestamp": "2026-01-05T10:30:00+01:00"
}

4PHP 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['data']['rezultat']['pfr_broj'];

5Najč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"
  }
}

6Često postavljana pitanja (FAQ)

Koliko traje obrada zahteva?

Prosečno vreme odgovora je 1-3 sekunde. VSDC (Virtual Sales Data Controller — virtuelni procesor fiskalnih računa 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
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. ponovni pokušaji nakon 1s, 2s, 4s (maksimalno 3 pokušaja).

Kako da testiram bez stvarne fiskalizacije?

Koristite tip računa "tip_racuna": "obuka" (Training režim, interni kod T, VSDC InvoiceType: 3). Ovi računi se šalju VSDC-u i dobijaju PFR broj, ali su eksplicitno označeni kao nevažeći — na računu piše "OVO NIJE FISKALNI RAČUN". Korisni za testiranje integracije bez trošenja kvote pravih računa.

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.

7Kontakt 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