Wymagania produktu i przegląd techniczny

1. Informacje o dokumencie

2. Streszczenie

Weblo TTS to integracja typu managed connector, która łączy sklep WooCommerce z TikTok Shop. Sprzedawca instaluje wtyczkę WordPress i zarządza katalogiem, zamówieniami oraz obsługą posprzedażową z poziomu panelu WooCommerce. Operacje wymagające OAuth, tokenów TikTok Shop API, webhooków i harmonogramów synchronizacji wykonuje platforma chmurowa Weblo (tts.weblo.pl).

Model eliminuje przechowywanie haseł TikTok i sekretów OAuth w WordPress - wtyczka komunikuje się wyłącznie z Weblo API przy użyciu klucza sklepu (store_id + Bearer api_key).

3. Cele produktu

• Udostępnienie katalogu WooCommerce na TikTok Shop z mapowaniem kategorii i atrybutów zgodnym z wymaganiami marketplace.
• Import zamówień TikTok do WooCommerce z pełnymi danymi kupującego, pozycji, podatków i dostawy.
• Bi-directional synchronizacja stanów magazynowych po zmianie w WooCommerce lub TikTok.
• Realizacja zamówień (fulfillment) - przekazywanie numerów śledzenia i przewoźników do TikTok.
• Obsługa zwrotów, anulowań, zmian adresu i wiadomości kupujących.
• Widoczność rozliczeń i wypłat TikTok Shop w panelu administracyjnym.

4. Architektura systemu

┌─────────────────────┐     HTTPS REST      ┌──────────────────────┐     TikTok Shop API     ┌─────────────────┐
│  WooCommerce Store  │ ◄──────────────────► │  Weblo API Platform  │ ◄──────────────────────► │  TikTok Shop    │
│  (WordPress + WC)   │   Bearer api_key     │  tts.weblo.pl        │   OAuth 2.0 / PKCE      │  (Seller Center)│
│                     │                      │                      │   Access & refresh tok. │
│  Weblo TTS Plugin   │ ◄── HMAC webhook ─── │  Webhook relay       │ ◄──── TikTok webhooks ──│                 │
└─────────────────────┘   POST /webhook      └──────────────────────┘                         └─────────────────┘

5. Model bezpieczeństwa

• OAuth 2.0 z PKCE - autoryzacja sprzedawcy przez TikTok; redirect URI: https://tts.weblo.pl/oauth/callback.
• Tokeny TikTok przechowywane i odświeżane wyłącznie po stronie Weblo - nie w bazie WordPress.
• Autoryzacja plugin → Weblo - nagłówek Authorization: Bearer <api_key> powiązany ze store_id.
• Webhooki - podpis HMAC-SHA256 w nagłówku X-Weblo-TTS-Signature; endpoint sklepu: /wp-json/weblo-tts/v1/webhook.
• Szyfrowanie - TLS 1.2+ dla całego ruchu; logi sync opcjonalnie w katalogu uploads (poza WWW).
• Separacja środowisk - produkcja, staging i development logicznie odseparowane.

6. Przepływ onboardingu (OAuth)

1. Instalacja i aktywacja wtyczki Weblo TTS w WordPress/WooCommerce.
2. Rejestracja sklepu: POST /api/v1/stores/register → otrzymanie store_id, api_key, webhook_secret.
3. Administrator klika „Połącz z TikTok Shop” → przekierowanie na https://tts.weblo.pl/oauth/authorize?store_id=….
4. Weblo inicjuje OAuth TikTok (PKCE); sprzedawca loguje się w TikTok Seller Center i akceptuje scope’y.
5. TikTok zwraca kod autoryzacji na callback Weblo; Weblo wymienia kod na tokeny i zapisuje powiązanie sklep ↔ TikTok Shop.
6. Weblo rejestruje webhooki TikTok i przekazuje zdarzenia do endpointu WordPress sklepu.
7. Panel Weblo TTS pokazuje status „Połączono” wraz z ID sklepu TikTok, regionem i URL webhooka.

7. Wymagania funkcjonalne

7.1 Katalog produktów

• Push produktów Woo → TikTok (POST /sync/products/push) z tytułem, opisem, ceną, zdjęciami, wariantami, SKU.
• Pull statusów i ID TikTok (POST /sync/products/pull).
• Mapowanie kategorii WooCommerce → kategorie TikTok; atrybuty obowiązkowe per kategoria.
• Aktywacja/deaktywacja listingów (/sync/products/activate, /deactivate).
• Aktualizacja istniejących produktów (/sync/products/update).
• Obsługa wymogów compliance UE (producent, osoba odpowiedzialna).

7.2 Stany magazynowe

• Sync po zmianie stocku w WooCommerce (hook woocommerce_product_set_stock).
• Push batch (POST /sync/inventory/sync) z mapowaniem SKU / wariantów.
• Webhook tiktok.product dla zmian po stronie TikTok.

7.3 Zamówienia

• Pull zamówień TikTok (POST /sync/orders/pull) - ręcznie lub przez webhook tiktok.order.
• Import do WooCommerce (/sync/orders/import, /confirm-import) z metadanymi TikTok (order ID, package ID).
• Metabox zamówienia Woo z linkiem do TikTok, statusem sync i akcjami fulfillment.
• Fulfillment (POST /sync/orders/fulfill) - numer śledzenia + przewoźnik z mapowania.
• Pobieranie etykiet wysyłkowych (/sync/fulfillment/shipping-document).

7.4 Zwroty i anulowania

• Wyszukiwanie zwrotów/anulowań (/sync/orders/returns/search, /cancellations/search).
• Approve/reject z powodami odrzucenia (/reject-reasons).
• Webhooki: tiktok.return, tiktok.cancellation, tiktok.address, tiktok.package.

7.5 Mapowanie i automatyzacja

• Mapowanie statusów Woo ↔ TikTok, przewoźników wysyłki, pól zamówienia.
• Reguły automatyczne: sync stanów/cen po zdarzeniach WooCommerce.

7.6 Finanse

• Podgląd zestawień, wypłat i nierozliczonych transakcji (/sync/finance/*).

7.7 Wiadomości kupujących

• Webhook tiktok.message; wysyłka odpowiedzi (POST /sync/messages/send).

8. Webhooki (TikTok → Weblo → WordPress)

Każdy request jest weryfikowany przez hash_hmac('sha256', body, webhook_secret) przed przetworzeniem.

9. API Weblo (wtyczka ↔ platforma)

Base URL: https://tts.weblo.pl/api/v1. Poniżej główne grupy endpointów używane przez wtyczkę v1.18.16:

10. Moduły wtyczki WordPress

11. Dane - lokalnie vs chmura

12. Wymagania niefunkcjonalne

• WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+.
• HTTPS obowiązkowy na sklepie (webhook + OAuth redirect).
• Timeout API: 45 s; retry przez cron przy błędach przejściowych.
• Obsługa HPOS (Custom Order Tables) - deklaracja kompatybilności WooCommerce.
• Wielojęzyczny UI wtyczki (PL domyślnie, EN przez locale).

13. Środowisko testowe

Szczegółowe instrukcje testowe i konto demo udostępniane są w formularzu weryfikacji Partner Center.

14. Powiązana dokumentacja compliance

• Polityka bezpieczeństwa informacji
• Polityka ochrony danych
• Polityka prywatności
• Regulamin usługi

Zatwierdzenie dokumentu

Dokument zatwierdzony przez Zarząd TIME4IT Sp. z o.o.

Wersja: 1.0 · Data zatwierdzenia: 22 czerwca 2026

Kontakt

W sprawach dotyczących tego dokumentu, integracji lub wsparcia technicznego: