-
• Not a DB entity (storedmapped asfrom invoices`invoices` + invoice_items`invoice_items` tables, mappedtables on read)
• - Not a DTO for the REST API DTO (API layer maps to/fromseparately) its- own request/response models)
• Not versioned independently — it evolves with EN 16931 minor revisions

2.3 Adapter Lifecycle States

Machine Defined in `EInvoiceTypes.ktkt` lines 22–26. ThisTransition ADRcriteria formalisesformalised thehere: transition``` criteria:

STUB  ──────────────────────►  SANDBOX_VERIFIED  ──────────────────────►  PRODUCTION
  │                                    │                                        │
  │ Compiles. │All 53 happy-path sandbox                   │ Securion audit passed.
  │ Allnetwork methods throw │ test cases pass with                   │ 30d stage soak with
  │ AdapterErrorCode.                  │ real platform submission               │ zero critical errors.
  │ NOT_IMPLEMENTED.
  │ IDsserialize() MAY be operational (notHR: mocked)already works offline).                      │ AdapterConfig(enabled=true)
  │ AdapterConfig row │not Real platform responserequired.
  │
  in│ productionTransition DB.criteria → SANDBOX_VERIFIED:
  │   may1. notProvider existaccount yet.                 │ logged and archived.                   │
  └────────────────────────────────────┴────────────────────────────────────────┘

HR current stateprovisioned (2026-05-11): STUB

• serialize() WORKS (offline, no credentials). Verified by unit tests.
• submit() throws NOT_IMPLEMENTED — blocked on MC #8675 (Storecovefor account).
HR/Storecove)
• pollStatus()│ throws2. NOT_IMPLEMENTED.
Credentials
• parseIncoming() throws NOT_IMPLEMENTED.

Transition to SANDBOX_VERIFIED requires (HR):

1. MC #8675 resolved: Storecove API key + STORECOVE_LEGAL_ENTITY_IDloaded in GCP Secret Manager
2. (see §2.6 secret taxonomy) │ 3. 5 sandbox test invoicesinvoice types pass with REAL platform submission IDs (§2.4) │ 4. pollStatus() confirmed for each submitted viainvoice submit()│ and5. pollingProveo confirmedevidence viafile pollStatus():with
   submission
   • B2BIDs outbound commercial invoice
   • B2G outbounduploaded to BookStack │ 6. lifecycleState field updated to SANDBOX_VERIFIED in adapter source │ ▼ SANDBOX_VERIFIED │ All 4 methods operational against provider sandbox. │ AdapterConfig(market, EINVOICE, enabled=true) in STAGE DB. │ │ Transition criteria → PRODUCTION: │ 1. Securion audit: adapter error handling + PII sanitization (see §2.7) │ 2. 30 continuous days on STAGE Cloud Run with zero │ AdapterErrorCode.PLATFORM_INTERNAL_ERROR alerts │ (Prometheus metric: bilko_integration_request_total) │ 3. AdapterConfig(market, EINVOICE, enabled=true) in PRODUCTION DB │ 4. CEO sign-off (this is the go-live gate) │ ▼ PRODUCTION │ Live. All 4 methods operational against production platform. │ Incident response: if critical error rate > 5% over 15min window, │ automated alert → Slack #bilko-incidents → human decision to flip │ AdapterConfig.enabled = false (no redeploy needed). ``` **Current HR government entity
   • Credit notestate (typeCode2026-05-13):** 381)
   STUB
   • Cancelled- `serialize()`: WORKS (offline). Unit-tested. - `submit()`: throws NOT_IMPLEMENTED — MC #8675 pending - `pollStatus()`: throws NOT_IMPLEMENTED - `parseIncoming()`: throws NOT_IMPLEMENTED (deferred post-GA) ### 2.4 HR-FISK Storecove Sandbox Validation Matrix 5 invoice workflow
   types
   • Inboundrequired invoicefor fromSANDBOX_VERIFIED Storecovetransition. webhook
