# Bilko HR eRačun — slanje i primanje, cjelovita slika (2026-08-19)

# Bilko HR eRačun — slanje i primanje, cjelovita slika (2026-08-19)

**Povod:** CEO pitanje — „Sad imamo firmu SMART FORGE. Kako ona može slati i primati račune?
Ako koristimo bilko.cloud, trebamo li i dalje raditi stvari preko sveRačuna?"

**Metod:** pročitano svih 10 mailova od sveRačuna/PostLinka (8491, 8519, 8524, 8760, 9473,
9523, 14870, 15382, 15458, 16036) + čitanje `azdo/main` + živi `az` pozivi.
Sve tvrdnje ispod imaju izvor. Gdje izvora nema, izričito piše da nije potvrđeno.

> Napomena: OIB informacijskog posrednika NIJE prepisan u ovaj dokument. `claude-hooks pre`
> ga blokira kao „Norwegian SSN" (11 cifara) — lažno pozitivno, ali gate se ne zaobilazi.
> Broj je u koraku 8 privitka „Upute za potvrdu adrese za zaprimanje eRačuna.pdf" (mail 16036).

---

## 1. Uloge u lancu

| uloga | ko | šta radi |
|---|---|---|
| softver | **Bilko** | pravi račun, šalje ga API-jem, prati status |
| informacijski posrednik | **PostLink d.o.o. (sveRačun)** | licencirana pristupna točka; jedini koji stvarno unosi eRačun u hrvatski fiskalizacijski sustav |
| obveznik | **SMART FORGE d.o.o.** | tvrtka koja izdaje/prima račun |

**Bilko nije pristupna točka i ne mora postati.** Mail 16036, tačka 5: OIB PostLinka je zapis
kojim **krajnji korisnik ovlašćuje PostLink** za fiskalizaciju. Ne ovlašćuje Bilko.
Posljedica: ne treba nam vlastita posrednička licenca.

## 2. Odgovor na pitanje „trebamo li i dalje preko sveRačuna"

**Da, i to trajno.** Koraci iz PDF-a nisu jednokratna radnja za nas nego čin pred Poreznom
upravom **za svaki OIB**. Svaka hrvatska firma koja prima eRačune mora sama potvrditi
PostLinka kao adresu za zaprimanje i dati mu ovlaštenje za fiskalizaciju.

Mi to ne možemo odraditi umjesto korisnika → **ulazi u onboarding kao vođeni korak u
proizvodu**, ne kao PDF u mailu.

Pola je automatsko: mail 16036 tačka 7 — kad Bilko API-jem registruje tvrtku, sveRačun
automatski šalje prijavu u AMS. Druga polovina je korisnikov klik u FiskAplikaciji.

## 3. Slanje — radi, čeka aktivaciju

Tehnički dokazano na TEST okruženju (MC #103450: `documentId`, `fiscalNumber 2026-000002`,
živi roundtrip).

**Aktivacija traži ČETIRI stvari, ne jednu:**

| # | šta | gdje | zamka |
|---|---|---|---|
| 1 | `hr_einvoice_issuer_config.enabled = true` | DB, per-org red | — |
| 2 | `SVERACUN_HR_LIVE=true` | ACA env | danas `false` na demo I stage |
| 3 | `hr_einvoice_issuer_config.api_base_url = 'https://hr.sveracun.hr/api'` | DB | **`V75...sql:43` ima DEFAULT `test.sveracun.hr`** |
| 4 | `SVERACUN_API_KEY` ← produkcijski ključ | ACA secret | secret postoji ali drži TEST ključ |

**Tačka 3 je tiha zamka.** Flip samo (1) i (2) → sistem uspješno šalje na TEST, vraća statuse,
sve izgleda ispravno, a nijedan račun nije zakonski fiskaliziran. Fallback u
`SveRacunHttpClient.kt:153` je isto TEST.

Klijent sam dodaje `/rest/v1/documents/send` (`SveRacunHttpClient.kt:135`), pa base mora biti
`https://hr.sveracun.hr/api` **bez** `/rest/v1` — što daje tačno URL koji je sveRačun naveo.

## 4. Primanje — NE POSTOJI u Bilku

Mjereno na `azdo/main`:

```
git grep "ReceivedEInvoices.insert"        → TAČNO JEDAN pogodak
                                             ReceivedEInvoiceService.kt:139
jedini vanjski pozivalac                   → StorecoveWebhookRoutes.kt
Storecove                                  → NAPUŠTEN 2026-06-11 (MC #103434, izabran sveRačun)
                                             adapter iza STORECOVE_HR_LIVE, default false
git grep inbound|fetchInbound|receiveDocuments|documents.inbox u country/hr/  → NULA
```

