WordPress API-first: łączenie WordPressa ze wszystkim w 2026

Dla firm WordPress jest często centrum treści: strona, aplikacja mobilna, intranet, sklep. Żeby ten układ trzymał się kupy, zespół wychodzi poza wp_head() i the_content() i składa orkiestrację headless. W Polsce ta orkiestracja ma drugi kontrakt, którego katalog nie pokrywa: kto wystawia fakturę, kto podpisuje powiadomienie Przelewy24 albo BLIK, gdzie leżą sekrety pod RODO.

Kolejki, idempotencja i uzgodnienie z ERP są w przewodniku architektury integracji WooCommerce z ERP 2026. Tutaj wchodzi przecięcie API: mapa tras REST, cutover webhooków i okno podwójnego zapisu, plus granica, na której WooCommerce nie nadaje numeru KSeF.

Usługi headless WordPress opisują, kiedy frontend w Astro 7 ma sens. Ten tekst zostaje przy kontrakcie API.

#1. Czym jest API-First WordPress?

Klasyczny rozwój zaczyna się od makiety i motywu. Rozwój API-first zaczyna się od własnych typów danych i punktów końcowych. Ten porządek zmienia skalowanie, podział pracy i to, co w ogóle wolno zapisać z poziomu sklepu.

#Kontrakt danych

Określasz, jak dane (wpisy, produkty, użytkownicy, zamówienia) są ułożone i wystawione. Kontrakt jest bazą, na której stoją frontend, aplikacja i integracje. W projekcie polskim kontrakt deklaruje też, czego WordPress nie emituje: numeru KSeF, własnej serii faktury, kodu JPK. Te wartości wracają od certyfikowanego wystawcy i lądują jako niezmienne metadane zamówienia.

Przykład kontraktu odczytu katalogu:

{
  "endpoint": "/wp-json/v1/products",
  "method": "GET",
  "response": {
    "id": "integer",
    "name": "string (max: 200)",
    "price": "float (2 decimals)",
    "currency": "string (ISO 4217)",
    "categories": "array<string>",
    "availability": "enum: in_stock|out_of_stock|preorder",
    "nip_required": "boolean",
    "metadata": {
      "seo_title": "string (max: 60)",
      "seo_description": "string (max: 160)"
    }
  }
}

NIP przy kasie, pobrany z GUS, jest daną wejściową dla wystawcy. Nie jest numerem faktury. Kontrakt, który miesza te dwa pola, psuje uzgodnienie z JPK_V7M, bo księgowość szuka dokumentu po identyfikatorze KSeF, a sklep pokazuje NIP nabywcy.

#Niezależność frontendu

Gdy API stoi, zespół Astro 7, zespół aplikacji mobilnej i zespół SEO pracują równolegle na tym samym źródle. Nie czekają, aż motyw dorysuje kolejny szablon.

Równoległe odczyty z jednego kontraktu:

• Frontend WWW: Astro 7 albo Next.js czyta treść i katalog.
• Aplikacja mobilna: te same endpointy w Flutter albo React Native.
• Marketing: segmentacja i zdarzenia po API, nie przez skrobanie HTML.
• SEO: schema i sitemapa z tego samego JSON, który widzi frontend.
• Integracje: CRM, ERP, bramka, kurier. Każda po własnej, wąskiej trasie.

Aplikacja nie dostaje w binarium klucza ck_ z uprawnieniem write. Ten klucz rusza stany magazynowe i zwroty. Aplikacja dostaje Application Password albo token OAuth użytkownika z odczytem. Checkout zalogowany idzie przez origin PHP.

#2. Opanowanie niestandardowych punktów końcowych REST API

Domyślne REST WordPressa pokrywa odczyt treści. Projekty z katalogiem, magazynem i kasą potrzebują własnej logiki, która zbiera zapytania i zamyka pola, których bot magazynu nie powinien ruszać. REST API WooCommerce na /wp-json/wc/v3/ obsługuje produkty, zamówienia i kupony. Stan z Comarch Optima, Subiekta nexo PRO albo enova365 nie powinien iść zwykłym PUT na produkt: jedno pole za dużo (cena, tytuł, klasa podatku) nadpisuje się po cichu.

#Izolacja logiki biznesowej

Zamiast dziesięciu zapytań po historię zakupów użytkownika budujemy jeden endpoint wp-json/v1/user-commerce, który zwraca jeden obiekt JSON.

add_action('rest_api_init', function () {
    register_rest_route('v1', '/user-commerce/(?P<id>\\d+)', [
        'methods'             => 'GET',
        'callback'            => 'get_user_commerce_data',
        'permission_callback' => 'verify_api_token',
        'args'                => [
            'id' => [
                'validate_callback' => static function ($param) {
                    return is_numeric($param);
                },
            ],
        ],
    ]);
});

function get_user_commerce_data($request) {
    $user_id = (int) $request['id'];

    return [
        'orders'           => get_user_orders($user_id),
        'subscriptions'    => get_user_subscriptions($user_id),
        'loyalty_points'   => get_user_loyalty($user_id),
        'ksef_documents'   => get_user_ksef_refs($user_id),
    ];
}

ksef_documents to referencje (numer KSeF, data przyjęcia), nie PDF z treścią faktury w każdym wierszu listy. PDF bierzesz od wystawcy, gdy użytkownik otwiera dokument.

#Wąskie trasy REST dla magazynu

ERP jest źródłem prawdy o stanie. WooCommerce aplikuje deltę. Wąska trasa (sku, qty, warehouse, event_id) z permission_callback podpiętym pod klucz zapisu WooCommerce, nie pod administratora, nie pozwala tokenowi redakcyjnemu ruszać magazynu.

add_action('rest_api_init', function () {
    register_rest_route('wc-erp/v1', '/stock', [
        'methods'             => 'POST',
        'callback'            => 'wpp_apply_stock_delta',
        'permission_callback' => 'wpp_verify_wc_write_key',
        'args'                => [
            'sku'      => ['required' => true, 'type' => 'string'],
            'qty'      => ['required' => true, 'type' => 'integer'],
            'event_id' => ['required' => true, 'type' => 'string'],
        ],
    ]);
});

event_id jest kluczem idempotencji. Gdy Optima albo Subiekt ponowią ten sam ruch, trasa oddaje zapamiętany wynik i nie odejmuje drugi raz. Wzorce kolejek i blokad są w przewodniku architektury WooCommerce ERP. Tu wystarczy nie otwierać /wc/v3/products/<id> botowi magazynu.

#Application Passwords kontra klucze API WooCommerce

WordPress i WooCommerce uwierzytelniają dwa światy. Nie mieszaj ich. Application Passwords żyją przy użytkowniku WordPressa, są hashowane w usermeta i dziedziczą jego uprawnienia: redaktor, aplikacja mobilna, skrypt na /wp-json/wp/v2/. Klucze REST WooCommerce (ck_ / cs_) żyją w woocommerce_api_keys, z prawem read, write albo read_write, i uwierzytelniają /wp-json/wc/v3/. ERP magazynu dostaje klucz write katalogu. Front headless dostaje read. Nigdy Application Password administratora w binarium aplikacji. Rotacja klucza WooCommerce nie wylogowuje redakcji. Rotacja Application Password nie tnie synchronizacji magazynu.

#Walidacja i sanityzacja

register_rest_route wymusza walidację wejścia, zanim callback cokolwiek zapisze.

Warstwy, których nie pomijamy:

1. Typ: każdy parametr ma oczekiwany typ.
2. Zakres: liczby mają min i max.
3. Format: stringi idą przez wzorzec (SKU, NIP, event_id).
4. Sanityzacja: wejście czyścisz przed zapisem, nie po.
5. Autoryzacja: każde żądanie sprawdza token, nie „czy user jest zalogowany w wp-admin”.

NIP walidujesz sumą kontrolną i, gdy trzeba, zapytaniem do GUS. Nie wklejasz go w pole numeru faktury. Numer faktury wraca z KSeF.

#KSeF i JPK_V7M na granicy REST WordPressa i WooCommerce

