e-Faktura API

Idempotency

Every write except POST /v1/oauth/token requires an Idempotency-Key header — any unique string, typically a UUID v4 generated once per logical request and reused on every retry of that same request.

Idempotency-Key: 8f14e45f-ceea-467f-b0e8-c1f9dc1e6f8f

• Replaying the same key with the same request body returns the original response (with Idempotent-Replayed: true), without doing the work twice.
• Replaying the same key with a different body is a 409 idempotency_conflict.
• Keys are remembered for 24 hours.

Beyond 24 hours — clientReference

For issuing e-invoices specifically, clientReference on POST /v1/einvoices gives you idempotency that outlives the 24-hour Idempotency-Key window: replaying the same clientReference with the same body always returns the existing document (200, not 202), indefinitely. A different body with the same clientReference is a 409 client_reference_conflict. This is what makes it safe to retry issuing an invoice from a queue or a cron job days later without risking a duplicate filing at UJP.

What’s naturally idempotent

GET requests, POST /v1/einvoices/validate (never submits anything) and status-refresh calls don’t need an idempotency key at all — they have no side effects to duplicate.