DEV Community: Vlad Cristian Alexa

From Stripe Checkout to a Compliant Romanian E-Invoice: A JSON UBL Field Report

Vlad Cristian Alexa — Thu, 03 Sep 2026 15:10:55 +0000

E-invoicing from a payment event is a mapping problem, not an XML problem. Stripe hands you a checkout.session.completed whose amount_total is a single integer in minor units, with no tax breakdown and no legal identity. ANAF's e-Factura portal, on the other end, accepts only UBL 2.1 documents pinned to the Romanian CIUS-RO profile, where every line carries a VAT rate, totals must reconcile across four cbc:*Amount elements, and the issuer's fiscal code is validated down to its checksum. Between those two worlds sit irreversible mapping decisions — and, as staging proved, the silent failures live in the webhook contract, not in the XSD. This is that field report: three production codebases, one canonical JSON shape in the middle, three contract breaks that only staging caught.

Architecture: webhook → canonical JSON → UBL

The core rule: webhooks never touch UBL. Every inbound provider (Stripe app event, WooCommerce order webhook, direct API call) is mapped into one canonical InvoiceSchema JSON document — a validated Java record with invoiceNumber, issueDate, currency, issuer/buyer parties, items[], and totals. Persistence, validation, and XML generation all consume that shape; the UBLInvoiceBuilderService reads a Map<String, Object> produced from it and is the only place that knows the CIUS-RO dialect.

Stripe checkout.session.completed ──┐
                                   ├─▶ canonical InvoiceSchema JSON ─▶ UBL 2.1 CIUS-RO XML ─▶ ANAF SPV
WooCommerce order.completed ────────┘        (POST /v1/invoices)          (JobRunr async)

For Stripe, the chain is two hops. The Stripe App backend receives the event at POST /hooks/app (one developer-configured endpoint listening to connected accounts), verifies the Stripe-Signature with stripe.webhooks.constructEvent(raw, sig, STRIPE_WEBHOOK_SECRET) over the exact raw bytes, reads the merchant's FiscalLink API key from the Stripe Apps Secret Store scoped by event.account, and then calls POST /v1/invoices. WooCommerce pushes the order JSON directly to POST /v1/webhooks/woocommerce/{tenantId}, HMAC-signed.

This indirection buys two things. First, adding a third source (Xero, QuickBooks) means writing one mapper, not one XML dialect. Second, validation failure modes concentrate in one service: InvoiceService.createAndEnqueue runs CifValidator checksum checks and En16931CompletenessValidator — a completeness gate that rejects with HTTP 400 before anything is persisted — then builds the UBL synchronously and enqueues a JobRunr ANAF_SUBMISSION job with exponential backoff (5s × 2^(attempt-1), max 10).

The mapping that matters

Payment/order source	Canonical `InvoiceSchema`	UBL 2.1 / CIUS-RO element
`session.amount_total` (minor units) ÷ 100	`totals.total`	`cbc:TaxInclusiveAmount`, `cbc:PayableAmount`
`total × 100/(100+19)` rounded	`totals.subtotal`	`cbc:LineExtensionAmount`, `cbc:TaxExclusiveAmount`
`total − subtotal`	`totals.totalVAT`	`cac:TaxTotal/cbc:TaxAmount`
`line_items[].amount_total ÷ 100 ÷ qty`	`items[].unitPrice`	`cac:Price/cbc:PriceAmount`
merchant metadata + stored CIF	`issuer.name`, `issuer.vatNumber`	`AccountingSupplierParty → PartyLegalEntity`
WC `taxes[0].rate_percent` / `tax_lines[]` default	`items[].vatRate`	`ClassifiedTaxCategory cbc:Percent` (ID `S`)
`customer_details.name` / WC billing	`buyer.name` (+ optional `vatNumber`)	`AccountingCustomerParty`, `PostalAddress`
WC order `subtotal`/`total_tax`/`total` — trusted, never re-summed	`totals`	`LegalMonetaryTotal`, per-rate `TaxSubtotal`s

Three decisions in that table are load-bearing:

Tax travels as a rate, never as a monetary amount. Stripe checkout events have no tax breakdown at all, so the Stripe mapper grosses up at the standard 19% (subtotal = amountTotal * 100 / (100 + 19)). WooCommerce does send tax amounts, but the mapper deliberately ignores taxes[].total as the rate source. The canonical line carries vatRate (a percent) plus vatAmount as a derived convenience field; the UBL builder recomputes everything from the rate:

// AbstractInvoiceBuilder.computeRateSubtotals — one TaxSubtotal per rate (EN 16931 BR-45)
for (Map<String, Object> item : items) {
    BigDecimal qty       = BigDecimalUtils.toBigDecimal(item.get("quantity"));
    BigDecimal unitPrice = BigDecimalUtils.toBigDecimal(item.get("unitPrice"));
    BigDecimal vatRate   = BigDecimalUtils.toBigDecimal(item.getOrDefault("vatRate", 19));

    BigDecimal lineSubtotal = qty.multiply(unitPrice).setScale(2, RoundingMode.HALF_UP);
    BigDecimal lineVat      = lineSubtotal.multiply(vatRate)
            .divide(BigDecimal.valueOf(100), 2, RoundingMode.HALF_UP);
    result.merge(vatRate, new BigDecimal[]{lineSubtotal, lineVat}, /* … */);
}

Totals come from the order, not from summing lines. Rounding at line level makes Σlines drift from the checkout total. Both mappers therefore trust the provider's order-level subtotal/total_tax/total when present and only fall back to recomputation (computeTotals in the WooCommerce controller does exactly this). Provider totals feed LegalMonetaryTotal; line arithmetic only feeds per-rate subtotals — which is why a bad line rate can corrupt the document even when totals are right (bug #3 below).

Rates resolve per line, with a fallback chain. WooCommerce sends VAT per line as taxes[].rate_percent; the mapper tries that first, then the order-level tax_lines[].rate_percent as the shop-wide default, then 0:

// WooCommerceWebhookController.mapLineItems — rate resolution order
BigDecimal vatRate = defaultVatRate;                       // from order tax_lines[]
if (li.has("taxes") && li.path("taxes").isArray() && li.path("taxes").size() > 0) {
    JsonDecimal ld = tryReadDecimal(li.path("taxes").get(0).path("rate_percent"));
    if (ld != null && ld.value != null) { vatRate = ld.value; }
}

The plugin mirrors that contract when it builds the payload: per-line total_tax plus taxes:[{rate_percent}], where the rate itself is read from the WooCommerce tax-rate table (WC_Tax_Rates::get_rate($rate_id)->tax_rate), falling back to tax_total / total * 100.

Three bugs that only staging caught

A dockerized WordPress staging harness (WP 6.7 + WooCommerce 11.0.1) pushed real orders to the live core and exposed three silent contract breaks in the original plugin — three ways to drop or corrupt an invoice while returning 2xx:

1. Missing issuerName/issuerVat → HTTP 400, and the plugin classified it as permanent. Core binds @RequestParam String issuerName on the webhook — a required query parameter — so Spring rejects the request before the handler runs when the merchant never configured their company name. The plugin's old error handling wrote _flwc_submitted = 'permanent_error:400' and never retried: one misconfiguration, zero invoices, no alert. Lesson: anything the merchant must configure to make the invoice legal belongs in setup-time validation, and a 400 on a webhook should page someone — it is never transient.

2. No X-WC-Webhook-Topic header → silent processed:false. Core's receiver returns 200 {"received":true,"processed":false,"reason":"No topic header"} for events it deliberately ignores (it also acks 2xx when invoice creation fails, to stop provider retry storms). The plugin treated any 2xx as success and stamped the order as submitted. The fix is the contract that now ships in the plugin:

// class-flwc-submit.php — only an explicit processed:true means done
if ( $code >= 200 && $code < 300 ) {
    $body = wp_remote_retrieve_body( $response );
    $parsed = json_decode( $body, true );
    if ( is_array( $parsed ) && false === ( $parsed['processed'] ?? true ) ) {
        $this->bump_failures( $order_id );   // 2xx but NOT processed → retry
        return false;
    }
    update_post_meta( $order_id, self::META_DONE, current_time( 'mysql', true ) );
    delete_post_meta( $order_id, self::META_FAILURES );
    return true;
}

3. Tax sent as taxes:[{total:19}] instead of rate_percent → invalid UBL. This is the nastiest one: everything returned 200 and an invoice was created. The mapper's tryReadDecimal(rate_percent) found nothing (total is not rate_percent), the order carried no tax_lines, so lines were stored at vatRate 0, vatAmount 0 — while computeTotals kept the order's real VAT 19.00. The UBL then declared cbc:Percent 0 on every line against a TaxTotal/TaxAmount 19.00: a textbook EN 16931 BR-45/BR-CO consistency break that ANAF would reject. The database told the story: corrupt invoices WC-9001 (line vatRate 0) next to correct WC-11, WC-12, WC-13 (line vatRate 19, UBL percents ['19','19']). Lesson: the amount-based tax shape makes you think you sent 19% — you sent 19 currency units.

Idempotency & retries

There are three idempotency layers, and they must not be confused:

Order/event level (source of truth). The WooCommerce plugin guards submission with post meta: _flwc_submitted (timestamp) means done, _flwc_failures counts attempts (max 5). on_order_completed returns immediately if the meta exists, and the hourly flwc_retry_pending cron re-pushes only orders that have failures, no done-marker, and attempts left. This makes the processing → completed status cycle and webhook redelivery safe.
HTTP level. POST /v1/invoices supports Stripe-style Idempotency-Key headers (IdempotencyFilter), but webhook receivers are explicitly excluded from that filter — shouldNotFilter returns true for /v1/webhooks/ — because each provider has its own redelivery semantics and its own natural key (Stripe event.id, WooCommerce order id). Reusing one generic mechanism for both hides bugs; keep them separate.
Job level. Once an invoice exists, the ANAF_SUBMISSION job retries with exponential backoff and dies into failed/dead_letter after 10 attempts; non-retryable results (ANAF HTTP 403, validation failures) skip retries entirely. Submission answers are reconciled later by a polling job.

The failure-mode matrix matters as much as the keys: 4xx → permanent (mark and stop, or you hammer a misconfiguration for days), 5xx/network → transient (retry), 2xx-without-processed:true → treated as transient (bug #2). Handled-but-failed events must still get a fast 2xx, or providers replay the whole batch into a broken endpoint.

What the UBL actually contains

<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>WC-11</cbc:ID>                        <!-- or INV-STRIPE-1759000000, FL-1F2E3A4B -->
<cbc:IssueDate>2026-09-02</cbc:IssueDate>
<cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode> <!-- 381 = credit note -->
<cbc:DocumentCurrencyCode>RON</cbc:DocumentCurrencyCode>
<cbc:TaxCurrencyCode>RON</cbc:TaxCurrencyCode>

CustomizationID is the CIUS-RO contract — the exact string urn:cen.eu:en16931:2017#compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1, alongside the PEPPOL BIS-3 ProfileID. If either is wrong, the document is out of scope before validation starts.
Invoice numbers arrive already prefixed by the source so origin is debuggable at a glance: WC-{orderId}, INV-STRIPE-{unixTs}, with FL-XXXXXXXX as the core's fallback.
Currency. TaxCurrencyCode is always RON even when the checkout was in EUR. For any DocumentCurrencyCode != RON, CIUS-RO (BR-53) demands a second cac:TaxTotal in RON converted at the BNR reference rate for the issue date, plus a cac:PaymentExchangeRate block. Never assume "the checkout currency is the invoice currency."
VAT categories. Positive rates emit category S; zero-rate lines emit the profile's zero category via getZeroRateCategoryId() (default Z — the France/Chorus Pro adapter overrides it to E). CIUS-RO validates the consistency of category, percent, and amounts, so whatever your zero-rate policy is, it must be applied in the one builder, not per mapper.

Pitfalls checklist

2xx ≠ processed — require the explicit processed: true in the response body before marking anything terminal.
Never send tax as a monetary amount; the UBL wants per-line rates, and document VAT is derived from them (BR-45/BR-CO).
Webhook events arrive unexpanded — retrieve the Stripe session with expand: ['line_items', 'customer'] before mapping; same for expand[]=payload on Stripe Secret Store reads (without it, reads return null forever and every merchant looks disconnected).
Verify signatures over the raw request bytes you captured, not a re-stringified body.
Idempotency belongs at the order/event level for webhooks (post-meta, event id); keep the HTTP Idempotency-Key mechanism for your own API.
Trust provider order totals; only derive per-line amounts, then prove Σlines == total in tests.
Treat 400s from webhooks as alarms, not noise — they are configuration deaths, and "permanent error" bookkeeping makes them silent.
Issuer CIF must be checksum-valid and authorized in the SPV; buyer CIF stays optional for B2C — don't invent one.

The same pipeline — canonical JSON in the middle, one CIUS-RO builder, explicit processed semantics — is what FiscalLink for ANAF runs in production (autoanaf.ro); these lessons cost us a staging week.

ANAF e-Factura UBL Rejections: What EN 16931 / CIUS-RO Validation Errors Look Like and How to Catch Them Before ANAF Does

Vlad Cristian Alexa — Thu, 03 Sep 2026 15:10:14 +0000

Uploading well-formed UBL XML to ANAF e-Factura is the easy part. Accepting your upload and validating your invoice are two different moments, separated by minutes or hours: ANAF returns a submission index immediately, then the validation verdict arrives later as an asynchronous message. When the verdict is a rejection, all you get is one Romanian sentence in a detalii field — no structured error list, no line number.

This is a code-first tour of what happens between "upload accepted" and "invoice rejected", grounded in a production Spring Boot integration with the ANAF SPV API: what ANAF validates (EN 16931 + CIUS-RO), the real shape of rejection answers, the pre-flight checks you can run locally, the CIF checksum trap, and the semantics of polling, retries and quota.

How ANAF validates: EN 16931 + CIUS-RO

Romanian e-Factura is built on EN 16931 (the European semantic invoice model with hundreds of business rules: BR-* document-level, BT-* field-level) plus the national extension CIUS-RO, which pins the exact CustomizationID your document must advertise and adds national requirements — a mandatory TaxCurrencyCode, and a second RON tax total for foreign-currency invoices.

The identifiers are exact strings, emitted verbatim by the production builder:

<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>   <!-- 381 for credit notes -->
<cbc:DocumentCurrencyCode>RON</cbc:DocumentCurrencyCode>
<cbc:TaxCurrencyCode>RON</cbc:TaxCurrencyCode>

CustomizationID is a conformance claim: writing #compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1 tells ANAF to validate you against CIUS-RO 1.0.1 — semantically, server-side. That is where most real rejections come from, because the OASIS UBL 2.1 XSD cannot express these rules: nothing in the XSD can require a specific CustomizationID, a TaxCurrencyCode, or RON totals on a foreign-currency invoice.

The builder shows which features trip semantic rules in practice:

Tax currency: TaxCurrencyCode is always RON. When DocumentCurrencyCode != RON, a second <cac:TaxTotal> in RON is emitted with a PaymentExchangeRate block (SourceCurrencyCode, TargetCurrencyCode=RON, CalculationRate, Date) using the BNR rate for the issue date. CIUS-RO BR-53 requires exactly this; omitting the RON tax total on a EUR invoice is a classic rejection.
VAT breakdown: each distinct rate gets its own <cac:TaxSubtotal> (TaxableAmount, TaxAmount, TaxCategory ID S standard / Z zero-rated, Percent, TaxScheme ID=VAT) inside TaxTotal; totals must reconcile with lines.
Monetary totals: LegalMonetaryTotal with LineExtensionAmount, TaxExclusiveAmount, TaxInclusiveAmount, PayableAmount — all carrying currencyID. A missing or mismatched PayableAmount is a common kill.
Lines: quantities use unitCode="C62"; a zero-item invoice violates EN 16931 BR-45.
Credit notes: type code 381, BillingReference/InvoiceDocumentReference to the original, and — for storno workflows — the original load index in the Note as index_incarcare_original: <index>.

Anatomy of a rejection: two failure moments

Upload-time (synchronous). POST /upload?standard=UBL&cif=<cif>&extern=DA&autofactura=DA returns XML, not JSON. Success:

<header ExecutionStatus="0" index_incarcare="11223344"/>

index_incarcare — the submission ID used later to match the answer. A synchronous refusal:

<header ExecutionStatus="1" errorMessage="CIF invalid"/>

ExecutionStatus != 0 is a permanent, non-retryable failure. A WAF/intermediary HTML page (detected via Your support ID is:), HTTP 429, a 5xx, or a non-XML body are classified retryable and go through exponential backoff.

Answer-time (asynchronous). Once index_incarcare is obtained, the invoice is submitted and real validation starts; a poller calls listaMesajeFactura?zile=60&cif=<cif> (60-day window) and matches each message by id_solicitare == index_incarcare. A message is flat JSON:

{
  "data_creare": "202604291200",
  "cif": "12345678",
  "id_solicitare": "99887766",
  "detalii": "Factura validata OK",
  "tip": "FACTURA PRIMITA",
  "id": "1001"
}

The verdict lives entirely in detalii — free-text Romanian. Rejections observed in fixtures:

Erori de validare identificate la factura transmisa cu id_incarcare=5035501773
S-au identificat erori la validarea facturii
Eroare la validare: CIF invalid
Factura respinsa din cauza formatului
Invalid schema
eroare: format invalid

Acceptances: Factura validata OK, Factura validata cu succes!, OK validat, Status: ok, with tip values like FACTURA PRIMITA (verbatim from code and fixtures). On rejection the invoice moves submitted → rejected, the job goes failed with error ANAF rejected: <detalii>, and an audit entry answer_rejected is recorded. Note: tip is not used for classification — only detalii; a load id, when present, is embedded in the sentence itself (id_incarcare=5035501773).

Pre-flight: three layers you can run before ANAF does

Waiting for an asynchronous rejection to catch a typo is expensive — with the 5-working-day legal deadline, sometimes fatal. Run three local layers in order.

Layer 1 — semantic completeness (En16931CompletenessValidator). Runs on the canonical data before XML generation: invoice fields (currency, issuer, buyer, items, totals), party names (BT-44), issuer VAT number for CIUS-RO (BT-31), at least one line (BR-45), per-line name/quantity/unitPrice/vatRate (BT-153/BT-146/BT-147/BT-152), totals subtotal/totalVAT/total. Failures are precise, e.g.:

items: at least one line item is required (EN 16931 BR-45)
issuer.vatNumber: required for CIUS-RO compliance (BT-31, supplier VAT identifier)
items[0].vatRate: required (EN 16931 BT-152, VAT category rate)

Layer 2 — XSD structure + CIUS-RO programmatic checks (UblSchemaValidator). After the UBL string is built it is validated against the real OASIS UBL 2.1 XSD set (bundled on the classpath, schemas/ubl21/UBL-Invoice-2.1.xsd, resolved with a custom LSResourceResolver, secure processing on). Because XSD can't express CIUS-RO, programmatic checks run first and short-circuit with actionable messages:

Missing or invalid CIUS-RO CustomizationID. Expected: urn:cen.eu:en16931:2017#compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1
Missing or invalid ProfileID. Expected: urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
InvoiceTypeCode must be 380 (invoice) or 381 (credit note)
Missing TaxCurrencyCode element — required by CIUS-RO BR-53
missing LegalMonetaryTotal/PayableAmount for invoices

Structural failures surface as XSD validation failed at line <L> (column <C>): <message>. In the submission job this gate is fatal before any HTTP call: the invoice goes straight to failed (UBL XSD validation failed: ...) — no retry, no quota slot consumed.

Layer 3 — identifier checksum (CifValidator). Next section.

The CIF checksum trap

Romanian CIF numbers carry a mod-11 control digit computed with multiplier 753217532 (a control value of 10 maps to 0). The validator strips an optional RO prefix, rejects non-numeric or out-of-range values, and applies the checksum — but only to numbers that start with RO (foreign VAT numbers are correctly skipped).

The trap: obvious test/placeholder numbers are almost all checksum-invalid. For RO12345678 the official check digit of base 1234567 is 4 (valid: RO12345674) — yet RO12345678 is the CIF used in countless examples, including fixtures in this codebase. It fails the algorithm, and a production API layer rejects it at invoice creation with Invalid Romanian VAT number for issuer: RO12345678 (IllegalArgumentException), long before any XML exists.

Two consequences:

Never fabricate or auto-generate CIFs — even "obviously fake" ones. Run the checksum (~10 lines; same algorithm as ANAF's client libraries) and reject bad numbers at the API boundary with a clear message, instead of letting them resurface as a generic ANAF error.
Checksum-valid ≠ registered. A checksum-valid but unregistered CIF (inactive, deregistered, registry typo) passes local checks and comes back from ANAF as a registry error. The recovery rules in the codebase recognize exactly this family: CIF invalid pentru cumparator, cif inactiv pentru buyer, BT-48 Buyer VAT identifier not found in registry (buyer), BT-31 ... supplier vat identifier ... (issuer) — mapped to ANAF_CIF_INVALID/BT-48/BT-31 hints on buyer.vatNumber / issuer.vatNumber, with an auto-fix that strips or adds the RO prefix (a frequent source of registry mismatches). Only ANAF can answer the registry question; the checksum answers the format question. Never conflate the two.

Answer classification: singular, plural, and keyword order

Because detalii is free text, classification is keyword matching. The reconciler lowercases and checks in this exact order: (1) acceptance first — contains ok, validat, or acceptat → accepted; (2) rejection second — contains eroare, erori, respins, invalid, or neconform → rejected; (3) otherwise log Unrecognised ANAF answer ... and change nothing.

Three subtleties that bite if you reimplement this:

Singular vs. plural. Real ANAF text uses both: Eroare la validare: CIF invalid (singular) and Erori de validare identificate la factura transmisa cu id_incarcare=5035501773 / S-au identificat erori la validarea facturii (plural). A matcher that looks for only one form silently strands invoices in submitted; the code matches both substrings explicitly.
Order matters. Acceptance is checked before rejection, so a detalii containing both ok and eroare would be classified accepted. Real ANAF strings don't mix them today, but test both directions.
Unknown text is a no-op, not a failure. The fixture Mesaj necunoscut din sistem changes nothing: the invoice stays submitted, and because polling matches by id_solicitare every six hours, the same unrecognized message is re-matched forever. Alert on repeated unmatched messages and dead-letter them manually.

Operational lessons: polling, quota semantics, retries

Validation is asynchronous by design. The upload answer is only an acceptance to process. Keep a submitted state and a poller — here every 6 hours (PT6H fixed delay) over 60 days, grouped per CIF, matching id_solicitare from the audit trail.
Handle degenerate list responses. {"eroare":"Nu exista mesaje"} is an empty result, not an error. Lista de mesaje este mai mare triggers the paginated fallback (listaMesajePaginatieFactura with startTime/endTime in epoch millis and numar_total_pagini; Pagina solicitata <N> este mai mare ... marks the last page). Treating these as failures turns a healthy poll into a false alarm.
Quota is refunded only on a real rejection. The tenant's quota slot is consumed at submission and decremented back only when a rejection answer lands — and only on a genuine status transition, so duplicate answers can't double-refund. An accepted credit note cancels the original invoice (status cancelled) and refunds its slot, unless the original was already rejected or cancelled. Refunding on "message seen" instead of "status changed" leaks quota.
Retry ≠ resubmit. Submission retries are exponential (5s × 2^(attempt-1), max 10, then dead_letter with Exceeded max retries (10)), but only transport failures are retryable: WAF pages, 429, 5xx, empty/non-XML bodies. A synchronous validation refusal (ExecutionStatus != 0) and other 4xx errors are permanent. An answer-time rejection is never retried: correct the document and resubmit as a new submission (new number, new load).
Keep the three failure buckets distinct in UI and metrics: transport failure (failed, retryable), submission-time validation refusal (failed, permanent), answer-time rejection (rejected, discovered hours later). The audit trail encodes it (ANAF_SUBMISSION_FAILED, UBL_SCHEMA_VALIDATION_FAILED, ANAF_ANSWER_RECEIVED), and hints even recognize the legal-deadline failure mode (ANAF: termen de depunere depasit (5 zile lucratoare)).

Pitfall checklist

CustomizationID must be the exact CIUS-RO string; a stale or PEPPOL-only value changes what ANAF validates you against.
Foreign-currency invoice without RON TaxTotal + PaymentExchangeRate → CIUS-RO BR-53 rejection.
TaxCurrencyCode missing or not RON; PayableAmount missing or unreconciled totals.
Checksum-invalid CIFs (e.g. RO12345678; real check digit 4): reject at the API, not at ANAF.
Checksum-valid but unregistered CIF: only ANAF's registry can tell you — map the CIF invalid/cif inactiv family to a human action.
Classifier matching only eroare and missing erori (or vice versa) strands invoices in submitted.
Treating Nu exista mesaje as an error, or refunding quota on duplicate answers.
Retrying permanent validation refusals instead of correcting the document.

If you'd rather not rebuild this pipeline — CIUS-RO generation, XSD gates, CIF checksum, answer polling, rejection hints — FiscalLink (autoanaf.ro) runs exactly these pre-flight checks for Romanian e-invoicing.

ANAF SPV E-Invoicing from Java/Spring Boot: OAuth2, JWT Access Tokens, and a Refresh Window That Never Rests

Vlad Cristian Alexa — Thu, 03 Sep 2026 15:03:04 +0000

ANAF SPV E-Invoicing from Java/Spring Boot: OAuth2, JWT Access Tokens, and a Refresh Window That Never Rests

Integrating with ANAF's SPV API for Romanian e-invoicing has a personality: sparse documentation, error messages in Romanian, a login flow that needs a human with a digital certificate, and JWT access tokens that expire after roughly ten minutes. The OAuth2 machinery itself is textbook — authorization code flow with client authentication — but every quirk around it decides whether you ship in a day or debug for a week. Below is the flow exactly as it runs in production Spring Boot code, including an honest look at what the refresh logic actually does with ANAF's short-lived tokens.

The flow ANAF actually runs

ANAF SPV (Sistemul Privat Virtual) e-Factura is the mandatory channel for B2B e-invoices in Romania, and machine access is not a plain API key: it is OAuth2 authorization code, after which every REST call carries Authorization: Bearer <jwt>. Two details make it special. First, token_content_type=jwt must appear on the authorize request and on the token exchange — omit it and ANAF returns a legacy token format. Second, the "user" authentication happens in a browser, where a person logs in with their digital certificate; your backend only ever sees the one-time code, exchanged over HTTPS.

The full dance: your app redirects the operator to ANAF's login page → the operator authenticates with the certificate → ANAF redirects to your callback with ?code=... → your backend exchanges the code at the token endpoint and receives access_token, refresh_token, expires_in → every subsequent SPV call uses the JWT.

Configuration that drives everything

Real endpoints, straight from application.yml:

app:
  anaf:
    api-key: ${ANAF_API_KEY:}
    api-url: ${ANAF_API_URL:https://api.anaf.ro/prod/FCTEL/rest}
    oauth:
      client-id: ${ANAF_CLIENT_ID:}
      client-secret: ${ANAF_CLIENT_SECRET:}
      authorization-url: ${ANAF_OAUTH_AUTHORIZATION_URL:https://logincert.anaf.ro/anaf-oauth2/v1/authorize}
      token-url: ${ANAF_OAUTH_TOKEN_URL:https://logincert.anaf.ro/anaf-oauth2/v1/token}
      callback-url: ${ANAF_OAUTH_CALLBACK_URL:https://api.fiscallink.io/v1/auth/anaf/callback}

These land in AnafTokenManager as @Value fields, and every lookup applies the same precedence rule: database settings first, environment variables second — firstNonBlank(s.getAnafClientId(), envClientId). Operators can reconnect a new ANAF account without a redeploy. Note the two hosts: logincert.anaf.ro is the OAuth server, api.anaf.ro serves the SPV data endpoints and the test hello endpoint.

Step 1 — build the authorize URL

AnafAuthController exposes GET /v1/auth/anaf/authorize: hit it from a browser (Accept: text/html) and it 302-redirects you to ANAF; call it from an API client and it returns the URL as JSON. The URL is assembled in AnafTokenManager.getAuthorizationUrl(state):

StringBuilder url = new StringBuilder(authorizationUrl)
        .append("?response_type=code")
        .append("&client_id=").append(enc(clientId))
        .append("&redirect_uri=").append(enc(callbackUrl))
        .append("&token_content_type=jwt");
if (state != null && !state.isBlank()) url.append("&state=").append(enc(state));
return url.toString();

token_content_type=jwt is already in the query string, and callbackUrl is a single configuration value used everywhere — it must match byte-for-byte the redirect URI registered for your client in ANAF SPV. Scheme, host, path: one character off and the login dies with a redirect URI mismatch. The controller also generates CSRF state (UUID.randomUUID().toString()) and logs it — but see the pitfalls: this callback accepts state without ever verifying it, so add that check in yours.

Step 2 — exchange the code

ANAF redirects the operator's browser to GET /v1/auth/anaf/callback?code=...&state=.... The controller hands the code to exchangeCodeForToken(code), which posts to the token endpoint using HTTP Basic client authentication and a form-urlencoded body:

String formBody = "grant_type=authorization_code"
        + "&code="         + enc(code)
        + "&redirect_uri=" + enc(callbackUrl)
        + "&token_content_type=jwt";

String response = restClient.post()
        .uri(tokenUrl)
        .header(HttpHeaders.AUTHORIZATION, basicAuth(clientId, clientSecret))
        .contentType(MediaType.APPLICATION_FORM_URLENCODED)
        .body(formBody)
        .retrieve()
        .body(String.class);

parseAndStore(s, response);

basicAuth() is just base64 of clientId + ":" + clientSecret — client credentials travel in the Authorization: Basic header, not in the body, a classic gotcha if you are used to other providers. redirect_uri here is the identical string sent on authorize, and token_content_type=jwt is mandatory again. The code is single-use: exchange it immediately and never log it.

Step 3 — store what ANAF returns

parseAndStore reads the token JSON and persists it into the AppSettings row (id "default"):

JsonNode json = objectMapper.readTree(jsonResponse);
String accessToken  = json.path("access_token").asText(null);
String refreshToken = json.path("refresh_token").asText(null);
long   expiresIn    = json.path("expires_in").asLong(3600);
// ...
s.setAnafApiKey(accessToken);
if (refreshToken != null && !refreshToken.isBlank()) s.setAnafRefreshToken(refreshToken);
s.setAnafTokenExpiresAt(Instant.now().plusSeconds(expiresIn));
return appSettingsRepository.save(s);

Two bookkeeping fields drive everything later: the refresh token and the expiry instant. If expires_in is missing the fallback is 3600 seconds; when a token is pasted manually via POST /v1/auth/anaf/token (storeToken), the fallback is 600 seconds — the same order of magnitude as ANAF's real JWT lifetime, which is the number that matters next.

Step 4 — getValidAccessToken, or the refresh window that never rests

Every SPV call funnels through AnafTokenManager.getValidAccessToken():

@Transactional
public String getValidAccessToken() {
    AppSettings s = getOrCreate();

    if (s.getAnafRefreshToken() == null || s.getAnafRefreshToken().isBlank()) {
        return firstNonBlank(s.getAnafApiKey(), envAnafApiKey);
    }

    if (shouldRefresh(s)) {
        try {
            s = performRefresh(s);
        } catch (Exception e) {
            log.warn("ANAF token refresh failed — continuing with current token: {}", e.getMessage());
        }
    }
    return firstNonBlank(s.getAnafApiKey(), envAnafApiKey);
}

private boolean shouldRefresh(AppSettings s) {
    if (s.getAnafTokenExpiresAt() == null) return false;
    return Instant.now().plusSeconds(REFRESH_WINDOW_SECONDS).isAfter(s.getAnafTokenExpiresAt());
}

with private static final long REFRESH_WINDOW_SECONDS = 86_400L; — the class comment says tokens are "auto-refreshed 24h before expiry". Be honest about what that means against ANAF's real token lifetime: the check refreshes whenever the token expires within the next 86,400 seconds, and a JWT that lives ~600–3600 seconds is always inside that window. So with a refresh token configured, every call to getValidAccessToken() triggers performRefresh() first:

String formBody = "grant_type=refresh_token"
        + "&refresh_token="      + enc(s.getAnafRefreshToken())
        + "&token_content_type=jwt";
// POST to the same token URL, same HTTP Basic header, then parseAndStore(...)

(no redirect_uri on the refresh grant — ANAF does not expect it there). That 24-hour window makes sense for a provider issuing 24h+ tokens, which ANAF is not; as implemented, the refresh never "rests": each SPV call first pays for a token-exchange round-trip, then executes the real request with a fresh JWT. Consequences to plan for: added latency per call, and no in-memory caching of the access token — every call re-reads AppSettings. If your traffic is bursty, add a small in-memory cache keyed by the stored expiry and refresh at most once per minute, keeping this class the single source of truth. And when a refresh fails, the code logs a warning and continues with the existing token; the next SPV call then fails with HTTP 401, which AnafClient surfaces as a result, not an exception.

Concurrency: transactional, single instance, last-write-wins

getValidAccessToken(), exchangeCodeForToken(), and storeToken() are @Transactional, and there is no token state shared between threads — every call re-reads the database row. On one instance, two concurrent requests can both observe "should refresh" and both hit the token endpoint; each exchange saves its result and the last write wins. If ANAF invalidates a refresh token after use, the losing thread's next refresh fails with invalid_grant — swallowed by the catch-and-continue path, then recovered on the next successful refresh. In practice: keep refresh cheap, run a single instance for the ANAF worker (or add single-flight locking around refresh), and treat the token store as shared state you serialize.

There is also a deliberate dev-skip convention: when nothing is configured, getValidAccessToken() returns null, and AnafClient answers SubmissionResult.devSkip() — a synthetic success carrying the id "DEV-SKIP" — so local development never touches ANAF. No token configured, no network call, no crash.

Testing your token: the hello endpoint

ANAF publishes a smoke-test endpoint, separate from the data API: GET https://api.anaf.ro/TestOauth/jaxrs/hello?name=... with your Bearer token. testConnection() wraps exactly that:

String body = restClient.get()
        .uri("https://api.anaf.ro/TestOauth/jaxrs/hello?name=fiscallink")
        .header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
        .retrieve()
        .body(String.class);
result.put("connected", true);
result.put("response", body);

Exposed through GET /v1/auth/anaf/status, it is the fastest way to tell "token expired or wrong client" (HTTP 401) apart from "ANAF is down" (timeout, 5xx, or a WAF page). POST /v1/auth/anaf/token even runs this check before answering, so manual injections are verified immediately.

Then the real calls

AnafClient is the single integration point for SPV: it takes the Bearer token from the manager, never throws, and returns result records — SubmissionResult, MessageListResult, AnswerDownloadResult — that callers inspect via success() / errorMessage():

String token = tokenManager.getValidAccessToken();
if (token == null || token.isBlank()) {
    log.warn("ANAF API key not configured — skipping submission for VAT {} (dev mode)", vatNumber);
    return SubmissionResult.devSkip();
}
// ...
String response = restClient.post()
        .uri(uri.toString())                       // /upload?standard=UBL&cif=...
        .header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
        .contentType(MediaType.TEXT_PLAIN)         // raw UBL XML — not multipart, not application/xml
        .body(xmlToSend)
        .retrieve()
        .body(String.class);

Submission is POST {api-url}/upload?standard=UBL&cif=RO12345607[&extern=DA][&autofactura=DA] with the raw UBL 2.1 XML as text/plain (the xsi:schemaLocation is stripped first — ANAF is picky). The response is XML, and acceptance means ExecutionStatus="0" plus an index_incarcare id; business rejections arrive as HTTP 200 with an errorMessage attribute. Answers are polled with GET /listaMesajeFactura?zile=...&cif=...&filtru=E|T|P|R, falling back automatically to paginated GET /listaMesajePaginatieFactura?startTime=<epochMillis>&endTime=...&cif=...&pagina=..., and downloaded from GET /descarcare?id=... as a ZIP (the code checks the 0x50 0x4B magic bytes before trusting it). Error payloads come back in Romanian — "Lista de mesaje este mai mare...", "nu exista mesaje", "Pagina solicitata ... este mai mare" — matched by string and mapped onto structured results. HTTP 429 and 5xx are flagged retryable so the job layer backs off; business rejections are not retried.

Pitfalls checklist

token_content_type=jwt on authorize and on the code exchange and on refresh. Forgetting it changes the token format ANAF hands you.
redirect_uri must equal the ANAF-registered URI exactly and stay identical across authorize and exchange; keep it in one config value.
ANAF JWTs are short-lived (~10 minutes). Verify the CSRF state on the callback — this codebase logs it but does not check it; yours should.
Never log the code, tokens, or Authorization headers. Even error paths should trim raw token responses — the "missing access_token" exception embeds the whole response body, so truncate it in production.
Expect HTML sometimes: ANAF sits behind a WAF. Detect pages containing Your support ID is: and treat them as infrastructure errors, not business answers.
Timeouts matter: connect 10 s, read 30 s (app.anaf.connect-timeout-ms, app.anaf.read-timeout-ms); slow days at ANAF are real.
Answer downloads are ZIPs — validate the PK magic before unzipping anything.
One-time codes: exchange immediately, never retry with the same code.
A static ANAF_API_KEY fallback is a rotation dead-end: without a refresh token, nothing ever auto-refreshes. Prefer the full OAuth flow.

The token manager and client above are the same code path that files real e-Factura invoices every day in FiscalLink's production ANAF integration — quirks included.