W Polsce certyfikowany wystawca (KSeF przez ERP albo biuro rachunkowe) jest właścicielem identyfikatora faktury. WooCommerce REST tego numeru nie nadaje.

To odwraca zwykły kierunek integracji API-first. W katalogu ERP pisze, sklep pokazuje. W fakturze polski wystawca wysyła strukturę do Krajowego Systemu e-Faktur, system nadaje numer, wystawca oddaje ten numer sklepowi. Sklep jest źródłem zamówienia. Nie jest źródłem numeru.

Jeśli WooCommerce w woocommerce_new_order skleja serię w stylu WC-2026-00412 i woła to fakturą, WordPress staje się wystawcą. Dziedziczy wtedy obowiązki, których REST sklepu nie uniesie: niezmienność dokumentu, korekta jako nowy dokument, ujęcie w JPK. DELETE zamówienia nie anuluje faktury w KSeF. Anulowanie albo korekta to nowa struktura po stronie wystawcy, z własnym numerem, który znowu wraca do meta zamówienia.

Przepływ, który się broni:

1. Checkout (albo wpis ręczny) tworzy zamówienie WooCommerce. Status to zamiar zakupu, nie dokument księgowy.
2. Po potwierdzonej płatności sklep wysyła zamiar do wystawcy (Comarch Optima, Subiekt nexo PRO, enova365, wFirma, Fakturownia). W payloadzie jest order_id i ten sam event_id, który zobaczy bramka.
3. Wystawca składa strukturę i wysyła ją do KSeF. Numer nadaje system, nie sklep i nie licznik w wp_options.
4. Sklep odczytuje numer i zapisuje go w meta. Ponowiony webhook z tym samym event_id nie tworzy drugiej faktury.

JPK_V7M zamyka obieg i nie jest webhookiem typu wystrzel i zapomnij. Plik powstaje z ksiąg, nie z tabeli zamówień. Każde zamówienie musi mieć drogę powrotną do dokumentu. Jeśli synchronizacja jest tylko ze sklepu do ERP, uzgodnienie miesięczne spada na ręczną pracę, a rozjazd wychodzi po terminie. Pętla odczytu wygląda tak: sklep pyta wystawcę albo ERP o dokumenty z numerem KSeF powiązane z order_id, porównuje kwoty i stawki z zamówieniem, oznacza rozjazd zanim księgowość złoży JPK_V7M. Nocny odczyt nie zastępuje zapisu w chwili wystawienia, ale łapie to, czego webhook nie doniósł: timeout, 409, faktura przyjęta w KSeF przy zamówieniu, które w sklepie wciąż wisi jako „oczekujące”.

BLIK i Przelewy24 są drugą ścieżką zapisu na to samo zamówienie. Bramka potwierdza pobranie. ERP potwierdza fakturę. Jeśli każda strona niesie własny identyfikator, ponowienie z Przelewy24 plus ponowienie z Optimy daje dwie faktury albo zamówienie opłacone bez dokumentu. Klucz idempotencji jest wspólny: order_id + identyfikator transakcji bramki (sessionId / p24_order_id, albo referencja BLIK, gdy BLIK idzie przez PayU, tpay albo Autopay). Callback bramki i callback wystawcy używają tego samego klucza. Drugi, który dojdzie, jest no-op.

Powiadomienie serwer-serwer Przelewy24 (CRC) jest jedyną drogą, która może przesunąć zamówienie na „przetwarzane”. Adres powrotu przeglądarki maluje potwierdzenie. Jeśli frontend Astro 7 ufa query stringowi powrotu, atakujący oznacza zamówienia jako opłacone bez obciążenia. BLIK, gdy jedzie tym samym TPV, dziedziczy tę weryfikację. Sekret CRC nie wychodzi z origin. Nie ma zmiany statusu zamówienia bez poprawnego podpisu.

Webhooki statusu InPost wychodzą ze sklepu. Sklep zleca nadanie, etykietę, punkt paczkomatu. InPost odsyła status przesyłki (nadana, w paczkomacie, odebrana). To logistyka, nie fiskus. Status „dostarczona” nie wystawia faktury w KSeF i nie wolno go podpiąć pod ten sam konsument, który woła wystawcę. Osobna trasa, osobny klucz, zero zapisu do pól fiskalnych. Zwrot przesyłki może później uruchomić korektę po stronie wystawcy. Sama paczka tego nie robi.

Podzielona płatność (MPP) i kody GTU też nie należą do REST sklepu jako wyrocznia. Sklep może przekazać flagę i NIP. Stawkę, GTU i mechanizm potwierdza wystawca, bo to on składa JPK_V7M.

Nie kopiujemy tu tabel kolejek ani konsumenta PHP 8.4 z przewodnika architektury. Kontrakt API-first na polskim sklepie mieści się w jednym zdaniu: KSeF nadaje numer, WooCommerce REST go zapisuje, BLIK albo Przelewy24 i ERP podpisują ten sam event_id, a JPK_V7M wraca odczytem.

#3. WordPress jako usługa (wpaas): Content mesh

W 2026 r. większe firmy składają treść jako siatkę usług. WordPress jest węzłem, nie jedynym systemem.

#Synchronizacja z systemami zewnętrznymi

WordPress nie tylko trzyma treść. Synchronizuje ją. Zmiana produktu w SAP, Comarch XL albo Subiekcie może pchnąć deltę do WordPressa, a stamtąd do sklepu i aplikacji.

[ERP] → webhook → [WordPress API] → webhook → [Frontend Astro 7]
                                 → webhook → [Aplikacja Flutter]
                                 → webhook → [CRM HubSpot / Salesforce]

Gdy przecięcie to migracja sklepu (PrestaShop, Magento albo stary WooCommerce na nowy), praca API schodzi do trzech elementów. To nie jest poradnik Shopify. To mapa kontraktów:

1. Mapa URL. Każda trasa REST i każdy adres powiadomienia Przelewy24 ze źródła ma cel. Bez mapy TPV nadal woła stary serwer, a zamówienia zostają w „oczekiwanie na płatność”.
2. Cutover webhooków. Pauzujesz nadawców, opróżniasz kolejkę, rejestrujesz nowe URL. Osierocony webhook w trakcie cięcia dubluje zamówienia albo gubi stan.
3. Okno podwójnego zapisu. Źródło i cel przyjmują zdarzenia przez ograniczony interwał, z tym samym kluczem idempotencji. Potem źródło zamarza. Wystawca (Optima, Subiekt, wFirma) widzi jeden event_id na operację.

W tym oknie WooCommerce nie „rezerwuje” numerów faktur na starym origin, żeby dokończyć je na nowym. Taka rezerwa rozjeżdża się z numeracją KSeF.

#Webhooki

Haki zdarzeniowe powiadamiają usługi zewnętrzne, gdy wpis idzie na publikację albo użytkownik się rejestruje.

add_action('transition_post_status', function ($new, $old, $post) {
    if ($new === 'publish' && $old !== 'publish') {
        $payload = [
            'event'     => 'content_published',
            'post_id'   => $post->ID,
            'title'     => $post->post_title,
            'url'       => get_permalink($post->ID),
            'timestamp' => current_time('c'),
        ];

        $subscribers = get_webhook_subscribers('content_published');
        foreach ($subscribers as $subscriber) {
            wp_remote_post($subscriber['url'], [
                'body'    => wp_json_encode($payload),
                'headers' => ['Content-Type' => 'application/json'],
                'timeout' => 5,
            ]);
        }
    }
}, 10, 3);

Ten wzorzec nadaje się do treści. Nie nadaje się do faktury. Publikacja wpisu może polecieć best-effort. Zapis numeru KSeF czeka na odpowiedź wystawcy i idzie przez kolejkę z ponowieniem.

#Architektura sterowana zdarzeniami

Integracje punkt-punkt ustępują brokerowi:

• Kolejka: Redis Streams albo RabbitMQ.
• Przetwarzanie w tle: zdarzenie nie blokuje requestu checkoutu.
• Ponowienie: backoff, nie pętla w wp-cron przy obciążonym origin.
• Dead letter: zdarzenia, które padają wielokrotnie, lądują do inspekcji, nie znikają.

