Boss of Toys × WooCommerce

Czym jest ten system?

System Boss of Toys × WooCommerce to kompleksowa integracja łącząca trzy platformy handlowe w jeden zautomatyzowany potok — od produktu w hurtowni, przez sklep i marketplace, aż po dostawę do klienta.

Architektura ogólna

KLIENCI
  │
  ├─ Sklep WooCommerce (OVH) ─── klient składa zamówienie
  ├─ Allegro (marketplace) ────── kupujący składa zamówienie
  └─ Empik (marketplace) ──────── kupujący składa zamówienie
         │
         ▼
┌──────────────────────────────────────────────────────┐
│           WordPress (OVH) — Plugin BossOfToys        │
│                                                      │
│  Dashboard    Ustawienia    Harmonogram              │
│  Etykiety     InPost Sizes  Geowidget                │
│  Fakturownia  Allegro Panel Logi                     │
└─────────────────┬────────────────────────────────────┘
                  │ HTTPS  (X-API-Key)
                  ▼
┌──────────────────────────────────────────────────────┐
│        VPS — Python FastAPI (port 8000)              │
│                                                      │
│  /api/jobs/*     /api/config/*    /api/labels/*      │
│  /api/allegro/*  /api/sse/*       /api/stats/*       │
│  /api/metrics    /api/logs/*                         │
│                                                      │
│  SQLite: data/api_bridge.db (WAL mode, 13 tabel)     │
└─────────────────┬────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────────────┐
│         Moduły core/ (20+ modułów Python)            │
│                                                      │
│  6x WooCommerce    9x Allegro                        │
│  3x Etykiety       2x Empik      1x Fakturownia      │
└─────────────────┬────────────────────────────────────┘
                  │
     ┌────────────┼────────────┬──────────────┐
     ▼            ▼            ▼              ▼
BossOfToys     WC REST      Allegro        ShipX
(hurtownia)    API          OAuth 2.0      REST API

Komunikacja między komponentami

Stos technologiczny

Backend (VPS)

Frontend (WordPress Plugin)

Wdrożenie i uruchomienie

Uruchomienie VPS

# Instalacja zależności
pip install fastapi uvicorn woocommerce requests python-dotenv

# Uruchomienie API (produkcja)
python run_api.py

# Z opcjami
python run_api.py --port 8080 --reload

# Tryb Desktop (GUI lokalny)
python main_woo.py

Minimalna konfiguracja .env

# WooCommerce
WOOCOMMERCE_URL=https://twojsklep.pl
WOOCOMMERCE_KEY=ck_xxxxxxxxxxxxxxxxxxxx
WOOCOMMERCE_SECRET=cs_xxxxxxxxxxxxxxxxxxxx

# WordPress REST API (media, produkty - wymaga Application Password)
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# BossOfToys
BOSSOFTOYS_EMAIL=email@firma.pl
BOSSOFTOYS_PASSWORD=haslo
BOSSOFTOYS_ACRONYM=ESKL1_XXXX

# API security
API_SECRET_KEY=bardzo_dlugi_losowy_klucz_min_32_znaki

# Allegro OAuth
ALLEGRO_CLIENT_ID=twoj_client_id
ALLEGRO_CLIENT_SECRET=twoj_client_secret

# ShipX (InPost)
SHIPX_TOKEN=twoj_token_shipx
SHIPX_ORGANIZATION_ID=12345

# Fakturownia
FAKTUROWNIA_API_TOKEN=twoj_token
FAKTUROWNIA_DOMAIN=twojafirma

# Empik Marketplace
EMPIK_API_KEY=twoj_klucz_empik
EMPIK_SHOP_ID=twoj_shop_id

# Opcjonalne (powiadomienia)
OPENAI_API_KEY=sk-xxxxxxxxxxxx
NTFY_TOPIC=twoj_temat_ntfy
SMTP_HOST=smtp.gmail.com
SMTP_USER=email@gmail.com
SMTP_PASSWORD=app_password
ALERT_EMAIL=odbiorca@gmail.com

Migracja na nowy serwer

• 1
  Skopiuj bazę danychPlik data/api_bridge.db — zawiera cały stan systemu: tokeny OAuth, historię zamówień, cache
• 2
  Skopiuj konfiguracjęKatalog config/ + plik .env
• 3
  Uruchom serwerpython run_api.py — migracje bazy uruchomią się automatycznie

Plugin WordPress

Skopiuj folder wordpress-plugin/bossoftoys-manager/ do wp-content/plugins/ i aktywuj w WordPress → Wtyczki.

Konfiguracja

Priorytet ładowania (pierwszy wygrywa)

1. Zmienne systemowe (export WOOCOMMERCE_URL=...)
2. Plik .env w katalogu głównym
3. Plik config/settings.json (legacy)
4. Plik config/settings.dat (zaszyfrowane — tryb Desktop)

Sekcje konfiguracji

Harmonogram VPS (config/scheduler.json)

{
  "label-generator":       { "enabled": true, "interval_minutes": 15 },
  "shipment-tracking":     { "enabled": true, "interval_minutes": 30 },
  "allegro-order-sync":    { "enabled": true, "interval_minutes": 15 },
  "allegro-offer-sync":    { "enabled": true, "interval_minutes": 30 },
  "order-forwarder":       { "enabled": true, "interval_minutes": 15 },
  "stock-sync":            { "enabled": true, "interval_minutes": 30 },
  "price-updater":         { "enabled": true, "interval_minutes": 1440 },
  "allegro-repricing":     { "enabled": true, "interval_minutes": 360 }
}

Baza danych SQLite

Plik: data/api_bridge.db — WAL mode + PRAGMA foreign_keys=ON

Architektura dostępu do danych

core/*.py
   └─ from core.data_store import data_store  (lazy import w funkcji!)
         └─ core/data_store.py (adapter)
               ├─ VPS: api/repository.py → api/database.py → SQLite
               └─ Desktop: pliki JSON (fallback)

13 tabel bazy danych

Moduły — BossOfToys / WooCommerce

Szczegóły modułu Order Forwarder

Tryb auto_forward: Jeśli boss_api.auto_forward=true, forwarding odbywa się inline po wygenerowaniu etykiety w label_auto_generator.py — bez potrzeby osobnego CRON Order Forwarder.

Moduły — Allegro Marketplace

Ważne gotcha — Allegro API

Mapowanie statusów fulfillment

Moduły — Etykiety i Wysyłka

Label Auto Generator (CRON)

Plik: core/label_auto_generator.py — centralny moduł automatyzacji wysyłki.

Zamówienie "processing" bez etykiety
  │
  ├─ _allegro_checkout_id JEST → Allegro Shipment Management API
  └─ _allegro_checkout_id BRAK → ShipX (InPost) API

Po wygenerowaniu etykiety:
  ├─ Zapis PDF: data/labels/label_{order_id}.pdf
  ├─ Meta WC: _*_shipment_id, _*_tracking_number, _shipping_label_source
  ├─ Pickup Scheduling (Allegro, inline, non-fatal)
  ├─ Auto-forward do BossOfToys (jeśli auto_forward=true)
  └─ NTFY/e-mail przy błędach

3-krokowy flow Allegro (allegro_label_generator.py)

• 1
  POST /shipment-management/shipments/create-commandsTworzy przesyłkę z additionalProperties (np. InPost sendingMethod) i smart wymiarami paczki
• 2
  GET /shipment-management/shipments/create-commands/{id}Polling co 2s, max 30 prób — czeka na potwierdzenie
• 3a
  POST /shipment-management/labelPayload: {"shipmentIds": [...]} → zwraca labelId
• 3b
  GET /shipment-management/label/{labelId}Header: Accept: application/octet-stream — zwraca bajty PDF

Smart wymiary paczek InPost

System bierze największy gabaryt ze wszystkich produktów w zamówieniu. PHP hook kopiuje meta z produktu do line item przy składaniu zamówienia.

Pickup Scheduling (allegro_pickup_scheduler.py)

Shipment Tracking (shipment_tracking.py)

CRON co 30 min. Dwa źródła danych równolegle:

Moduły — Integracje zewnętrzne

Fakturownia.pl

Plik: core/fakturownia_client.py

• Produkty: Product Adder tworzy kartotekę (SKU, nazwa, cena, EAN)
• Faktury: PHP hook planuje pobranie PDF 60s po zmianie statusu na processing
• Pliki: wp-content/uploads/faktury/faktura_{order_id}.pdf
• Auto-cleanup po 3 miesiącach
• Jeśli zamówienie Allegro: faktura uploadowana do Allegro (_allegro_invoice_uploaded)

Empik Marketplace — OR23 i OR24

Plik: core/empik_client.py (Mirakl API)

Warunek automatycznego OR24: _empik_order_id JEST + _empik_carrier_tracking_number JEST + _empik_or24_sent BRAK + status WC = collected_from_sender LUB shipped/completed

Plugin WordPress

Struktura plików

wordpress-plugin/bossoftoys-manager/
├── bossoftoys-manager.php              ← Główny plik, aktywacja
├── includes/
│   ├── class-bot-api.php               ← Klient HTTP do VPS (X-API-Key)
│   ├── class-bot-admin.php             ← Dashboard, ustawienia, 53+ AJAX handlerów
│   ├── class-bot-cron.php              ← WP-Cron handlery
│   ├── class-bot-labels.php            ← Meta box etykiety na zamówieniu
│   ├── class-bot-inpost-sizes.php      ← Gabaryty InPost per produkt
│   ├── class-bot-geowidget.php         ← Mapa InPost na checkout
│   └── class-bot-allegro-orders.php    ← Dane Allegro na zamówieniu, fix VAT
└── admin/
    ├── views/
    │   ├── dashboard.php               ← Kokpit (statystyki, wykresy, logi)
    │   ├── settings.php                ← Ustawienia (BossOfToys, Allegro, itp.)
    │   ├── schedule.php                ← Harmonogram CRON
    │   ├── page-allegro.php            ← Panel Allegro (oferty, zamówienia, wysyłka)
    │   └── page-logs.php               ← Logi aplikacji
    ├── js/dashboard.js                 ← JavaScript (60+ funkcji)
    └── css/admin.css                   ← Style pluginu

Kluczowe PHP hooki (class-bot-admin.php)

Meta box etykiety (class-bot-labels.php)

Wyświetlany na stronie zamówienia WC. Zawiera:

• Status etykiety z kolorowym źródłem (🟠 Allegro / 🟡 ShipX)
• Kurier + numer tracking z linkiem śledzenia
• Przyciski: Generuj / Pobierz PDF / Regeneruj
• Badge statusu trackingu (zielony delivered, niebieski w transporcie, czerwony zwrot)
• Sekcja Empik: OR23 ✅/❌, OR24 ✅/❌, przycisk Wyślij OR24
• Sekcja Fakturownia: link do faktury PDF

API REST — mapa endpointów

Zadania (jobs)

Etykiety

Allegro — główne endpointy

Przepływ zamówień

Jak system rozpoznaje typ zamówienia?

Meta zamówienia WC: _allegro_checkout_id
  ├─ JEST    → Zamówienie ALLEGRO
  │            Etykieta: Allegro Shipment Management
  │            Tracking: Allegro Tracking API
  │            Faktura: upload do Allegro
  │            Status: sync → Allegro SENT
  │
  ├─ BRAK + _empik_order_id JEST → Zamówienie EMPIK
  │            Etykieta: ShipX (InPost)
  │            OR23: numer trackingu do Empika
  │            OR24: potwierdzenie wysyłki
  │
  └─ BRAK    → Zamówienie SKLEPOWE
               Etykieta: ShipX (InPost)
               Tracking: ShipX API
               Faktura: tylko lokalna

Zamówienie sklepowe — pełny flow

KROK 1 — ZŁOŻENIE
  Klient → WooCommerce → status: processing (po płatności)
  PHP hook → planuje pobranie faktury (60s)
  Geowidget → _inpost_point_id
  PHP hook → _inpost_parcel_size z produktów do line items

KROK 2 — ETYKIETA (CRON: label-generator, co 15 min)
  Brak _allegro_checkout_id → ShipX API
  Odczytuje _inpost_parcel_size → największy gabaryt
  Tworzy przesyłkę ShipX → PDF → data/labels/label_{id}.pdf
  Meta: _shipx_shipment_id, _shipx_tracking_number

  [auto_forward=true] → BossOfToys + status completed

KROK 3 — ŚLEDZENIE (CRON: shipment-tracking, co 30 min)
  ShipX API → status paczki
  "collected_from_sender" → AUTO-COMPLETE WC
  PHP hook (completed) → Fakturownia PDF

GOTOWE ✅

Zamówienie Allegro — pełny flow

KROK 1 — IMPORT (CRON: allegro-order-sync, co 15 min)
  Allegro API → POST /wc/v3/orders
  Drugi PUT: _wc_order_attribution_utm_source="Allegro"
  Meta: _allegro_checkout_id, _allegro_buyer_*, _allegro_delivery_*
  PHP fix: zeruje VAT "zw" na wysyłce

KROK 2 — ETYKIETA (CRON: label-generator, co 15 min)
  Jest _allegro_checkout_id → Allegro Shipment Management
  3-krokowy flow: create → poll → label PDF
  Smart wymiary z _inpost_parcel_size
  Meta: _allegro_shipment_id, _allegro_tracking_number, _allegro_carrier
  Pickup scheduling: DHL → zamów, InPost/GLS/UPS → skip
  [auto_forward=true] → BossOfToys

KROK 3 — ŚLEDZENIE (CRON: shipment-tracking, co 30 min)
  Allegro Tracking API (/order/carriers/{id}/tracking)
  statuses[-1] = najnowszy status
  IN_TRANSIT  → WC: "shipped"
  DELIVERED   → WC: "completed" → Fakturownia → upload faktury
              → Fulfillment sync: Allegro SENT

GOTOWE ✅

Zamówienie Empik

KROK 1 — IMPORT
  Empik → WooCommerce (meta _empik_order_id)

KROK 2 — ETYKIETA + OR23 (label-generator)
  ShipX etykieta → _shipx_shipment_id, _shipx_tracking_number
  OR23 inline: empik_client.send_tracking()
  → _empik_carrier_tracking_number

KROK 3 — OR24 (shipment-tracking, co 30 min)
  "collected_from_sender" + _empik_order_id + tracking + brak or24_sent
  → OR24: empik_client.confirm_ship()
  → Empik: SHIPPED
  → _empik_or24_sent = "1"
  (ręczny fallback: przycisk "Wyślij OR24")

GOTOWE ✅

Harmonogram CRON

Kolejność włączania (nowe wdrożenie)

• 1
  Etykiety i śledzenieLabel Generator + Shipment Tracking + Order Forwarder (lub auto_forward=true)
• 2
  Import AllegroAllegro Order Sync + Allegro Offer Sync
• 3
  ProduktyStock Sync + Price Updater + Product Adder (najpierw raz ręcznie)
• 4
  Product DeleterNajpierw DRY-RUN przez kilka dni, sprawdź logi, dopiero potem dry_run=false

Meta dane na zamówieniach WooCommerce

Kluczowe meta (routing systemu)

Meta etykiet Allegro

Meta etykiet ShipX

Meta Empik

Meta Attribution (Pochodzenie w WC)

Zależności między modułami

BossOfToys API / XML
        │
        ├──────────────────────────────────┐
        ▼                                 ▼
  Stock Sync ──────────► WooCommerce    Product Adder
  Price Updater ─────────► (REST API)   Product Deleter
  Cost Backfill                │
                               │
        ┌──────────────────────┤
        │                      │
        ▼                      ▼
  Allegro Scanner ──► WooCommerce produkty (EAN)
        │
        ▼
  Allegro Lister ──────────► Allegro API (OAuth 2.0)
                                     │
        ┌────────────────────────────┤
        │                            │
        ▼                            ▼
  Allegro Order Sync          Allegro Offer Sync
        │                            │
        ▼                            ▼
  WooCommerce               Allegro oferty
  (zamówienia)              (stany/ceny)
        │
        ├──────────────────────────────────────┐
        │                                      │
        ▼                                      ▼
  Label Auto Generator                   Order Forwarder
    │         │                                │
    │         │                                ▼
    ▼         ▼                         BossOfToys API
  ShipX   Allegro                       (zamówienie + PDF)
  Label   Label
    │         │
    └────┬────┘
         │
         ▼
  Shipment Tracking ──► ShipX API / Allegro Tracking API
         │
         ├──────────────► AUTO-COMPLETE WC
         ├──────────────► OR24 Empik (jeśli _empik_order_id)
         └──────────────► Fakturownia → upload faktury → Allegro SENT

Kolejność uruchamiania modułów

1. Label Generator — etykiety muszą być pierwsze
2. Shipment Tracking — śledzi i auto-complete
3. Order Forwarder — wymaga etykiety
4. Allegro Order Sync — import nowych zamówień
5. Stock Sync — stany magazynowe
6. Allegro Offer Sync — po sync stanów
7. Price Updater — ceny
8. Allegro Fulfillment Sync — na końcu (zależy od etykiet)

Historia wersji

Rozwiązywanie problemów

Diagnoza ogólna — pierwsze kroki

1. Sprawdź logi VPS: WordPress → BossOfToys → Logi
2. Status API Allegro: GET /api/allegro/status
3. Diagnostyka WP REST API: GET /api/config/wp/test
4. Status Schedulera: GET /api/stats/scheduler
5. Weryfikacja składni: python -m py_compile core/nazwa_modulu.py

Allegro

Brak tokenu / "Nie połączono z Allegro"

Sprawdź czy ALLEGRO_CLIENT_ID i ALLEGRO_CLIENT_SECRET są w .env. Tokeny OAuth są w SQLite (kv_store), nie w configu — autoryzuj przez WordPress → Ustawienia → Allegro.

Zamówienia Allegro — "Pochodzenie: Nieznane"

Wymaga obu meta: _wc_order_attribution_utm_source="Allegro" ORAZ _wc_order_attribution_source_type="utm". WooCommerce może nadpisać attribution w hooku — allegro_order_sync.py wykonuje drugi PUT po zapisie zamówienia.

Błąd 406 przy pobieraniu etykiety

Header Accept: application/octet-stream jest wymagany (NIE application/pdf!).

Endpoint etykiety 404

/shipment-management/label/commands NIE ISTNIEJE. Używaj POST /shipment-management/label.

WooCommerce / WordPress

Empik

Baza danych

Komendy diagnostyczne

# Weryfikacja składni Pythona
python -m py_compile core/allegro_order_sync.py

# Test połączenia Allegro
curl -H "X-API-Key: TWOJ_KLUCZ" https://vps:8000/api/allegro/status

# Test połączenia WordPress
curl -H "X-API-Key: TWOJ_KLUCZ" https://vps:8000/api/config/wp/test

# Status Schedulera VPS
curl -H "X-API-Key: TWOJ_KLUCZ" https://vps:8000/api/stats/scheduler