Ruta `GET /api/v1/received-einvoices` postoji i radi — ali tabelu **nema ko puniti**.

**Provider to podržava.** Mail 9523 (2026-06-11):
- `NEW — Novi dokument; odnosi se samo na novo primljeni DOLAZNI dokument koji još treba preuzeti`
- `Status dokumenta se pull-a pomoću metoda, nemamo webhook-ove`

Dakle rupa je **isključivo naša**. Iz javne dokumentacije vidljive metode: `amsCheck`,
`getStatus`, `getInternalStatus`, `getPdf`, uz `filterBy`/`sortBy`/`issuedDateTime`.
Tačno ime metode za listanje dolaznih **nije potvrđeno** — docs je JS-renderovan,
`openapi.yaml`/`.json` daju 404.

**Praktična posljedica:** čim korisnik potvrdi adresu za zaprimanje, dolazni računi stižu
kod PostLinka i tu staju.

## 5. Kako radi njihov sustav (mail 9523)

Izdani eRačun prolazi dvije etape:

1. Osnovna raščlamba — provjera da se **initiator (OIB koji poziva send) i pošiljalac u XML-u
   podudaraju**, provjera primaoca, vrste dokumenta, procesa.
2. Validacija prema validatoru Porezne uprave → provjera postoji li primaočeva pristupna točka
   → priprema SBD za AS4 razmjenu → AS4 razmjena (čeka odgovor 5 min; kod nedostupnosti
   pokušava **24 puta svakih 30 min**) → izlazna fiskalizacija → arhiviranje.

**Interni statusi:** `NEW`, `OK`, `FAILED`, `UNKNOWN`, `UNDELIVERABLE` (primalac nije u AMS-u).
**Eksterni:** `FISCALIZATION:OK|ERROR`, `FISCALIZATION_PAYMENT_REPORT:*`,
`FISCALIZATION_REJECTION_REPORT:*`, `FISCALIZATION_NOT_DELIVERED_REPORT:*`, `null`.

Uspješno poslan račun = **`OK` + `FISCALIZATION:OK`**. Neuspješan = `FAILED` + `FISCALIZATION:ERROR`.

Zahtjev iz etape 1 (initiator == pošiljalac) je razlog zašto postoje dva režima u kodu.

## 6. DIRECT vs INTERMEDIARY

`IssuerProfile.kt:29`:

- **DIRECT** — vlasnik API ključa i pošiljalac su ista firma. SMART FORGE šalje **svoje** račune.
  To je ono za šta smo spremni danas.
- **INTERMEDIARY** — Bilko drži ključ, pošiljalac je per-tenant OIB. Potrebno za **kupce**.
  Kod je označen kao „parked, B2 commercial track required first".

**Nije parkiran — čeka jedan mail.** Mail 15458 (2026-08-03), sami ponudili:
*„Možemo izdati sveobuhvatni API ključ koji će moći upravljati sa svim Vašim korisnicima koji
će se nalaziti u grupi… master API ključ za rad s više pravnih subjekata okupljenih u jednu
grupu. Ovo možemo napraviti u bilo kojem trenutku."*

Ponovljeno u 16036 tačka 4: grupni ključ vrijedi i za tvrtke naknadno kreirane tim ključem.

## 7. Komercijalni uslovi — dogovoreni

Mail 8760 (2026-06-02) + CEO prihvat u 14870 (2026-07-21): **„Prihvaćamo uvjete iz vašeg
prijedloga (reselling model). Ugovor smo spremni potpisati do kraja mjeseca."**

- prva godina: **0,10 €/račun** za 10.000 mjesečno, **bez set-up fee**
- podrška: **50 € + PDV** mjesečno
- poslije prve godine, razredi: `<50k → 0,18 €`, `50–100k → 0,16 €`, `100–150k → 0,14 €`,
  `150–200k → 0,13 €`, `>200k → 0,12 €`
- popust: **35%** na prvi razred, **25%** na ostale
- **Reselling model**: Bilko sam definiše cijenu prema krajnjem korisniku
  (alternativa je bila Revenue share: 20% provizije umanjeno za njihov fiksni trošak 0,05 €)

## 8. Certifikat — nije potreban

Mail 15458 tačka 2 i 16036 tačka 1: sustav potpisuje račune **aplikativnim certifikatom na
razini informacijskog posrednika**. Po zakonu o F2.0 potpisivanje B2B dokumenata pri razmjeni
nije potrebno; izlazne eRačune ipak potpisuju, na zahtjev korisnika.

