Sadržaj

• 1. Preduslovi za instalaciju
• 2. Registracija i aktivacija naloga
• 3. Preuzimanje kredencijala
• 4. Konfiguracija API integracije
• 5. Test konekcije (Sandbox)
• 6. Prelazak na produkciju
• 7. Verifikacija instalacije
• 8. Česta pitanja pri instalaciji
• Prilog A: Checklist za instalaciju
• Prilog B: Kontakt podrška

1. Preduslovi za instalaciju

1.1 Tip obveznika

Pre instalacije, uverite se da vaš poslovni model odgovara nameni ovog ESIR sistema:

1.2 Tehnički preduslovi

1.3 Potrebna dokumentacija

Za registraciju pripremite:

• PIB obveznika
• Matični broj
• Rešenje o registraciji APR
• Kontakt podaci odgovornog lica
• Tehnički kontakt za integraciju

2. Registracija i aktivacija naloga

3. Preuzimanje kredencijala

3.1 Pristup Admin panelu

Nakon aktivacije, pristupite admin panelu:

https://efiskalizacija.cloud/admin/

Unesite korisničko ime i lozinku iz aktivacionog email-a.

3.2 API kredencijali

U sekciji Bezbednost pronađite vaše API kredencijale:

3.3 Regeneracija kredencijala

Ako izgubite API Secret ili sumnjate na kompromitaciju:

1. Pristupite Bezbednost sekciji
2. Kliknite Regeneriši kredencijale
3. Potvrdite akciju
4. Sačuvajte novi API Secret
5. Ažurirajte vašu aplikaciju sa novim kredencijalima

4. Konfiguracija API integracije

4.1 API Endpoints

4.2 Konfiguracija autentifikacije

Svaki API zahtev mora sadržati sledeće HTTP header-e:

X-Api-Key: vaš_api_key
X-Timestamp: unix_timestamp_u_sekundama
X-Signature: hmac_sha256_potpis

4.3 Generisanje potpisa (HMAC-SHA256)

PHP primer:

<?php
$apiKey = getenv('EFISK_API_KEY');
$apiSecret = getenv('EFISK_API_SECRET');

$timestamp = time();
$body = json_encode($data);

// String za potpisivanje: timestamp + body
$stringToSign = $timestamp . $body;

// HMAC-SHA256 potpis
$signature = hash_hmac('sha256', $stringToSign, $apiSecret);

// HTTP headers
$headers = [
    'Content-Type: application/json',
    'X-Api-Key: ' . $apiKey,
    'X-Timestamp: ' . $timestamp,
    'X-Signature: ' . $signature
];

JavaScript/Node.js primer:

const crypto = require('crypto');

const apiKey = process.env.EFISK_API_KEY;
const apiSecret = process.env.EFISK_API_SECRET;

const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify(data);

const stringToSign = timestamp + body;
const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(stringToSign)
    .digest('hex');

const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature
};

4.4 Environment varijable

Preporučena konfiguracija:

# .env fajl (NE UKLJUČIVATI U GIT!)
EFISK_API_KEY=vaš_api_key
EFISK_API_SECRET=vaš_api_secret
EFISK_API_URL=https://efiskalizacija.cloud/api/multitenant.php

5. Test konekcije (Sandbox)

5.1 Status endpoint

Testirajte konekciju pozivom status endpoint-a:

GET /status

Očekivani odgovor:

{
    "success": true,
    "data": {
        "status": "operational",
        "version": "1.2.0",
        "tenant": "Naziv vašeg tenanta"
    }
}

5.2 Test fiskalizacije

Pošaljite test račun u sandbox okruženju:

POST /fiskalizacija

{
    "tip_racuna": "prodaja",
    "nacin_placanja": "kartica",
    "stavke": [
        {
            "naziv": "Test artikal",
            "kolicina": 1,
            "cena": 100.00,
            "pdv_stopa": 20
        }
    ]
}

5.3 Verifikacija odgovora

Uspešan odgovor sadrži:

{
    "success": true,
    "data": {
        "pfr_broj": "XXXXXXXX-XXXXXXXX-12345",
        "broj_racuna": "1/2026",
        "ukupan_iznos": 100.00,
        "qr_url": "https://...",
        "pdf_url": "https://..."
    }
}

6. Prelazak na produkciju

6.1 Checklist pre produkcije

• Uspešno testirani svi tipovi transakcija u sandbox-u
• API Secret bezedno čuvan (ne u kodu)
• Error handling implementiran
• Retry mehanizam za neuspele zahteve
• Logovanje API poziva
• PDF računi se pravilno prikazuju

6.2 Promena URL-a

Zamenite sandbox URL sa produkcijskim:

# Sandbox (test)
EFISK_API_URL=https://sandbox.efiskalizacija.cloud/api/multitenant.php

# Produkcija
EFISK_API_URL=https://efiskalizacija.cloud/api/multitenant.php

7. Verifikacija instalacije

7.1 Funkcionalni testovi

7.2 Provera u Admin panelu

1. Prijavite se na admin panel
2. Otvorite sekciju Računi
3. Proverite da li se prikazuju fiskalizovani računi
4. Otvorite detalje računa i proverite PDF

8. Česta pitanja pri instalaciji

Greška: "Invalid signature"

Uzrok: Neispravan HMAC potpis.

Rešenje:

• Proverite da li koristite ispravan API Secret
• Proverite format timestamp-a (Unix sekunde, ne milisekunde)
• Proverite da je string za potpisivanje: timestamp + body

Greška: "Timestamp expired"

Uzrok: Timestamp zahteva je stariji od 5 minuta.

Rešenje: Sinhronizujte sistemsko vreme sa NTP serverom.

Greška: "Rate limit exceeded"

Uzrok: Previše zahteva u kratkom periodu.

Rešenje: Implementirajte exponential backoff. Limit je 60 zahteva po minutu.

Greška: "VSDC unavailable"

Uzrok: VSDC servis Poreske uprave nije dostupan.

Rešenje: Sačekajte i pokušajte ponovo. Implementirajte retry sa backoff-om.

Prilog A: Checklist za instalaciju

Pre instalacije

• Verifikovan tip obveznika (web shop / e-commerce)
• Pripremljena dokumentacija (PIB, APR rešenje)
• Definisan tehnički kontakt

Registracija

• Poslat zahtev za registraciju
• Dostavljena dokumentacija
• Potpisan ugovor
• Primljen aktivacioni email

Konfiguracija

• Pristup admin panelu potvrđen
• API Key preuzet
• API Secret bezbedno sačuvan
• Environment varijable konfigurisane

Integracija

• HMAC-SHA256 implementiran
• Status endpoint testiran
• Test fiskalizacija uspešna (sandbox)
• PDF generisanje testirano
• Error handling implementiran

Produkcija

• URL promenjen na produkcijski
• Prva produkcijska fiskalizacija uspešna
• Račun vidljiv u admin panelu
• QR kod verifikovan

Prilog B: Kontakt podrška

Tehnička podrška

Dokumentacija

Proizvođač

Infogram d.o.o. Beograd
Kneza Višeslava 63
11000 Beograd, Srbija
PIB: 107026577
MB: 20476061