Callback Przelewy24 i BLIK nie jest kolejnym webhookiem marketingowym. To druga droga zapisu na to samo zamówienie. Jeśli broker i TPV nie dzielą klucza idempotencji, ERP wystawia dwie faktury albo żadnej.

Zdarzenie „płatność potwierdzona”, które zjada Mautic albo HubSpot, wychodzi po weryfikacji CRC bramki, nie z powrotu przeglądarki. Lead „płatny klient” odpalony z URL sukcesu to klasyczny fałszywy plus.

#4. Wydajność headless i warstwa API

Historyczny zarzut wobec API WordPressa to czas odpowiedzi. W 2026 r. ratuje to wielowarstwowy cache, z twardym wyjątkiem: trasy płatności i fiskusa nie idą do cache.

#Object Caching (Redis)

Odpowiedzi API trzymamy w pamięci, żeby nie powtarzać ciężkiego SQL. Każdy endpoint ma własny TTL zależny od tego, jak szybko dane się starzeją. Endpointy powiadomienia płatności i rejestracji fiskalnej mają TTL zero: stary 200 z już sprawdzonym HMAC nie może zostać odtworzony.

#Edge caching

Cloudflare trzyma JSON na krawędzi. Listing produktów idzie z PoP blisko czytelnika, nie z origin PHP. Trasy uwierzytelnione, żywy stan magazynu i callbacki TPV wypadają z edge i idą na origin.

function add_api_cache_headers($response) {
    if (is_wp_error($response)) {
        return $response;
    }

    $response->header('Cache-Control', 'public, max-age=300, stale-while-revalidate=60');
    $response->header('CDN-Cache-Control', 'max-age=600');
    $response->header('Surrogate-Control', 'max-age=3600');

    return $response;
}
add_filter('rest_post_dispatch', 'add_api_cache_headers');

Tego filtra nie nakładasz na wc-erp/v1 ani na URL powiadomienia Przelewy24. Cache-Control: public na callbacku płatności to incydent, nie optymalizacja.

#GraphQL jako uzupełnienie odczytu

Do złożonych odczytów GraphQL przez WPGraphQL obcina over-fetching:

query ProductPage {
  product(id: "123") {
    title
    price
    description
    categories {
      name
      slug
    }
    relatedProducts(first: 3) {
      title
      thumbnail
    }
  }
}

Jedno zapytanie GraphQL zastępuje kilka osobnych wywołań REST. GraphQL nie zastępuje tras zapisu magazynu ani webhooka TPV. Te mutacje zostają na wąskim REST. Numeru KSeF też nie pytasz GraphQLem „na wszelki wypadek” w listingu. Referencja fiskalna jest w szczegółach zamówienia, po stronie wystawcy.

Origin PHP skalujesz do wolumenu redakcji i wolumenu zamówień, nie do anonimowego ruchu katalogu. Katalog może siedzieć na edge. Kasa, magazyn i KSeF nie.

#5. Bezpieczeństwo w otwartym świecie API

Otwarcie WordPressa przez API wymaga minimum uprawnień. Każdy wystawiony endpoint to powierzchnia ataku. W Polsce przechowywanie tych tokenów to przetwarzanie danych pod RODO. UODO nie rozróżnia „to tylko klucz API” od sekretu, który otwiera zamówienia i adresy.

#Tokeny z zakresem

Dajesz najmniej, ile trasa potrzebuje. Skrypt analityczny czyta. Synchronizacja CRM aktualizuje rekordy. Bot magazynu pisze deltę stanu. Żaden z nich nie dostaje roli administratora.

Application Passwords nie lądują w wp_options jawnym tekstem i nie idą do repozytorium. Klucze ck_ / cs_ szyfrujesz w spoczynku i rotujesz, gdy ktoś schodzi z projektu. Art. 32 RODO (bezpieczeństwo przetwarzania) dotyczy tego magazynu. Art. 33 każe zgłosić naruszenie organowi w 72 godziny, jeśli wyciek obejmuje dane osobowe. Zrzut kluczy REST z dostępem do zamówień jest naruszeniem.

#Rate limiting

