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 = 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)