Bilko ADR-016: E-Invoice Adapter
Author: ALAI, 2026
# ADR-016: E-Invoice Adapter & UBL 2.1 Canonical Model
**Status:** Accepted
**Date:** 2026-04-21
**Author:** ALAI, 2026
**Related:** ADR-015 (Four-Jurisdiction Plugin), ADR-019 (Integration Adapter Registry)
---
## Context
Each of Bilko's four tax jurisdictions mandates **electronic invoicing** via government-operated fiscal platforms:
| Jurisdiction | Platform | Format | Mandatory Since | Inbound Support |
| -------------------- | --------------------- | ---------------------- | --------------- | --------------- |
| RS (Serbia) | SEF (efaktura.gov.rs) | UBL 2.1 + SEF envelope | 2023 | Yes (B2B) |
| HR (Croatia) | HR-FISK / FINA eRacun | UBL 2.1 + FINA XML | Jan 2026 | Yes (B2B) |
| BA-FED (Bosnia FBiH) | CPF | Unspecified (stub) | TBD 2027 | Unknown |
| BA-RS (Bosnia RS) | UINO | Unspecified (stub) | TBD | Unknown |
### Problem Statement
Bilko's **invoice domain** must:
1. Generate invoices in a **canonical format** independent of any single jurisdiction
2. **Serialize** to jurisdiction-specific XML/JSON for submission
3. **Submit** to fiscal platforms with retry/error handling
4. **Poll** for status updates (async platforms)
5. **Parse** inbound invoices received from suppliers (B2B procurement)
**Without:**
- Embedding SEF/FINA-specific logic in the core `Invoice` model
- Duplicating invoice validation across 4 jurisdictions
- Tight coupling to any single platform's API changes
### Design Decision Drivers
**Vendor patterns adopted:**
- **SAP B1 Electronic Filing Manager (EFM):** Pluggable adapter layer per jurisdiction + canonical UBL 2.1 core
- **EN 16931 European e-invoicing standard:** Defines minimal invoice semantic model
- **UBL 2.1 (ISO/IEC 19845):** OASIS Universal Business Language — XML serialization
**Key insight from SAP:** The _canonical model_ should reflect **accounting semantics**, not platform wire formats. Adapters translate from canonical → platform-specific.
---
## Decision
### 1. Canonical Invoice Model — EN 16931 Subset
Bilko's internal invoice representation is a **Kotlin data class** implementing the **EN 16931 Core Invoice Model** (mandatory BT fields + optional BG groups).
**File:** `CanonicalInvoice.kt` (see `~/ALAI/products/Bilko/scratch-api/src/main/kotlin/no/alai/bilko/einvoice/CanonicalInvoice.kt`)
**Key design rules:**
1. All monetary amounts: `BigDecimal` with 4 decimal places (ADR-002)
2. All dates: `kotlinx.datetime.LocalDate`
3. VAT categories: UN/ECE 5305 codes (`S`, `Z`, `E`, `AE`, `O`, `K`, `G`)
4. Invoice types: UNTDID 1001 codes (380 = commercial invoice, 381 = credit note, 383 = debit note)
5. Currency codes: ISO 4217 (RSD, EUR, BAM)
6. Country codes: ISO 3166-1 alpha-2 (RS, HR, BA)
**Mandatory fields (EN 16931 BT numbering in KDoc):**
- BT-1: Invoice number
- BT-2: Issue date
- BT-3: Invoice type code
- BT-5: Currency code
- BT-9: Due date
- BG-4: Supplier party (name, tax ID, address)
- BG-7: Buyer party (name, tax ID, address)
- BG-23: VAT breakdown per category
- BG-25: Invoice lines (minimum 1 line)
**Extension point:**
```kotlin
val adapterMetadata: Map<String, String> = emptyMap()
```
For jurisdiction-specific fields not covered by EN 16931 (e.g., `sef.requestId`, `hr.fiscalCode`). Namespaced by adapter.
### 2. EInvoiceAdapter Interface
All jurisdiction-specific e-invoice integrations **must** implement this contract.
**File:** `EInvoiceAdapter.kt` (see `~/ALAI/products/Bilko/scratch-api/src/main/kotlin/no/alai/bilko/einvoice/EInvoiceAdapter.kt`)
**Four methods (ADR-019 lifecycle contract):**
```kotlin
interface EInvoiceAdapter {
val jurisdiction: TaxJurisdiction
val lifecycleState: AdapterLifecycleState // STUB | SANDBOX_VERIFIED | PRODUCTION_CERTIFIED
@Throws(AdapterException::class)
fun serialize(invoice: CanonicalInvoice): ByteArray
@Throws(AdapterException::class)
fun submit(serializedInvoice: ByteArray, invoice: CanonicalInvoice): SubmitResult
@Throws(AdapterException::class)
fun pollStatus(submissionId: String, invoice: CanonicalInvoice): EInvoiceStatus
@Throws(AdapterException::class)
fun parseIncoming(rawPayload: ByteArray): CanonicalInvoice
}
```
**Lifecycle states (ADR-019):**
- `STUB`: Not implemented — all methods throw `AdapterException(NOT_IMPLEMENTED)`
- `SANDBOX_VERIFIED`: Tested against fiscal platform sandbox (e.g., SEF demo env)
- `PRODUCTION_CERTIFIED`: Audited and approved for live traffic
**Error normalization (ADR-019):**
All adapters throw `AdapterException(code, market, retryable, rawPayload)` — never platform-native exceptions. Canonical error codes: `NETWORK_TIMEOUT`, `AUTH_TOKEN_EXPIRED`, `VALIDATION_SCHEMA_ERROR`, `PLATFORM_MAINTENANCE`, etc.
### 3. Adapter Implementations — Phase 1 Priorities
| Jurisdiction | Adapter Class | Lifecycle State (2026-04-22) | Notes |
| ------------ | ----------------------- | ---------------------------- | -------------------------------------------------- |
| RS | `SEFEInvoiceAdapter` | SANDBOX_VERIFIED | Outbound + inbound implemented (MC #8682) |
| HR | `HRFISKEInvoiceAdapter` | STUB | Blocked on FINA certificate (CEO decision pending) |
| BA-FED | `CPFEInvoiceAdapter` | STUB | CPF spec not published |
| BA-RS | `UINOEInvoiceAdapter` | STUB | UINO spec unavailable |
**SEF Serbia (RS) — Reference Implementation:**
- Serialization: UBL 2.1 XML + SEF JSON envelope
- Submission: HTTPS POST to `https://efaktura.mfin.gov.rs/api/publicApi/invoice`
- Authentication: X.509 certificate + API key
- Polling: GET `/api/publicApi/invoice/{id}/status`
- Inbound: Webhook `/api/invoices/incoming` + polling `/api/publicApi/inbox`
**SEF sandbox certification (Task 1.5):**
5 invoice types tested in sandbox:
1. B2B outbound invoice
2. B2G outbound invoice (to government buyer)
3. Credit note
4. Cancelled invoice
5. Inbound invoice received from supplier
**Evidence:** Acknowledgement IDs returned by real SEF demo environment (MC #8682 DoD).
### 4. Canonical → Platform Serialization Flow
```mermaid
sequenceDiagram
participant Core as Invoice Service
participant Plugin as CountryPlugin (RS)
participant Adapter as SEFEInvoiceAdapter
participant SEF as SEF Platform
Core->>Plugin: generateEInvoiceXml(invoice)
Plugin->>Adapter: serialize(invoice)
Adapter->>Adapter: Map CanonicalInvoice → UBL 2.1 XML
Adapter-->>Plugin: ByteArray (XML)
Plugin->>Adapter: submit(xml, invoice)
Adapter->>SEF: POST /api/publicApi/invoice
SEF-->>Adapter: HTTP 200 + platformInvoiceId
Adapter-->>Plugin: SubmitResult(platformInvoiceId, PENDING)
Plugin-->>Core: FiscalSubmissionHandle
```
**Key invariant:** The `Invoice` model in `packages/database` **never** contains SEF-specific fields. All jurisdiction logic flows through the plugin and adapter layers.
---
## Consequences
### Positive
1. **Platform independence:** When SEF changes XML schema (happened 2024), only `SEFEInvoiceAdapter` changes. Core untouched.
2. **Testability:** Each adapter has isolated unit tests. Mock platforms for regression.
3. **Incremental rollout:** HR/BA adapters can remain stubs until fiscal platforms are ready.
4. **B2B procurement:** Inbound invoices parse through `parseIncoming()` → canonical model → standard invoice creation flow.
### Negative
1. **Mapping complexity:** UBL 2.1 has 200+ optional fields. CanonicalInvoice supports ~40. Adapter must decide what to include.
2. **Round-trip fidelity:** Parsing inbound invoice → canonical → serialize may lose platform-specific metadata. Use `adapterMetadata` map.
3. **Certification burden:** Sandbox testing required per adapter before production (Phase 1 Task 1.5).
### Risks
1. **SEF/FINA breaking changes:** Government platforms have no SLA, no deprecation policy. **Mitigation:** Adapter feature flags (ADR-019 Task 4.5) — disable broken adapter without redeploy.
2. **CPF/UINO spec delays:** BiH platforms have no published tech specs. **Mitigation:** Stub adapters document `NOT_IMPLEMENTED`; GA proceeds without BiH e-invoicing.
3. **UBL 2.1 extensions:** Some platforms extend UBL with custom namespaces. **Mitigation:** `adapterMetadata` carries extension data; serialization handles custom namespaces.
---
## Implementation Notes
### Validation Strategy
**EN 16931 validation (core):**
- Invoice must have ≥1 line
- `sum(lines.lineTotal)` == `invoice.totalAmountExclVat`
- `totalAmountExclVat + totalVatAmount` == `totalAmountInclVat`
- All amounts ≥ 0 (credit notes use negative `quantity`, not negative `unitPrice`)
**Jurisdiction validation (adapter):**
- SEF Serbia: Buyer VAT ID must match PIB format (9 digits)
- HR Croatia: Supplier must be FINA-registered (OIB validation)
- Validation errors throw `AdapterException(VALIDATION_BUSINESS_RULE, retryable=false)`
### Async Submission Pattern (Transactional Outbox)
SEF and HR-FISK are **asynchronous**. Recommended pattern:
```kotlin
// 1. Persist invoice to DB (transaction T1)
// 2. Write to {market}_outbox table (still in T1)
// 3. Commit T1
// 4. Background worker polls outbox, calls adapter.submit()
// 5. Update outbox row with platformInvoiceId
// 6. Background worker polls adapter.pollStatus() until APPROVED/REJECTED
```
**Do NOT block invoice creation** on fiscal platform availability.
### Sandbox Environments
| Platform | Sandbox URL | Credential Type |
| ------------ | --------------------------------- | ------------------------- |
| SEF (RS) | https://demo-efaktura.mfin.gov.rs | Test X.509 cert + API key |
| HR-FISK (HR) | https://demo.fiskalizacija.hr | Test FINA certificate |
| CPF (BA-FED) | N/A | Not available |
| UINO (BA-RS) | N/A | Not available |
**Sandbox credential convention (ADR-019):**
- Secret store path: `Bilko/sandbox/{market}/{secret-name}`
- Example: `Bilko/sandbox/RS/sef-api-key`
---
## References
- **EN 16931 spec:** https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/Compliance+with+eInvoicing+standard
- **UBL 2.1 spec:** http://docs.oasis-open.org/ubl/UBL-2.1.html
- **SEF Serbia docs:** https://www.efaktura.gov.rs/en
- **HR-FISK Croatia:** https://www.porezna-uprava.hr/HR_Fiskalizacija/Stranice/Naslovna.aspx
- **Implementation:** `~/ALAI/products/Bilko/scratch-api/src/main/kotlin/no/alai/bilko/einvoice/`
- **Master plan:** `~/system/specs/bilko-multi-market-architecture-plan.md` (Phase 1 Task 1.4, Task 1.5)
- **Related ADRs:**
- ADR-015: Four-Jurisdiction Plugin Architecture
- ADR-019: Integration Adapter Registry
---
## Approval
**Approved:** 2026-04-21 by CEO Alem Basic
**Execution:** Phase 0 Task 0.2, Phase 1 Task 1.4 (completed 2026-04-22, MC #8682)