Żeby obciąć nadużycia, stawiasz limit na poziomie serwera. 60 żądań na minutę na IP to punkt startowy, nie dana rynkowa.

function api_rate_limit($result) {
    $ip  = $_SERVER['REMOTE_ADDR'] ?? '';
    $key = 'rate_limit_' . md5($ip);
    $count = (int) get_transient($key);

    if ($count > 60) {
        return new WP_Error(
            'rate_limited',
            'Za dużo żądań. Spróbuj ponownie za 60 sekund.',
            ['status' => 429]
        );
    }

    set_transient($key, $count + 1, 60);
    return $result;
}
add_filter('rest_pre_dispatch', 'api_rate_limit');

Transients nie wystarczą przy kilku instancjach PHP. W produkcji licznik żyje w Redis, a IP powiadomień Przelewy24, PayU i tpay wypadasz z limitu: 429 do TPV zostawia zamówienie opłacone w banku i wiszące w WooCommerce.

#HMAC Przelewy24 i BLIK

Przelewy24 podpisuje powiadomienie CRC z kluczem sprzedawcy. Porównanie idzie w stałym czasie (hash_equals). BLIK na tym samym TPV dziedziczy tę weryfikację. Gdy BLIK idzie przez PayU albo Autopay, sprawdzasz podpis tej bramki, nie „czy w query jest status=OK”. Sekret nie wychodzi z origin. Headless front nie rozstrzyga, czy zamówienie jest opłacone.

Odczyt KSeF (pobranie numeru, sprawdzenie statusu przyjęcia) też nie wisi na publicznym REST bez klucza. To nie jest treść do CDN.

#Pozostałe twarde reguły

• CORS: tylko domeny, które mają czytać API.
• TLS: HTTPS na każdej rozmowie API, w tym webhookach wychodzących do InPost i do wystawcy.
• Dziennik dostępu: każde żądanie zapisu zostawia ślad. IP haszujesz, jeśli log wychodzi poza EOG.
• Rotacja: Application Passwords i klucze WooCommerce rotujesz przy odejściu osoby, nie „kiedy ktoś sobie przypomni”.
• Oddzielne sekrety: CRC Przelewy24, token InPost, klucz ERP i Application Password redakcji to cztery sekrety. Kompromitacja motywu nie może dać wszystkich czterech.

#6. Dlaczego wppoland to twój partner w API-First

W WPPoland składamy hydraulikę, która trzyma kontrakt REST, gdy do sklepu wejdzie ERP, bramka i KSeF.

1. Własne endpointy. Wąskie trasy magazynu i odczytu, nie otwarty PUT na cały produkt. Dokumentacja i testy przy kontrakcie.
2. Integracje systemowe. WordPress z ERP (SAP, Comarch Optima i XL, Subiekt nexo, enova365, Dynamics), CRM (HubSpot, Salesforce) i własnymi bazami. HMAC, idempotencja, kierunek zapisu, w którym KSeF nadaje numer. Zakres handlowy jest w integracjach WooCommerce z ERP.
3. Konsulting headless. Czy API-first ma sens w tym projekcie, i jak przejść, gdy frontend ma spaść na Astro 7 w usłudze headless.
4. Obserwowalność. Dostępność i błędy tras krytycznych, w tym callbacków TPV i odczytu numeru z KSeF. Ceny są indywidualne, po zakresie.

Jeśli REST sklepu nadal produkuje numery faktur, napisz przez kontakt.

#7. Podsumowanie: hub nowoczesnej sieci

WordPress 7.1 na PHP 8.4 unosi kontrakt API-first, gdy trasy są wąskie, a bramka dzieli idempotencję z ERP. Frontend w Astro 7 czyta katalog z edge. Magazyn przyjmuje deltę. KSeF nadaje numer. JPK_V7M wraca odczytem. InPost mówi o paczce, nie o fakturze.

Dane uwięzione w klasycznym motywie otwierasz od kontraktu, nie od kolejnego szablonu. Szczegóły kolejek zostaw przewodnikowi architektury ERP. Tu kończy się mapa API.

Rozwój backendu i treść: usługi WordPress. Pytanie o granicę REST i KSeF: kontakt.