KSeF Faktury
PL
Zapisz się na start
Wczesny dostęp

API jest we wczesnym dostępie: klucze testowe (KSeF TEST) wydajemy partiami osobom z listy startowej. Tryb produkcyjny włączymy później.

Poproś o dostęp

Przewodniki

Paginacja i limity zapytań

Listy zwracają strony od najnowszych obiektów, a każdy klucz ma limit 100 zapytań na minutę z czytelnymi nagłówkami.

Listy

Endpointy list (/v1/invoices, /v1/events, /v1/webhook_endpoints) zwracają obiekty od najnowszych w kopercie:

{ "object": "list", "url": "/v1/invoices", "has_more": true, "data": [ ... ] }
Parametr Znaczenie
limit Ile obiektów na stronie: 1-100, domyślnie 10.
starting_after Id ostatniego obiektu z poprzedniej strony.

Gdy has_more ma wartość true, poproś o następną stronę z starting_after równym id ostatniego elementu data.

Wszystkie faktury strona po stronie
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

Filtry

  • GET /v1/invoices?external_id=SO-1001 zwraca fakturę jednego zamówienia (z korektami).
  • GET /v1/events?type=invoice.rejected zwraca tylko zdarzenia jednego typu.

Limity zapytań

Każdy klucz może wykonać 100 zapytań na minutę. Każda odpowiedź ma nagłówki:

Nagłówek Znaczenie
RateLimit-Limit Limit w oknie (100).
RateLimit-Remaining Ile zapytań zostało.
RateLimit-Reset Za ile sekund okno się odnowi.

Po przekroczeniu dostaniesz 429 rate_limited i nagłówek Retry-After z liczbą sekund do odczekania. Kod ponawiania jest w przewodniku idempotencja.

Jak nie wpaść w limit

  • Zamiast odpytywać każdą fakturę co kilka sekund, odbieraj webhooki.
  • Odpytując, rób to co 3-5 sekund i przestań po stanie końcowym.
  • Do raportów pobieraj strony po 100 obiektów, a nie pojedyncze faktury.
  • Testowe i produkcyjne klucze mają osobne limity.
KSeF Faktury

Wczesny dostęp do API

Klucze testowe wydajemy partiami. Zostaw e-mail: napiszemy, gdy dostęp będzie gotowy.