Katalog zdarzeń

W każdym doręczeniu webhooka znajduje się zdarzenie opisujące konkretny etap cyklu życia faktury. Wszystkie zdarzenia mają tę samą strukturę i przenoszą fakturę w stanie z tego etapu, dzięki czemu jeden handler obsłuży dowolny typ zdarzenia, wystarczy rozgałęzić logikę według pola type.

Struktura zdarzenia

Zdarzenie ma stałą strukturę zewnętrzną, a właściwa faktura jest zagnieżdżona pod data.object. Zagnieżdżony obiekt to ten sam kształt Invoice, który zwraca Developer API, odzwierciedlający status faktury w chwili utworzenia zdarzenia.

  • idstring

    Publiczny identyfikator zdarzenia z prefiksem evt_. Deduplikuj doręczenia po tej wartości.

  • objectevent

    Typ obiektu.

  • typestring

    Typ zdarzenia, jeden z sześciu zdarzeń cyklu życia faktury poniżej.

  • modetest | live

    Czy faktura jest testowa, czy live.

  • account_idstring

    Publiczny identyfikator konta.

  • organization_idstring

    Publiczny identyfikator organizacji.

  • created_atstring

    Czas utworzenia zdarzenia. Zdarzenia z jednej transakcji mogą mieć wspólny znacznik czasu i nie ma gwarancji globalnego uporządkowania.

  • dataobject

    Wrapper, którego pole object to faktura.

invoice.received

Emitowane, gdy wysyłka zostaje przyjęta do cyklu życia produktu. Zagnieżdżona faktura ma status received. To najwcześniejsze zdarzenie cyklu życia; potwierdza, że faktura istnieje i jest w kolejce do przetworzenia.

invoice.processing

Emitowane, gdy faktura jest przetwarzana lub czeka na przetworzenie w wyznaczonym terminie. Zagnieżdżona faktura ma status processing. Faktura może przechodzić przez ten stan więcej niż raz, gdy w grę wchodzą ponowienia.

invoice.accepted

Emitowane, gdy faktura zostaje przyjęta. Zagnieżdżona faktura ma status accepted, a dla przyjętych faktur ksef_number jest wypełnione; upo_available może wciąż być false, dopóki nie istnieje artefakt UPO.

invoice.accepted
{  "id": "evt_V3sGDb5VXxLxzGzvYVw0Pw",  "object": "event",  "type": "invoice.accepted",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "accepted",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": "KSEF-TEST-8D7C6B5A4E3F2A1B0C9D",      "upo_available": true,      "retrying": false,      "next_retry_at": null,      "last_error": null,      "metadata": {        "order_id": "ord_123"      }    }  }}

invoice.rejected

Emitowane przy nieponawialnym odrzuceniu produktowym lub biznesowym. Zagnieżdżona faktura ma status rejected i niesie last_error opisujące odrzucenie.

invoice.rejected
{  "id": "evt_U8wYyy6fj34N1D6lH6ZPLQ",  "object": "event",  "type": "invoice.rejected",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "rejected",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": null,      "upo_available": false,      "retrying": false,      "next_retry_at": null,      "last_error": {        "code": "sandbox_invoice_rejected",        "message": "The sandbox invoice was rejected.",        "retryable": false      },      "metadata": {        "order_id": "ord_123"      }    }  }}

invoice.failed

Emitowane przy awarii technicznej lub przetwarzaniu zakończonym po wyczerpaniu ponowień. Zagnieżdżona faktura ma status failed i niesie last_error z kodem awarii. W przeciwieństwie do odrzucenia awaria oznacza, że faktury nie dało się przetworzyć. Nie oznacza niepowodzenia opartego na regule biznesowej.

invoice.upo_available

Emitowane, gdy utrwalony artefakt UPO XML staje się dostępny dla przyjętej faktury. Zagnieżdżona faktura ma upo_available: true. Po tym zdarzeniu UPO można pobrać przez Developer API. Zobacz Cykl życia faktury i UPO.

invoice.upo_available
{  "id": "evt_XjW1g8KMqJj6fW3Az7bXzQ",  "object": "event",  "type": "invoice.upo_available",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "accepted",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": "KSEF-TEST-8D7C6B5A4E3F2A1B0C9D",      "upo_available": true,      "retrying": false,      "next_retry_at": null,      "last_error": null,      "metadata": {        "order_id": "ord_123"      }    }  }}

Zdarzenia invoice.received, invoice.processing i invoice.failed korzystają z tej samej struktury, z data.object niosącym fakturę w odpowiednim statusie. Pełną listę statusów znajdziesz w Statusy faktur.