Introduction

info

If you are interested in using and accessing the Fast KSeF REST API, please contact our staff at the following Email address: [kontakt@fast-ksef.pl].

Fast KSeF REST API

The REST API enables the integration of external systems with the National e-Invoice System (KSeF) via the FastKSeF platform.

Architecture

Client  ──────▶  REST API  ──────▶  ksef-proxy (Edge Function)  ──────▶  KSeF API
                  │                        │
                  ▼                        ▼
             Local Logic               PostgreSQL (sync DB)
             - validation              - session references
             - date formatting         - invoice links SETTLE↔ADVANCE,
             - PDF generation          - correction invoices,
             - QR generation           - sync metadata
             - base64 encoding         - failure handling/simulation

The REST API is a thin wrapper — it never communicates with KSeF directly. All KSeF operations are delegated to ksef-proxy, which plays a dual role:

1. HTTP Proxy — the sole point of communication with the KSeF API, handling authentication, token refreshing, and connection status verification.
2. DB Synchronizer — maintains data consistency between KSeF and the local database:
   • Assigns session_reference_number to synced_invoices and offline_invoices during submission/status checks.
   • Links advance invoices (SETTLE ↔ ADVANCE) via advance_groups / advance_group_invoices.
   • Links correction invoices (CORR ↔ original) via invoice_corrections.
   • Updates invoice_sync_meta during synchronization.

The REST API is responsible exclusively for local logic: input validation, date formatting, base64 encoding/decoding, server-side PDF generation (ksef-pdf-generator), and QR code generation.

Authorization

All endpoints (except for GET /status and GET /openapi.json) require Basic Auth authentication:

Authorization: Basic base64(email:password)

warning

The user must have the admin or technical role.

KSeF Environments

The {environment} parameter accepts the following values:

Value	Description
test	KSeF test environment
demo	KSeF demo environment
prod	KSeF production environment

Date Format

Dates returned by the API are of type string. The format is configurable via the api.date.format key in the system_config table (default: yyyy-MM-dd HH:mm:ss).

Session Reference Tracking

When invoices are sent or their status is checked, ksef-proxy automatically stores the session_reference_number in synced_invoices (online) and offline_invoices (batch). This reference is required to download UPO later.

Swagger UI

Interactive Swagger UI documentation is available at:

GET /swagger

The OpenAPI 3.0 specification is available at:

GET /openapi.json