---
title: "Platforma — architektura handlowa SwiftShop.pl"
description: "Architektura SwiftShop.pl: sklep renderowany na edge, brama agentowa ACP i MCP, silnik faktur FA(3) w KSeF, integracje BLIK i InPost oraz wymuszanie dostępności na etapie budowania."
lang: pl
url: https://swiftshop.pl/pl/platforma/
markdown_url: https://swiftshop.pl/pl/platforma/index.md
section: platform
updated: 2026-10-10
sources:
  - id: ksef_scope
    org: "Ministerstwo Finansów / Krajowa Administracja Skarbowa"
    url: https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/
    date: 2025-06-30
  - id: ksef_roadmap
    org: "Ministerstwo Finansów"
    url: https://ksef.podatki.gov.pl/etapy-wdrozenia-ksef/
    date: 2025-10-08
  - id: pad_ecommerce
    org: "gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji)"
    url: https://www.gov.pl/web/dostepnosc-cyfrowa/polski-akt-o-dostepnosci--uslugi-handlu-elektronicznego
    date: 2025-06-27
  - id: pad_act
    org: "Dziennik Ustaw RP"
    url: https://eli.gov.pl/api/acts/DU/2024/731/text/O/D20240731.pdf
    date: 2024-05-15
---

# 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.

## Co robi każda warstwa i dlaczego da się ją oddzielić

**Warstwy platformy SwiftShop**

| 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. |

*Interfejsy to HTTP/JSON oraz MCP. Żadna warstwa nie trzyma prywatnego schematu, którego potrzebowałaby inna.*

## 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.

```json
// 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
  }
}
```

## 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]

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.
2. **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.
3. **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.
4. **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ć.

```http
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"]
  }
}
```

## 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]

### 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.

### 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.

> **Note:** Świadomy kompromis. Wymuszanie dostępności w CI spowalnia część wdrożeń. Postanowiliśmy ponieść ten koszt i go udokumentować, zamiast wystawiać sprzedawcom fakturę za doposażenie później.

## 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.

- Planowany cennik: /pl/cennik/
- Interfejs dla agentów i LLM: /pl/agenci-ai/

## Sources

1. Ministerstwo Finansów / Krajowa Administracja Skarbowa. [Zakres obowiązkowego KSeF (KSeF 2.0)](https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/) — 2025-06-30
2. Ministerstwo Finansów. [Etapy wdrożenia KSeF 2.0 — mapa drogowa](https://ksef.podatki.gov.pl/etapy-wdrozenia-ksef/) — 2025-10-08
3. gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji). [Polski Akt o Dostępności — usługi handlu elektronicznego](https://www.gov.pl/web/dostepnosc-cyfrowa/polski-akt-o-dostepnosci--uslugi-handlu-elektronicznego) — 2025-06-27
4. 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)](https://eli.gov.pl/api/acts/DU/2024/731/text/O/D20240731.pdf) — 2024-05-15