3. All 5must produce real Storecove submission GUIDs (not mock strings)
.
4. Proveo (Angie Jones) runs these tests. | # | Invoice Type | UNTDID Code | Scenario | Expected Storecove Response | Evidence Required | | --- | ----------------------- | ------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------- | | 1 | B2B outbound commercial | 380 | Supplier OIB + Buyer OIB both valid. EUR. 25% PDV. Standard commercial transaction. | HTTP 200 + `{"id": "<guid>", "status": "pending"}` | Storecove submission GUID in evidence file with| submission| IDs2 uploaded| B2G outbound | 380 | Buyer is HR government entity (OIB format same). `PaymentMeans.paymentMeansCode=30`. | HTTP 200 + GUID | GUID + Storecove routing.peppol.id verified as buyer OIB | | 3 | Credit note | 381 | References original invoice number in `note` field. Negative line totals. | HTTP 200 + GUID | GUID + typeCode=381 confirmed in Storecove portal | | 4 | Cancelled invoice | 384 | CORRECTIVE_INVOICE type. Status flow: submit → pollStatus until APPROVED or REJECTED | HTTP 200 + GUID, then pollStatus APPROVED/REJECTED | GUID + final status confirmed | | 5 | Inbound received | 380 (inbound) | Storecove sends test webhook to BookStack
Bilko's

Transitionendpoint. `parseIncoming()` invoked. | Webhook received. CanonicalInvoice returned. `hr.supplierOib` in adapterMetadata. | Log entry showing successful parse + extracted OIB value | **HR-specific validation rules verified in each test case:** - `currencyCode = "EUR"` (HALT-3) - Supplier OIB: ISO 7064 MOD 11,10 checksum valid - Buyer OIB: ISO 7064 MOD 11,10 checksum valid - CustomizationID: verify with Storecove support which to PRODUCTIONuse (PEPPOL_BIS3 or HR_CIUS — TODO MC #8675 D3) - `routing.peppol.scheme = "9934"` and `routing.peppol.id = <buyerOIB>` **Storecove-specific notes:** - Sandbox URL is the same as production (`api.storecove.com/api/v2`) — sandbox mode is a payload flag, not a different host. Set `STORECOVE_ENV=sandbox` env var. - Idempotency key: SHA-256(`invoice.id` + `invoice.invoiceNumber`) → sent as `Idempotency-Key` header. Platform returns HTTP 409 on duplicate — treat as success (re-fetch GUID from error body). - `document_id` field in Storecove payload = `CanonicalInvoice.id` (Bilko UUID) — Storecove dedup key, prevents double-billing on retry (D2 in StorecoveHrFiskEInvoiceAdapter). ### 2.5 NOT_IMPLEMENTED Transition Rules `AdapterErrorCode.NOT_IMPLEMENTED` is the canonical error code for STUB lifecycle methods. Rules for callers and implementers: **Implementer rules:** 1. Any STUB lifecycle method that is not yet operational MUST throw: ```kotlin throw AdapterException( code = AdapterErrorCode.NOT_IMPLEMENTED, market = jurisdiction, retryable = false, rawPayload = "", message = "<Platform> <method> requires account — MC #<id>" ) ``` 2. `serialize()` is EXEMPT from the NOT_IMPLEMENTED requirement — it SHOULD be operational even in STUB lifecycle because it needs no credentials (anyoffline adapter):

3.
1. Once an implementation moves to SANDBOX_VERIFIED, no method may throw NOT_IMPLEMENTED for the sandbox environment. If a method is genuinely deferred (e.g., `parseIncoming()` for HR v1), the lifecycle state must remain STUB until all 4 methods are operational. Exception: `parseIncoming()` for HR is formally deferred to 90 days post-GA per Plan v3 §4d. The HR adapter will hold a partial SANDBOX_VERIFIED state alreadytracked achieved
by
2. Securionthe audit`AdapterConfig` offeature flag with `reason = "parseIncoming deferred — Phase 1H.6"`. **Caller rules:** 1. Before calling `submit()` or `pollStatus()`, callers MUST check: ```kotlin val config = adapterConfigRepo.find(jurisdiction, "EINVOICE") ?: throw AdapterException(NOT_IMPLEMENTED, ...) if (!config.enabled) throw AdapterException(NOT_IMPLEMENTED, ..., message="Adapter disabled: ${config.reason}") ``` 2. `NOT_IMPLEMENTED` caught at the route handler level maps to HTTP 503 (Service Unavailable) with body `{"error": "ADAPTER_NOT_AVAILABLE", "market": "<jurisdiction>"}`, NOT HTTP 500. This is the stub plugin HTTP 500 risk mitigation from ADR-015 §5.3. 3. `serialize()` callers do NOT need to check AdapterConfig — serialize is always available. **Error code precedence when multiple codes could apply:** ``` NOT_IMPLEMENTED > AUTH_INVALID_CREDENTIALS > VALIDATION_BUSINESS_RULE > NETWORK_TIMEOUT ``` If a STUB adapter erroris handlingalso andmissing PIIcredentials, sanitization
`NOT_IMPLEMENTED`
3. 30takes continuousprecedence. daysLifecycle onstate stagecheck happens before credential check. ### 2.6 Secret Management — GCP Secret Manager Taxonomy All adapter credentials follow the taxonomy defined in ADR-019 §2.5: ``` Bilko/{env}/{market}/{secret-name} ``` - `{env}`: `dev`, `stage`, `prod` - `{market}`: `HR`, `RS`, `BA_FED`, `BA_RS` - `{secret-name}`: platform-specific identifier (kebab-case) **HR Storecove secrets (provision after MC #8675):** | GCP Secret Manager path | Content | Access binding | | ------------------------------------------ | ----------------------------------- | ----------------------------- | | `Bilko/stage/HR/storecove-api-key` | Storecove sandbox API key | Cloud Run withSA zero`bilko-stage-sa` AdapterErrorCode.PLATFORM_INTERNAL_ERROR| alerts| `Bilko/prod/HR/storecove-api-key` | Storecove production API key | Cloud Run SA `bilko-prod-sa` | | `Bilko/stage/HR/storecove-legal-entity-id` | Storecove legal entity ID (persandbox) Prometheus| bilko_integration_request_totalCloud metric)
Run
4. AdapterConfig(market=HR,SA adapter_type=EINVOICE,`bilko-stage-sa` enabled=true)| row| `Bilko/prod/HR/storecove-legal-entity-id` | Storecove legal entity ID (prod) | Cloud Run SA `bilko-prod-sa` | **Mounting in Cloud Run:** ```yaml # gcp-deploy.yml (Cloud Run --set-secrets pattern): --set-secrets="STORECOVE_API_KEY=Bilko/stage/HR/storecove-api-key:latest,\ STORECOVE_LEGAL_ENTITY_ID=Bilko/stage/HR/storecove-legal-entity-id:latest" ``` **Env var naming convention:** `<PLATFORM>_<FIELD>`, uppercase, underscores. Accessed in `StorecoveApiClient` via `System.getenv("STORECOVE_API_KEY")`. **Secret rotation policy:** - Rotate API keys every 90 days OR on any Storecove security notice, whichever comes first. - Previous version retained in Secret Manager for 24h to allow graceful failover. - Rotation event: create new secret version → update Cloud Run env → verify health endpoint → delete previous version 24h later. **Never in source code or logs:** API keys, legal entity IDs, OIB values, IBAN values. `StorecoveHrFiskEInvoiceAdapter.sanitizeForLog()` must be called on all Storecove response bodies before logging. **RS future secrets (Phase 1S):** | GCP Secret Manager path | Content | | ----------------------------- | --------------------------- | | `Bilko/stage/RS/sef-api-key` | SEF sandbox access token | | `Bilko/prod/RS/sef-api-key` | SEF production DB
access

| | `Bilko/stage/RS/sef-username` | SEF API username | | `Bilko/prod/RS/sef-username` | SEF API username (prod) | SEF uses OAuth2 with client credentials. The token endpoint is `https://efaktura.mfin.gov.rs/` (Serbian Ministry of Finance). Exact credentials shape to be confirmed at Phase 1S kickoff. ### 2.47 Per-Platform XML NamespaceField Mapping

TheHow canonical CanonicalInvoice`CanonicalInvoice` fields map to platform-specific XML/JSONJSON: elements:

HR| CustomizationID`"hr.supplierOib"`, note`"hr.buyerOib"`, `"hr.pozivNaBroj"` (StorecoveHrFiskEInvoiceAdapter.ktinbound) lines| 247–252):`"rs.sefId"`, Two`"rs.supplierPib"` candidates| —TBD default| isTBD CUSTOMIZATION_ID_PEPPOL_BIS3.| Verify with Storecove support before MC #8675 activation which to use for HR-FISK submission.

