Product Requirements & Technical Overview

1. Document Control

2. Executive Summary

Weblo TTS is a managed connector that links WooCommerce stores to TikTok Shop. Merchants install a WordPress plugin and manage catalog, orders, and after-sales workflows from the WooCommerce admin. OAuth, TikTok Shop API tokens, webhooks, and scheduled synchronisation run on the Weblo cloud platform (tts.weblo.pl).

This design ensures TikTok credentials and OAuth secrets are never stored in WordPress. The plugin communicates with Weblo API using a per-store key pair (store_id + Bearer api_key).

3. Product Goals

• Publish WooCommerce catalog to TikTok Shop with category and attribute mapping aligned to marketplace rules.
• Import TikTok orders into WooCommerce with buyer, line-item, tax, and shipping data.
• Bi-directional inventory synchronisation on stock changes in WooCommerce or TikTok.
• Order fulfillment - push tracking numbers and carriers back to TikTok.
• After-sales: returns, cancellations, address changes, and buyer messaging.
• Settlement and payout visibility inside the admin panel.

4. System Architecture

┌─────────────────────┐     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. Security Model

• OAuth 2.0 with PKCE - seller authorisation via TikTok; redirect URI: https://tts.weblo.pl/oauth/callback.
• TikTok tokens stored and refreshed only on Weblo - not in the WordPress database.
• Plugin → Weblo auth - Authorization: Bearer <api_key> header bound to store_id.
• Webhooks - HMAC-SHA256 signature in X-Weblo-TTS-Signature; store endpoint: /wp-json/weblo-tts/v1/webhook.
• Encryption - TLS 1.2+ for all traffic; optional sync logs in uploads directory (not web-accessible).
• Environment separation - production, staging, and development logically isolated.

6. Onboarding Flow (OAuth)

1. Install and activate the Weblo TTS plugin in WordPress/WooCommerce.
2. Register the store: POST /api/v1/stores/register → receive store_id, api_key, webhook_secret.
3. Admin clicks “Connect TikTok Shop” → redirect to https://tts.weblo.pl/oauth/authorize?store_id=….
4. Weblo initiates TikTok OAuth (PKCE); seller signs in to TikTok Seller Center and accepts scopes.
5. TikTok returns an authorisation code to Weblo callback; Weblo exchanges it for tokens and links store ↔ TikTok Shop.
6. Weblo registers TikTok webhooks and relays events to the store’s WordPress endpoint.
7. Weblo TTS panel shows “Connected” status with TikTok shop ID, region, and webhook URL.

7. Functional Requirements

7.1 Product catalog

• Push Woo products → TikTok (POST /sync/products/push) with title, description, price, images, variants, SKU.
• Pull TikTok statuses and IDs (POST /sync/products/pull).
• Category mapping WooCommerce → TikTok; mandatory attributes per category.
• Activate/deactivate listings (/sync/products/activate, /deactivate).
• Update existing products (/sync/products/update).
• EU compliance fields (manufacturer, responsible person).

7.2 Inventory

• Sync on WooCommerce stock change (woocommerce_product_set_stock hook).
• Batch push (POST /sync/inventory/sync) with SKU / variant mapping.
• tiktok.product webhook for TikTok-side changes.

7.3 Orders

• Pull TikTok orders (POST /sync/orders/pull) - manually or via tiktok.order webhook.
• Import into WooCommerce (/sync/orders/import, /confirm-import) with TikTok metadata (order ID, package ID).
• Woo order metabox with TikTok link, sync status, and fulfillment actions.
• Fulfillment (POST /sync/orders/fulfill) - tracking number + mapped carrier.
• Shipping label download (/sync/fulfillment/shipping-document).

7.4 Returns and cancellations

• Search returns/cancellations (/sync/orders/returns/search, /cancellations/search).
• Approve/reject with rejection reasons (/reject-reasons).
• Webhooks: tiktok.return, tiktok.cancellation, tiktok.address, tiktok.package.

7.5 Mapping and automation

• Map Woo ↔ TikTok order statuses, shipping carriers, and order fields.
• Automation rules: stock/price sync on WooCommerce events.

7.6 Finance

• View statements, payments, and unsettled transactions (/sync/finance/*).

7.7 Buyer messaging

• tiktok.message webhook; send replies (POST /sync/messages/send).

8. Webhooks (TikTok → Weblo → WordPress)

Every request is verified with hash_hmac('sha256', body, webhook_secret) before processing.

9. Weblo API (plugin ↔ platform)

Base URL: https://tts.weblo.pl/api/v1. Main endpoint groups used by plugin v1.18.16:

10. WordPress Plugin Modules

11. Data - Local vs Cloud

12. Non-Functional Requirements

• WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+.
• HTTPS required on the store (webhook + OAuth redirect).
• API timeout: 45 s; cron retry on transient failures.
• HPOS (Custom Order Tables) compatibility declared.
• Multilingual plugin UI (PL default, EN via locale).

13. Test Environment

Detailed testing instructions and demo credentials are provided in the Partner Center verification form.

14. Related Compliance Documentation

• Information Security Policy
• Data Protection and Privacy Policy
• Privacy Policy
• Terms of Service

Document Approval

This document has been approved by the Management Board of TIME4IT Sp. z o.o.

Version: 1.0 · Approval date: 22 June 2026

Contact

For questions regarding this document, integration, or technical support: