كل التغييرات

added GET /api/v1/e-invoice/jobs/{job_id} returns the job descriptor: status (pending | completed | failed), data residency, created/expiry timestamps, validation state, and per-artifact availability, content type, size, and expiring download URL. Authenticates with the same Bearer token that created the job.

added GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact} streams raw artifact bytes for pdf, xml, report (only when report.enabled = true), and request (only when retention.store_request = true).

added settings.e_invoice.delivery: mode (inline_pdf | object) selects the response shape; url_ttl_seconds (range 1..900, default 300) bounds artifact download URLs.

added settings.e_invoice.retention: ttl_hours (range 1..23, default 23) bounds object-mode artifacts and job metadata; store_request additionally stores the original request body as an artifact.

added settings.e_invoice.data_residency: auto resolves eu / global from the invoice country; eu and global force a residency profile; strict turns an unresolvable country into an API-002 error instead of a fallback.

What’s new

POST /api/v1/e-invoice/render now supports two delivery modes. The default, delivery.mode = inline_pdf, returns the PDF/A-3b bytes inline exactly as before. Setting delivery.mode = object instead returns a JSON job descriptor and stores the render outputs as artifacts you download separately — for pipelines that need the embedded XML or the validation report alongside the PDF, or that hand the outputs to another system.

The endpoint family

Endpoint	Auth	Purpose
`POST /api/v1/e-invoice/render`	Required	Render. Returns inline PDF or a job descriptor.
`GET /api/v1/e-invoice/jobs/{job_id}`	Required	Poll an object-mode job.
`GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact}`	Required	Download a job artifact.
`GET /api/v1/e-invoice/capabilities`	None	Static capability registry (advertises delivery and residency modes).

Job lookup and artifact download authenticate with the same Bearer token that created the job.

Artifacts

{artifact} is one of:

pdf — the signed PDF/A-3b document
xml — the embedded CII XML
report — validation report (only when report.enabled = true)
request — original request body (only when retention.store_request = true)

The job descriptor lists available, content_type, bytes, expires_at_ms, and a download URL per artifact; the URL carries its own expiry and is fetched with the same Bearer token.

Lifetime controls

delivery.url_ttl_seconds (range 1..900, default 300) bounds how long artifact download URLs stay valid.
retention.ttl_hours (range 1..23, default 23) bounds the artifacts and job metadata themselves. After it elapses, artifact downloads return 404 and job lookup returns metadata only.

Data residency

settings.e_invoice.data_residency picks where object-mode artifacts are stored: auto resolves eu / global from the invoice country (e.g. DE → eu, US → global), eu and global force a profile, and strict = true makes an unresolvable country a hard API-002 error rather than a fallback.

Compatibility

Object delivery is opt-in. Requests that omit delivery — or set delivery.mode = inline_pdf — behave exactly as before: inline PDF, no job created, nothing stored.

See the E-invoice API reference for the full contract, including the two end-to-end validation flows.