**SEF XML note (RS):note:** SEF does not use UBL 2.1. It uses a Serbian-specific XML schema published by the Ministry of Finance. The SEF adapter (Phasemaps 1S)`CanonicalInvoice` must map from CanonicalInvoice to→ SEF schema —directly; it does NOT go through UBL. The `EInvoiceAdapter.serialize()` contract requires only that the output isreturns the platform's native wireformat. format.

adapters (Phase 1B):** CPF and UINO platforms have no published API specifications as of 2026-05-13. Phase 1B cannot begin until regulatory mandates define the technical specification (~2027 per plan v3 context). ### 2.58 HR Reference Implementation

StorecoveHrFiskEInvoiceAdapterDesign atDecisions apps/api/src/main/kotlin/no/alai/bilko/country/hr/StorecoveHrFiskEInvoiceAdapter.kt`StorecoveHrFiskEInvoiceAdapter` is the reference implementationimplementation. forFuture alladapters EInvoiceAdapter decisions in this ADR. Key design choices toMUST replicate inthese futurepatterns: adapters:

| Lines 420–437 (`StorecovePayloadBuilder.wrap()`) | REQUIRED if platform supports 409 | --- ## 3. Adapter Lifecycle Governance

### 3.1 AdapterConfig Feature Flag

All adaptersadapter network paths (`submit`, `pollStatus`, `parseIncoming`) are gated by an AdapterConfig`AdapterConfig` row in the databasedatabase. (Defined fully in ADR-019 §2.4):

-- Table defined in ADR-019;4; referenced herehere:

for completeness```sql
CREATE TABLE adapter_config (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    market       VARCHAR(8) NOT NULL,   -- TaxJurisdiction enum value
    adapter_type VARCHAR(32) NOT NULL,  -- 'EINVOICE', 'BANK_STATEMENT', etc.
    enabled      BOOLEAN NOT NULL DEFAULT FALSE,
    reason       TEXT,                  -- WhyHuman-readable disabledstatus (e.g., "MC #8675 pending")note
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (market, adapter_type)
);

NoSeed EInvoiceAdapterrow submitfor pathHR executesSTUB unlessstate adapter_config.(Flyway V17): ```sql INSERT INTO adapter_config (market, adapter_type, enabled, reason) VALUES ('HR', 'EINVOICE', false, 'Storecove account pending — MC #8675'); ``` Row is flipped to `enabled = truetrue` forby the operator (market,not 'EINVOICE').by Thiscode) allowsafter disablingSANDBOX_VERIFIED atransition brokenis adapterconfirmed withoutby aProveo redeploy.

### 3.2 Adapter Versioning

Adapters are versioned independently of the CountryPlugin version. Each adapter implementationexposes: exposes```kotlin a val adapterVersion: String property// (e.g., "1.0.0"). ``` The CountryPlugin`CountryPlugin` implementation declares a minimum adapter version it is compatible with.version. Incompatibility detected at startup → application fails fast with a clear error.

silent degradation). --- ## 4. Consequences

### 4.1 Positive

-
• **Offline serialization.** `serialize()` contract requires no network. Enables invoice PDF preview, offline testing, and regression test suites without live platform credentials.
• - **Uniform error handling.** AdapterException (defined in ADR-019)`AdapterException` is the only exception type that crossescrossing the adapter boundary. Callers implement one error handler, not four platform-specific ones.
• - **Lifecycle visibility.** lifecycleState`lifecycleState` is afirst-class. first-class property. Monitoring dashboards canDashboards show "HR adapter: STUB" and alert when a market is operatingoperates in degraded lifecyclestate. state.
-
• **Canonical model.** CanonicalInvoice`CanonicalInvoice` enables cross-market reporting, invoice history normalisation,reporting and futureanalytics. features- (e.g.,**NOT_IMPLEMENTED group→ invoiceHTTP analytics503.** acrossClients HRreceive +a RS).
clean