Kratek pregled za vodjo in natančen postopek za razvijalca, ki povezuje elektronsko blagajno, spletno trgovino ali ERP s FURS.
Podjetje ostane odgovorno za pravilnost računov, certifikat in pravočasno oddajo. Storitev tehnično izvede komunikacijo s FURS in hrani poslovne rezultate.
Spodnji postopek pokriva vse korake od administratorske priprave do produkcije. Primeri so za API v1, uporabljajo UTF-8 in ne vsebujejo skrivnosti.
Administrator ustvari ali spremeni Naročnika, rotira API ključ in dodeli licenco. Naročnik sam naloži TEST ali produkcijski certifikat ter sam vključi ali izključi prometni dnevnik. Razvijalec prijavi prostore, vodi naprave in izdaja račune. Odgovorna oseba potrdi davčno in poslovno pravilnost.
TEST uporablja demo certifikat in izključno testne podatke; Production uporablja veljaven produkcijski certifikat in resnične račune. Klici Naročnika zahtevajo X-Tenant-Id in X-Api-Key. Idempotency-Key je potreben za zapisne operacije proti FURS in ni access token.
X-Tenant-Id: YOUR_TENANT_ID
X-Api-Key: YOUR_API_KEY
Content-Type: application/json; charset=utf-8
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Trenutke hranite v UTC. API sprejme ISO 8601 z Z ali odmikom, nato pa tik pred podpisom FURS protokola čas pretvori v Europe/Ljubljana. validityDate poslovnega prostora je koledarski datum brez ure.
Samo Administrator lahko ustvari ali spremeni Naročnika. STANDARD_200 vključuje 200 oddaj mesečno in evidentira presežek, ne da bi blokiral fiskalizacijo. INTERNAL_UNLIMITED je brezplačna neomejena licenca, ki jo administrator ročno dodeli pravilnemu obstoječemu Naročniku Simple-Tasks.
POST /api/Tenants
Authorization: Bearer YOUR_ADMIN_JWT
{
"name": "Primer d.o.o.",
"taxNumber": "10195904",
"address": "Slovenska cesta 1",
"postalCode": "1000",
"city": "Ljubljana",
"countryCode": "SI",
"contactEmail": "racuni@example.si",
"billingEmail": "finance@example.si",
"logTraffic": false
}POST /api/Tenants/YOUR_TENANT_ID/licenses
Authorization: Bearer YOUR_ADMIN_JWT
{
"planCode": "STANDARD_200",
"status": "Active",
"validFromUtc": "2026-09-10T00:00:00Z",
"validUntilUtc": null,
"monthlySubmissionLimit": 200,
"currency": "EUR",
"monthlyPriceExVat": 19.90,
"overagePriceExVat": 0.03,
"isComplimentary": false
}Naročnik naloži celoten PKCS#12/PFX z zasebnim ključem. Zahtevek nima tehničnega polja tenantId ali taxNumber v bodyju; davčna številka se izpelje iz avtenticiranega Naročnika. API vrne samo varne metapodatke in nikoli ne vrne zaščitenih bajtov ali gesla.
POST /api/v1/tenant/certificates
X-Tenant-Id: YOUR_TENANT_ID
X-Api-Key: YOUR_API_KEY
{
"environment": "Test",
"pkcs12": "YOUR_CERT_BASE64",
"password": "YOUR_CERT_PASSWORD"
}GET vrne certifikate Naročnika in podrobnost. PUT z isActive=false certifikat deaktivira, PUT z isActive=true pa ga aktivira; aktivacija novega certifikata deaktivira prejšnjega samo v istem okolju.
Echo hkrati preveri Naročnika, aktivno licenco, izbrani certifikat, zasebni ključ, TLS in dosegljivost FURS. Uspeh je success=true in value=furs. Echo ne prijavlja prostora in ne šteje mesečne porabe.
GET /api/v1/fiscalization/echo?environment=Test
{
"success": true,
"value": "furs",
"errorMessage": null
}Za premični prostor uporabite movablePremiseType, za nepremičnino realEstate, za avtomat vendingMachine. Izpolnjena mora biti natanko ena vrsta identifikatorja. businessPremiseId je poslovna FURS oznaka, lokalni GUID iz seznama pa identifikator zapisa v tej storitvi.
POST /api/v1/fiscalization/business-premises
Idempotency-Key: NEW_UUID
{
"environment": "Test",
"businessPremise": {
"taxNumber": "10195904",
"businessPremiseId": "LJOFFICE",
"businessPremiseIdentifier": { "movablePremiseType": "C" },
"validityDate": "2026-09-10",
"closing": false,
"softwareSuppliers": [{ "taxNumber": "10195904" }],
"specialNotes": "UTF-8: č š ž"
}
}Zaprtje je trajna FURS operacija: isti BusinessPremise DTO pošljite na /closures z closing=true. Testirajte ga samo na namenskem prostoru, na primer CLOSEME1.
Elektronska naprava je lokalna evidenca Naročnika. FURS njeno oznako prejme kot del številke računa, nima pa ločenega protokola za prijavo ali brisanje naprave. PUT z isActive=false prepreči nove račune, ponovna nastavitev true pa uporabo spet dovoli.
POST /api/v1/fiscalization/electronic-devices
{
"environment": "Test",
"businessPremiseId": "LJOFFICE",
"electronicDeviceId": "CASHREGISTER1",
"description": "Web register",
"isActive": true
}
PUT /api/v1/fiscalization/electronic-devices/YOUR_DEVICE_DB_GUID
{ "description": "Web register", "isActive": false }invoiceNumber mora biti pozitivna številčna poslovna oznaka, ne GUID. Poslovni prostor mora biti odprt, naprava aktivna in oba v istem okolju. Pri uspehu shranite EOR, ZOI, QR payload, messageId, responseDateTime in outcome.
POST /api/v1/fiscalization/invoices
Idempotency-Key: NEW_UUID
{
"environment": "Test",
"invoice": {
"taxNumber": "10195904",
"issueDateTime": "2026-09-10T10:38:22+02:00",
"numberingStructure": "B",
"invoiceIdentifier": {
"businessPremiseId": "LJOFFICE",
"electronicDeviceId": "CASHREGISTER1",
"invoiceNumber": "1"
},
"invoiceAmount": 12.20,
"paymentAmount": 12.20,
"taxesPerSeller": [{
"sellerTaxNumber": null,
"vat": [{ "taxRate": 22.00, "taxableAmount": 10.00, "taxAmount": 2.20 }]
}],
"operatorTaxNumber": "10195904",
"foreignOperator": false,
"subsequentSubmit": false
}
}Storno je nov račun z negativnimi zneski in novo lastno invoiceNumber. referenceInvoices mora vsebovati poslovno FURS identifikacijo originala in čas njegove izdaje. Uporabite na primer invoiceNumber 1 iz originala, nikoli njegovega lokalnega GUID-a.
POST /api/v1/fiscalization/cancellations
Idempotency-Key: NEW_UUID
{
"environment": "Test",
"cancellationInvoice": {
"taxNumber": "10195904",
"issueDateTime": "2026-09-10T18:25:00+02:00",
"numberingStructure": "B",
"invoiceIdentifier": {
"businessPremiseId": "LJOFFICE",
"electronicDeviceId": "CASHREGISTER1",
"invoiceNumber": "2"
},
"invoiceAmount": -12.20,
"paymentAmount": -12.20,
"taxesPerSeller": [{ "vat": [{ "taxRate": 22.00, "taxableAmount": -10.00, "taxAmount": -2.20 }] }],
"operatorTaxNumber": "10195904",
"foreignOperator": false,
"subsequentSubmit": false,
"referenceInvoices": [{
"invoiceIdentifier": {
"businessPremiseId": "LJOFFICE",
"electronicDeviceId": "CASHREGISTER1",
"invoiceNumber": "1"
},
"issueDateTime": "2026-09-10T10:38:22+02:00"
}]
}
}Za vnaprej oštevilčene račune iz vezane knjige uporabite /sales-book-invoices. Zahtevek vsebuje SalesBookIdentifier in ne uporablja elektronske naprave. Uspešen odgovor lahko vsebuje EOR brez ZOI in QR kode.
Paket vsebuje od 2 do 500 zapisov. /invoice-batches vrne rezultate po recordNumber, medtem ko /business-premise-batches lahko ob uspehu vrne prazen records. En Idempotency-Key velja za cel paket; poraba se šteje za vsak račun v paketu.
GET /invoices podpira filtre environment, businessPremiseId, electronicDeviceId, invoiceNumber, success, isCancellation, from, to in take. Podobno lahko berete prostore, naprave in certifikate. Intervala from in to pošljite v UTC ISO 8601.
Isti ključ z istim bodyjem vrne shranjen rezultat brez ponovne oddaje in brez dvojnega štetja. Isti ključ z drugačnim bodyjem vrne HTTP 409. Accepted shranite; Rejected popravite in pošljite kot nov zahtevek; RetryableFailure ponovite z istim ključem; pri Unknown najprej preverite stanje.
400 pomeni neveljaven DTO ali pogodbo FURS, 401 napačnega Naročnika oziroma ključ, 403 neaktivno licenco, 404 tuj ali manjkajoč vir, 409 konflikt idempotence, 429 omejitev in 500 nepričakovano napako. transport_timeout je lahko varen za ponovitev; transport_failure in invalid_signature zahtevata preverjanje certifikata, TLS, payload-a, podpisa in časa.
Beleženje je za Naročnika privzeto izključeno. Stanje preveri z GET /api/v1/tenant/traffic-logging ter ga sam vključi ali izključi s PUT in bodyjem {"logTraffic":true|false}. Beležijo se metoda, URL, query, UTC čas, okolje, status, trajanje ter očiščena in zaščitena request/response bodyja. Skrivnosti in QR PNG se ne hranijo; zapisi se hranijo največ 90 dni.
Uvozite samo aktualno zbirko iz docs/postman. Najprej nastavite BaseUrl in administratorski Bearer token, ustvarite Naročnika ter licenco, nato uporabite glavi Naročnika, naložite certifikat in izvedite Echo. Za varen retry zaklenite isti idempotency ključ; za nov logični zahtevek ustvarite novega.
Aktualne DTO-je, odzive in primere vedno preverite v interaktivnem Swaggerju. Za podporo na hello@kvadrati.com dodajte okolje, endpoint, UTC čas, messageId, outcome in varen izsek napake — nikoli ključa, certifikata, gesla ali JWT. Uradna dokumentacija FURS ima prednost pri davčnih in protokolarnih pravilih.