Changelog i wersjonowanie API — Polska
Datowane wersje API, polityka wycofań i ostatnie zmiany — REST API dla Polska.
Architektura — Model wersjonowania API dla Polska
Używamy wersji API datowanych: Accept-Version: 2026-03-15. W ramach wersji zmiany są tylko addytywne (nowe pola, nowe endpointy, nowe enum za flagami opt-in). Breaking changes wychodzą jako nowa data. Konto przypięte do wersji aktywnej przy zakładaniu, chyba że jawnie podniesiesz. Zmiany w kanale KSeF są wersjonowane osobno i widoczne w payloadzie faktury.
Jak to zintegrować — Polityka wycofań
Wycofania zapowiadamy ≥12 miesięcy wcześniej trzema kanałami: banner w dashboardzie, miesięczny e-mail changelog i nagłówek Sunset na dotkniętych endpointach. Nigdy nie usuwamy pól po cichu. Na końcu życia stara wersja zwraca 410 Gone z nagłówkiem Link do przewodnika migracji. VAT 23% i inne pola podatkowe Polska są stabilne w v1 i v2.
Eksploatacja i przypadki brzegowe — Ostatnie zmiany (wycinek)
2026-03-15: dodano partial_ok na zamówieniach, nowe zdarzenie order.partially_shipped. 2026-01-10: dodano id potwierdzenia KSeF w payloadzie faktury. 2025-11-04: klucze idempotency wymagane na POST /v1/orders (breaking; v2). Pełny changelog na /docs/changelog z RSS i Atom. Dodatki schematu Krajowy System e-Faktur (KSeF) są non-breaking w przypiętych wersjach.
FAQ
Jak przypinane są wersje?
Domyślna z konta przy zakładaniu; override per żądanie przez Accept-Version. Testuj nową wersję nagłówkiem zanim zmienisz default.
Jak ogłaszacie zmiany?
Banner w dashboardzie, miesięczny email, nagłówek Sunset na dotkniętych endpointach. Nigdy cichych zmian w przypiętej wersji.
Czy jest RSS?
Tak — /docs/changelog.rss oraz Atom /docs/changelog.atom.
Jak długo wspierane są stare wersje?
Minimum 24 miesiące od wydania następcy; 12-miesięczny preawiz przed EOL.
Zmiany kanału KSeF?
Śledzone w tym samym changelogu. VAT 23% i inne pola podatkowe są stabilne w v1 i v2.