## 9. Stanje ključa i tajni

Produkcijski ključ izdan **2026-08-03**, dostavljen mailom 2026-08-19 kao `.txt` privitak.
Upisan u vault: item `sveracun HR produkcijski API kljuc - SMART FORGE` (id 026d1133),
verifikovan čitanjem nazad. Plaintext kopije u `/tmp` uklonjene.

**Obrazac koji treba znati:** i TEST ključ (mail 9473) je stigao plaintext mailom. To nije
izuzetak nego njihova praksa — svaki ključ koji dobijemo dolazi tim putem. Kopije ostaju u
sandučićima `alem@alai.no` i `john@alai.no`. Rotacija je otvorena poslovna odluka CEO-a.

## 10. Zašto je ovo stajalo

`#103443` (aktivacija) `open/L/backlog`, nedirnut od 08.08. `#106636` (komercijalni ugovor)
isto `L/backlog` od 15.08. Blokator je glasio „nemamo prod nalog" — a nalog i ključ postoje
**od 3. augusta**. Oba zadatka je na L spustio `stale-task-escalator`, ne odluka.

Obavezni B2B eRačun u HR važi od **2026-01-01**. Kašnjenje je 7,5 mjeseci.

## 11. Redoslijed

1. **CEO** — 9 koraka u FiskAplikaciji za SMART FORGE (AMS prijava već postoji, samo potvrda).
   Poslano mailom 2026-08-19 21:19 na alem@alai.no, s PDF-om u privitku.
2. **CEO, jedan mail sveRačunu** — master/grupni ključ + tačno ime metode za dohvat dolaznih.
3. **John** — tehnička aktivacija slanja (4 stavke iz §3) + dokaz **internim** računom
   s pravim fiskalnim brojem. Ne HTTP 200.
4. **Builder** — dolazni put. Jedini pravi razvojni posao za kompletan eRačun.

**Ne puštati kupce prije koraka 4** — proizvod koji šalje ali ne prima nije eRačun rješenje.

## Izvori

- Mailovi: `email-inbox.db` id 8491, 8519, 8524, 8760, 9473, 9523, 14870, 15382, 15458, 16036
- Kod: `azdo/main` — `IssuerProfile.kt`, `IssuerProfileRepository.kt`, `HrEInvoiceService.kt`,
  `SveRacunHttpClient.kt`, `ReceivedEInvoiceService.kt`, `StorecoveWebhookRoutes.kt`,
  `V75__hr_einvoice_issuer_config.sql`
- Evidencija: `~/system/evidence/103443/hr-eracun-go-live-plan-2026-08-19.md`
- MC: #103443, #106636, #900004, #103450, #103434

<!-- ALAI-MC:900106:BEFORE -->

---

## Addendum — Sastanak 2026-08-24 + implementacija prijema (isti dan)

**Sastanak (CEO ↔ sveRačun, 14h):** (1) po firmi je OBAVEZAN ručni korak u FiskAplikaciji
(odabir/potvrda Sveračuna) — potvrda nalaza iz §2/§11; (2) postoji API endpoint za provjeru
"je li za firmu sve odrađeno" — poznati kandidat `organizations/amsCheck` (status adrese);
pokriva li išta i status ovlaštenja za fiskalizaciju = otvoreno pitanje PostLinku;
(3) TEST konto naše firme drži seedane dolazne račune za razvoj/igranje.

**Implementacija (MC #900106, PR #403, 2026-08-24):** PRIJEM VIŠE NIJE RUPA NA GRANI —
sveRačun inbox poll (bez date filtera — dokazano da filter vraća prazno), UBL parsiranje s
iznosom, documentId kao source dedup ključ (V168), trajni dead-letter + replay (V169),
pravi fail-closed test, per-org readiness kolone + amsCheck servis (V170), onboarding UI
karta s 2 FiskAplikacija koraka. Živi dokaz: stvarna TEST faktura (27,69 EUR) persistovana
end-to-end. Nezavisni verifier 12/13 VERIFIED. VAN opsega (svjesno): produkcijski scheduler
i naplata prijema — čekaju #900029 (razdvajanje ključeva) i CEO odluku o meteringu.
Grupni API ključ izdat 21.08. (vault). §4 i §11 korak 4 ovog dokumenta su time ZASTARJELI
u dijelu "primanje ne postoji" — kod postoji na PR #403; ova stranica se ažurira ponovo
nakon merge-a i stage aktivacije. Detalji: ~/system/evidence/900208/ + evidence/900106/.