Automatyczne bramki
axe-core, proporcje kontrastu, kolejność nagłówków, struktura landmarków i wielkość celów dotykowych uruchamiają się przy każdym pull requeście. Regresja nie może zostać zmergowana.
Siedem warstw, każda wymienialna niezależnie.
Platformy handlowe padają na stykach: silnik faktur nie widzi zamówienia, CDN nie widzi koszyka, a poprawka dostępności nigdy nie trafia do merge'a. SwiftShop definiuje kontrakt na każdej warstwie, więc każdą można wymienić bez przepisywania całości.
Warstwy
Co robi każda warstwa i dlaczego da się ją oddzielić
| Warstwa | Odpowiedzialność | Interfejs | Można zastąpić |
|---|---|---|---|
| Sklep na edge | Renderuje strony produktu, kategorii i koszyka na brzegu sieci; na stronie produktu nie wysyła blokującego JavaScriptu. | HTML + cache HTTP | Dowolnym frameworkiem; kontrakt HTML jest stabilny. |
| Brama agentowa | Publikuje katalog przez MCP, a koszyk przez ACP; egzekwuje politykę i limity wydatków per agent. | MCP + ACP/REST | Innym hostem agentowym, jeśli wersja specyfikacji się zgadza. |
| Rdzeń handlowy | Koszyki, reguły cenowe, promocje, rezerwacje stanów, cykl życia zamówienia. | REST + webhooki | Dowolnym OMS-em; koperta webhooków jest wersjonowana. |
| Silnik faktur | Buduje XML FA(3), uwierzytelnia się w KSeF 2.0, śledzi UPO, obsługuje tryb offline24 i korekty. | API KSeF 2.0 | Twoim systemem księgowym, przez ten sam kanał KSeF. |
| Płatności | BLIK, BLIK Płacę Później, pay-by-link, karty, portfele, pobranie, płatności dzielone, zwroty. | REST PSP | Dowolnym operatorem obsługującym BLIKA i tokenizowane karty. |
| Logistyka | Wybór automatu i kuriera, etykiety, webhooki śledzenia, zwroty, rozliczenie pobrania. | REST przewoźnika | Dowolnym przewoźnikiem na polskim rynku. |
| Zgodność | Bramki dostępności, pola GPSR, prezentacja historii cen z Omnibus, notice-and-action z DSA. | Sprawdzenia w buildzie i runtime | Niczym — ta warstwa jest obowiązkowa z mocy prawa. |
Brama agentowa
Co agent faktycznie robi w Twoim sklepie
Nie widżet czatu. Realna, uwierzytelniona i ograniczona polityką kontrahent, który potrafi domknąć zakup i przekazać Ci potwierdzone zamówienie.
Klient → agent
Znajdź mi kurtkę przeciwdeszczową, rozmiar L, do 400 zł, dostawa do Paczkomatu w Warszawie do piątku.
Agent → MCP SwiftShop
catalogue.search({ q: "kurtka przeciwdeszczowa", size: "L", price_max: 400, delivery_before: "2027-03-12", fulfillment: "locker" })
MCP SwiftShop
3 wyniki. Każdy niesie ustrukturyzowaną cenę, stan magazynowy, deklaracje bezpieczeństwa GPSR, najniższą cenę z 30 dni (Omnibus) oraz dostępność automatów z obietnicą dostawy policzoną wobec sieci InPost.
Agent → ACP SwiftShop
checkout.create({ items: [...], fulfillment: { method: "paczkomat", point_id: "WAW831M" }, payment_handler: "blik" })
ACP SwiftShop
Zwracana jest sesja checkoutu z kwotą, rozbiciem podatków i tokenem płatniczym ograniczonym do agenta. Klient zatwierdza w swojej aplikacji bankowej. Sprzedawca nigdy nie przekazuje danych płatniczych agentowi.
Sprzedawca
Zamówienie trafia do tej samej kolejki co każde inne. Faktura FA(3) jest już przesłana do KSeF. Etykieta jest już wydrukowana.
Koszyk — sesja agenta ss_9f2c
Kurtka Shell RC-01
rozmiar L · czarny373,98 zł
rozmiar L · czarny373,98 zł
Wysyłka — Paczkomat
WAW831M · obietnica 11.030,00 zł
WAW831M · obietnica 11.030,00 zł
Rabat — historia cen
najniższa z 30 dni: 419,00 zł−45,02 zł
najniższa z 30 dni: 419,00 zł−45,02 zł
// GET /.well-known/acp.json
{
"spec_version": "1.0",
"merchant": {
"name": "SwiftShop.pl",
"id": "pl-swiftshop",
"country": "PL",
"merchant_of_record": true
},
"endpoints": {
"catalogue": "/mcp",
"checkout": "/acp/v1/checkout_sessions",
"orders": "/acp/v1/orders",
"webhooks": "/acp/v1/webhooks"
},
"capabilities": [
"agentic_checkout",
"cart",
"delegate_payment",
"delegate_authentication",
"order_webhooks"
],
"payment_handlers": ["blik", "blik_pay_later", "card_token"],
"fulfillment": ["paczkomat", "kurier", "odbior_osobisty", "same_day_warszawa"],
"policy": {
"require_human_approval_above_pln": 2000,
"allowed_agents": ["chatgpt", "*"],
"refund_window_days": 14
}
}Silnik faktur
Natywnie w KSeF, nie obok KSeF
Fakturowanie to miejsce, w którym większość platform wręcza Ci CSV i życzy powodzenia. Od 1 kwietnia 2026 r. każdy polski przedsiębiorca wystawia faktury ustrukturyzowane w KSeF, a odbieranie przez system jest obowiązkowe od 1 lutego 2026 r.[1]
Zamówienie staje się szkicem faktury
Pozycje, stawki VAT, koszt dostawy i rabaty są mapowane na strukturę FA(3) w momencie potwierdzenia płatności. Nic nie jest przepisywane ręcznie. Rabaty z koszyka wędrują z pozycjami, które je wypracowały — właśnie dlatego późniejsza korekta jest czysta.
Przesłanie online z realnym planem B
W trybie online fakturę uznaje się za wystawioną w dniu przesłania do KSeF.[2] Jeśli system nie działa, tryb offline24 pozwala wystawić teraz i dosłać najpóźniej następnego dnia roboczego, z dwoma wymaganymi kodami QR na wizualizacji.
UPO i wizualizacja obsłużone
Przechowujemy UPO, udostępniamy numer KSeF i generujemy PDF z kodem QR na wypadki, gdy prawo nadal wymaga wręczenia dokumentu — kontrahenci zagraniczni, konsumenci, scenariusze offline.
Korekty, które nie psują ksiąg
Częściowy zwrot, rabat z dobrej woli i błędny NIP nabywcy mają różne prawidłowe sposoby ujęcia. Silnik wybiera właściwy, wiąże korektę z fakturami pierwotnymi i nie pozwala po cichu popełnić błędu, którego nie da się naprawić.
POST /internal/invoice-jobs HTTP/1.1
Content-Type: application/json
{
"order_id": "SS-2027-0000193842",
"issued_to": { "type": "nip", "value": "5252955037" },
"schema": "FA(3)",
"mode": "online", // fallback: "offline24"
"lines": [
{ "sku": "RC-SHELL-01-L", "qty": 1, "net": 373.98, "vat": "23" },
{ "sku": "SHIP-LOCKER", "qty": 1, "net": 0.00, "vat": "23" }
],
"payment": { "method": "blik", "paid_at": "2027-03-09T14:02:11Z" },
"deliver_to": { "locker_id": "WAW831M", "promise": "2027-03-11" },
"on_success": {
"store": ["ksef_number", "upo"],
"render": ["qr_pdf", "customer_email"]
}
}Silnik dostępności
Wydanie nie przejdzie, jeśli spadnie kontrast
Wymagania dostępności dla e-handlu obowiązują w Polsce od 28 czerwca 2025 r., organem nadzoru jest Minister Cyfryzacji, a kary sięgają 10% obrotu.[3][4]
Scenariusze testów manualnych
Każdy komponent ma zapisany scenariusz zdany/niezdany dla pułapek fokusu, komunikacji czytnika ekranu, kolejności fokusu i obsługi błędów — tego, czego automaty nie ocenią.
Oświadczenie i obsługa skarg
Ustawowe oświadczenie o dostępności generuje się z żywej konfiguracji, a przyjmowanie skarg jest spięte z zegarem 30 dni.[4]
Wielojęzyczność domyślnie
Twierdzenia o dostępności są per język. Angielski interfejs, który ignoruje polską wymowę w czytniku ekranu, nie jest dostępny w Polsce.
Dalej
Zobacz cennik albo protokół dla agentów
Dwie drogi w głąb
Warunki handlowe publikujemy w całości. Podobnie jak interfejs agentowy, który prosimy wdrażać naszych maszynowych kontrahentów.
Źródła cytowane na tej stronie
Każda z powyższych wartości pochodzi ze źródeł wymienionych poniżej. Rejestr czytelny dla maszyn znajduje się pod /data/market-data.json.
- Ministerstwo Finansów / Krajowa Administracja Skarbowa. Zakres obowiązkowego KSeF (KSeF 2.0) —
- Ministerstwo Finansów. Etapy wdrożenia KSeF 2.0 — mapa drogowa —
- gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji). Polski Akt o Dostępności — usługi handlu elektronicznego —
- Dziennik Ustaw RP. Ustawa z dnia 26 kwietnia 2024 r. o zapewnianiu spełniania wymagań dostępności niektórych produktów i usług przez podmioty gospodarcze (Dz.U. 2024 poz. 731) —