Referencja API

Zdarzenia

Zdarzenia o stanach końcowych faktur i korekt. Te same obiekty wysyłają webhooki; lista służy do uzgadniania, gdy coś nie dotarło.

GET/v1/events
GET/v1/events/{id}

Obiekt Event

Zdarzenie o końcowym stanie dokumentu. Te same obiekty dostajesz webhookiem i z listy /v1/events.

Pola

idstringwymagane
Id zdarzenia (to samo co w nagłówku KSeF-Event-Id).
Prefiks evt_
objectstringwymagane
Rodzaj obiektu.
Zawsze event
typestringwymagane
Typ zdarzenia. Typy
Jedna z: invoice.accepted, invoice.rejected, invoice.skipped, correction.accepted, correction.rejected, correction.skipped
livemodebooleanwymagane
Tryb dokumentu.
createdintegerwymagane
Kiedy powstało zdarzenie (sekundy Unix).
dataobjectwymagane
Dane zdarzenia.
Pokaż pola
- objectInvoice | Correctionwymagane
  Faktura albo korekta w stanie z chwili zdarzenia.

Obiekt Event

{
  "id": "evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
  "object": "event",
  "type": "invoice.accepted",
  "livemode": false,
  "created": 1760865214,
  "data": {
    "object": {
      "id": "inv_4fJ2kP9xQwErTy7uI0oPaSdF",
      "object": "invoice",
      "livemode": false,
      "status": "accepted",
      "order": {
        "external_id": "SO-1001",
        "number": "1001"
      },
      "number": "FV/2026/10/1",
      "ksef_number": "4235405606-20261019-0E7570400000-57",
      "ksef_environment": "test",
      "issue_date": "2026-10-19",
      "currency": "PLN",
      "total_gross": "163.99",
      "buyer_nip": "5260250274",
      "pdf_url": "https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w",
      "last_error": null,
      "created": 1760865185,
      "updated": 1760865214,
      "corrections": []
    }
  }
}

Lista zdarzeń

GET /v1/events

Te same zdarzenia, które wysyłają webhooki, od najnowszych. Przydaje się do uzgadniania, gdy Twój serwer nie odbierał webhooków. Filtr type zawęża listę do jednego typu.

Parametry

limitquery · integer
Ile obiektów na stronie.
Domyślnie 10 · 1-100
starting_afterquery · string
Id ostatniego obiektu poprzedniej strony.
typequery · string
Tylko zdarzenia tego typu.
Jedna z: invoice.accepted, invoice.rejected, invoice.skipped, correction.accepted, correction.rejected, correction.skipped

Odpowiedzi

200Strona zdarzeń.
400Błędne żądanie, np. parameter_invalid buyer_nip_invalid vat_rate_unsupported
401Brak klucza albo zły klucz: api_key_missing api_key_invalid
404Nie ma takiego obiektu (albo należy do innego konta lub trybu): resource_missing

GET /v1/events

curl "https://app.ksefshop.pl/v1/events?limit=10" \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/events?limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo count($data['data']), ' obiektów', PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/events?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.data.length, data.has_more);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/events?limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(len(data["data"]), data["has_more"])

Odpowiedź

{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": []
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "buyer_nip_invalid",
    "message": "buyer.nip is not a valid Polish NIP (checksum).",
    "param": "order.buyer.nip",
    "doc_url": "https://ksefshop.pl/api/errors#buyer_nip_invalid"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is wrong, revoked, or the account is disabled.",
    "doc_url": "https://ksefshop.pl/api/errors#api_key_invalid"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'",
    "doc_url": "https://ksefshop.pl/api/errors#resource_missing"
  }
}

Pobierz zdarzenie

GET /v1/events/{id}

Jedno zdarzenie po id evt_... (to samo id przychodzi w nagłówku KSeF-Event-Id).

Parametry

idpath · stringwymagane
Identyfikator obiektu.
Prefiks evt_

Odpowiedzi

200Zdarzenie.
401Brak klucza albo zły klucz: api_key_missing api_key_invalid
404Nie ma takiego obiektu (albo należy do innego konta lub trybu): resource_missing

GET /v1/events/{id}

curl https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8 \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['type'], true), ' ', var_export($data['id'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.type, data.id);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["type"], data["id"])

Odpowiedź

{
  "id": "evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
  "object": "event",
  "type": "invoice.accepted",
  "livemode": false,
  "created": 1760865214,
  "data": {
    "object": {
      "id": "inv_4fJ2kP9xQwErTy7uI0oPaSdF",
      "object": "invoice",
      "livemode": false,
      "status": "accepted",
      "order": {
        "external_id": "SO-1001",
        "number": "1001"
      },
      "number": "FV/2026/10/1",
      "ksef_number": "4235405606-20261019-0E7570400000-57",
      "ksef_environment": "test",
      "issue_date": "2026-10-19",
      "currency": "PLN",
      "total_gross": "163.99",
      "buyer_nip": "5260250274",
      "pdf_url": "https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w",
      "last_error": null,
      "created": 1760865185,
      "updated": 1760865214,
      "corrections": []
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is wrong, revoked, or the account is disabled.",
    "doc_url": "https://ksefshop.pl/api/errors#api_key_invalid"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'",
    "doc_url": "https://ksefshop.pl/api/errors#resource_missing"
  }
}

Zdarzenia

Obiekt Event

Pola

Lista zdarzeń

Parametry

Odpowiedzi

Pobierz zdarzenie

Parametry

Odpowiedzi

Wczesny dostęp do API

Dziękujemy!