KSeF Faktury
EN
Join the start list
Early access

The API is in early access: we hand out test keys (KSeF TEST) in batches to people on the launch list. Live mode comes later.

Request access

Guides

Pagination and rate limits

Lists return pages, newest first, and every key may make 100 requests per minute with clear headers.

Lists

List endpoints (/v1/invoices, /v1/events, /v1/webhook_endpoints) return objects newest first in an envelope:

{ "object": "list", "url": "/v1/invoices", "has_more": true, "data": [ ... ] }
Parameter Meaning
limit Objects per page: 1-100, default 10.
starting_after Id of the last object of the previous page.

When has_more is true, ask for the next page with starting_after set to the id of the last item in data.

All invoices, page by page
AFTER=""
while :; do
  PAGE=$(curl -s "https://app.ksefshop.pl/v1/invoices?limit=100${AFTER:+&starting_after=$AFTER}" \
    -H "Authorization: Bearer $KSEF_API_KEY")
  echo "$PAGE" | jq -r '.data[] | [.number, .ksef_number, .status] | @tsv'
  [ "$(echo "$PAGE" | jq -r .has_more)" = "true" ] || break
  AFTER=$(echo "$PAGE" | jq -r '.data[-1].id')
done

Filters

  • GET /v1/invoices?external_id=SO-1001 returns the invoice of one order (with corrections).
  • GET /v1/events?type=invoice.rejected returns events of one type only.

Rate limits

Each key may make 100 requests per minute. Every response carries:

Header Meaning
RateLimit-Limit The limit per window (100).
RateLimit-Remaining Requests left.
RateLimit-Reset Seconds until the window resets.

Over the limit you get 429 rate_limited with a Retry-After header in seconds. Retry code is in the idempotency guide.

Staying under the limit

  • Receive webhooks instead of polling every invoice every few seconds.
  • If you poll, poll every 3-5 seconds and stop at a final state.
  • For reports, fetch pages of 100 objects rather than single invoices.
  • Test and live keys have separate limits.
KSeF Faktury

API early access

We hand out test keys in batches. Leave your email: we will write when your access is ready.