TikTok Shop — core/tiktok

Stan: 0.1.5, rozpoczęta implementacja; nie jest to kompletne wydanie 1.0.0. Docelowe 1.0.0 ma umożliwiać normalną obsługę zamówień po imporcie w Orbito: automatyzacje, pakowanie, faktury, przesyłki, etykiety, druk i zwrot trackingu. Moduł korzysta ze wzorców Mirakl i Amazon. Konfiguracja mapowań i integracji znajduje się w Config bieżącej instancji, a nie w osobnym formularzu panelu.

Co zaimplementowano

Osobna instancja na sklep; trwałe przypisanie sprzedawcy, sklepu i dostawcy zamówień.
OAuth sprzedawcy przez bilety rdzenia Orbito: jednorazowy state związany z

użytkownikiem, firmą i instancją, wymiana kodu, kontrola zakresów, odświeżanie i rozłączenie. Bilet powstaje dopiero po kliknięciu przycisku połączenia. Tokeny są prywatnymi danymi runtime; nie występują w diagnostyce ani w odpowiedziach UI.

Podpis HMAC-SHA256 i transport przez Core.fetch; brak sieci bezpośrednio z kontenera.
Trwałe okna odczytu, nieprzezroczyste tokeny paginacji, nakładka 5 minut,

zapis ID zamówień przed przesunięciem kursora i ponowne odczyty oczekujących zamówień.

Idempotentny import przez orders.create z tożsamością sklep + zamówienie + instancja.

Każdy line item TikToka jest jedną sztuką; identyfikatory wszystkich sztuk są zachowane.

Dane marketplace: produkt, SKU, obraz, ceny, odbiorca, dostawa i płatność.

Orbito pozostaje właścicielem katalogu, BOM-ów i normalnego obiegu dokumentów.

Jawny VAT w Config, w tym stawka 0%, wyjątki SKU i VAT dostawy.

Nieuzgodnione kwoty lub brak VAT uruchamiają istniejącą kontrolę finansową Orbito.

ON_HOLD, UNPAID i oczekujące anulowanie pozostają w kolejce poza Orbito.

Historia jest importowana bez automatyzacji utworzenia, płatności i żądania faktury. Pobranie nie tworzy fikcyjnej wpłaty. Anonimowy e-mail TikToka nie jest adresem klienta.

Seller Shipping: odczyt jednej przesyłki Orbito, mapowanie ID instancji przewoźnika,

sprawdzenie dostępności przewoźnika dla zamówienia i Mark Package As Shipped po wskazanym statusie fizycznej wysyłki. Nadanie kurierem, etykiety i druk realizuje dotychczasowy obieg Orbito; moduł TikTok przekazuje wynik.

Trwały dziennik potwierdzeń wysyłki. Niepewny wynik lub restart po wysłaniu żądania

nie powoduje powtórzenia efektu. Potwierdzenie wymaga zgodnych pozycji, trackingu, przewoźnika i stanu odczytanych z TikToka.

Diagnostyka kolejki i wkład do szczegółów zamówienia. Panel służy logowaniu i

diagnostyce; nie przechowuje równoległych ustawień integracji.

Faktury

Faktury powstają przez standardowych dostawców i automatyzacje Orbito. Config pozwala zgłosić potrzebę faktury dla osoby fizycznej. Użytkownik musi uzupełnić dane firmowe, jeżeli potrzebuje faktury dla firmy — API zamówienia nie gwarantuje polskiego NIP. Import finansowo niepełny pozostaje do zatwierdzenia w istniejącym obiegu Orbito.

Nie wysyłamy polskiego PDF do TikToka. Oficjalny Upload Invoice 202502 opisuje XML dla lokalnych sprzedawców w Brazylii. Nie stanowi potwierdzenia obsługi faktur PDF w Polsce. Dostępność uploadu należy ponownie sprawdzić dla rynku przed rozszerzeniem.

Uruchomienie w środowisku testowym

Utwórz aplikację ISV w Partner Center; włącz seller.order.info,

seller.authorization.info i, dla zwrotu trackingu, seller.fulfillment.basic. Aplikacja w development korzysta z development shop; dostęp do prawdziwego sklepu wymaga właściwego etapu aplikacji.

Zarejestruj callback rdzenia https://v2.orbito.pl/api/oauth/callback.

Moduł używa OAuth.createTicket z SDK @orbito/api-lib 4.3.0 (funkcja od 4.2.0). Rdzeń i frontend muszą obsługiwać bilety OAuth. Adres jest pobierany z biletu, a wynik trafia do oauth.finish właściwej instancji w kontekście użytkownika. Nie wdrażaj starych plików HTML/JS callbacku; wersje od 0.1.2 ich nie potrzebują.

Pozwól platformie Orbito na ruch do open-api.tiktokglobalshop.com i

auth.tiktok-shops.com. Kontener nie używa globalnego fetch ani SDK z własną siecią.

Autor ustawia wspólne dane aplikacji w Secrets store Orbito przez omm secrets,

zgodnie z instrukcją wdrożenia. Rdzeń przekazuje je do środowiska kontenera na podstawie deklaracji secrets w manifeście. Klient instaluje osobną instancję modułu i otrzymuje uprawnienie tiktok.manage. Otwiera stronę TikTok Shop w ustawieniach, klika „Połącz konto TikTok Shop” i zatwierdza dostęp u TikToka. Nie zakłada konta Partner Center ani nie wpisuje danych aplikacji. Po powrocie odświeża autoryzowane sklepy i wybiera sklep w Config.

Wybierz dokładne instancje dostawców, statusy i jawne stawki VAT. Otwórz Config

ponownie po zmianie instancji zamówień, aby odświeżyć jej statusy.

Użyj „Sprawdź połączenie”, potem włącz synchronizację w izolowanej firmie testowej.

Pierwsze zamówienia udostępnią kody przewoźników TikTok w Config.

W Config przypisz kody do konkretnych instancji przewoźników Orbito; włącz tracking

po sprawdzeniu pełnego obiegu z jedną przesyłką i statusem fizycznej wysyłki.

Lokalnie sprawdzono protokół biletów przez rzeczywiste SDK oraz izolację użytkownika, instancji, aplikacji, jednorazowość i niepewną wymianę kodu. Nie wykonano jeszcze logowania na rzeczywistym sklepie ani pełnego testu frontend → TikTok → callback. Po aktualizacji wymagane jest nowe logowanie; tokeny ze starszego mechanizmu nie są uznawane za połączenie nowego mechanizmu.

Dane aplikacji autora (0.1.5)

Wszystkie firmy korzystają z jednej aplikacji ISV Orbito. Config klienta zawiera wyłącznie sklep i mapowania; nie zawiera App key, App secret, Service ID ani regionu autoryzacji. OAuth, wymiana i odświeżanie tokenów oraz podpisy API korzystają z serwerowych danych autora. Tokeny sprzedawcy są nadal osobne dla każdej instancji. Stare wpisy application.* są ignorowane, bez automatycznego usuwania danych.

Manifest deklaruje TIKTOK_APP_KEY, TIKTOK_APP_SECRET, TIKTOK_SERVICE_ID i TIKTOK_AUTH_REGION. Ich wartości przechowuje Secrets store Orbito i wstrzykuje rdzeń przy starcie kontenera. Moduł wymaga kompletu zmiennych; nie odczytuje już pliku application-private.json ani wcześniejszych zmiennych ORBITO_TIKTOK_*. Sekret i identyfikatory aplikacji nie są częścią nowego ZIP-a/obrazu, formularzy, diagnostyki ani odpowiedzi metod. Lokalnie omm dev korzysta z ignorowanego .env; przykład bez poświadczeń znajduje się w .env.example.

Przed aktualizacją ustaw komplet danych przez omm secrets i sprawdź przekazanie ich przez rdzeń przy starcie kontenera. Wersje 0.1.3–0.1.4 nadal zawierają poprzedni sekret w starych artefaktach. Przed udostępnieniem klientom dokonaj jego rotacji w TikTok Partner Center i zapisz nową wartość w Secrets store.

Brak danych autora pokazuje ogólny komunikat dostępności, bez proszenia klienta o klucze. Zmiana danych aplikacji unieważnia dotychczasowe połączenie i otwarte próby OAuth. Publikacja modułu Orbito nie oznacza zatwierdzenia aplikacji przez TikToka; przed obsługą klientów wymagane są weryfikacje widoczne w Partner Center.

Otwarte prace do pełnego 1.0.0

TikTok Shipping: zakup etykiety, usługa dostępna dla konkretnego zamówienia,

waga i wymiary, dokument, rejestracja w Orbito i druk przez kontrakty. W specyfikacji jest Create Packages 202512; decyzję o wersji i ścieżce trzeba zweryfikować dla rynku i jego wymaganego workflow. Obecny kod nie wywołuje tej operacji.

Blokada realizacji u właścicieli operacji: po anulowaniu lub zmianie danych

integracja ustawia status problemu i blokuje własny eksport trackingu. Nie jest to techniczna blokada ręcznego pakowania, faktury ani nadania przez inne moduły. Potrzebny jawny kontrakt domenowy właściciela zamówień, respektowany przez pakowanie, przesyłki i wystawianie dokumentów, bez zależności od marki źródła.

Weryfikacja i zatwierdzanie zmian adresu, pozycji i cen bez nadpisywania ręcznych

poprawek; obecne konflikty są trwałe i pozostają do obsługi operatora.

Secure webhook ingress platformy/relay, walidacja podpisu surowego body,

deduplikacja, seller deauthorization i upcoming expiration. Obecnie działa polling; nie wystawiono pozornego publicznego endpointu modułu.

Scenariusze odbioru w punkcie, częściowych anulowań i dopłat/promocji: uzgodnione

kwoty dla księgowości, potwierdzona semantyka VAT/VCS, właściwe dane odbiorcy.

Odtworzenie/usunięte zamówienia i powiązane zamówienia/merge: wykorzystanie

istniejących kontraktów po decyzji o wymaganym zachowaniu, bez arbitralnego przekazania trackingu z innego zamówienia.

Test na development shop oraz pełny test w autoryzowanej instancji Orbito:

import → automatyzacja → pakowanie → faktura → przesyłka → etykieta → druk → tracking.

Osobne rozszerzenia, poza zakresem tej implementacji: listing produktów i stanów, reklamy, affiliate, komunikator klienta, rozliczenie prowizji/payoutów, zwroty i refundacje, FBT oraz nietypowe próbki, prezenty, wymiany, virtual bundles, blind boxes, towary wymagające szczególnego obiegu. Wersja 0.1.5 pokazuje te zamówienia w diagnostyce; nie zamienia ich w zwykłe zamówienia do nadania.

Konfiguracja i logo (0.1.1)

Poprawiono rejestrację bloków Config: każdy tytuł zawiera wymagane przez SDK title.en. Po aktualizacji uruchomionej instancji platforma otrzymuje metadane konfiguracji dla przycisku „Konfiguruj”. Test uruchomienia korzysta z rzeczywistej walidacji i serializacji Config SDK, przy zastąpionym transporcie.

Oficjalna ikona TikToka jest dołączona jako assets/tiktok-icon.png i zgłaszana przez orders.source.register do wybranej instancji zamówień: w źródłach, filtrach i szczegółach zamówienia. Odświeża się przy starcie, włączeniu, imporcie i sprawdzeniu połączenia. Po wybraniu dostawcy lub zmianie nazwy użyj akcji „Odśwież nazwę i logo źródła zamówień” w Config; nie wymaga ona połączenia z TikTokiem. Ikona karty w katalogu instalowanych modułów jest osobną metadaną rejestru, nie polem tego manifestu — do jej ustawienia można użyć tego samego pliku PNG. Pochodzenie oficjalnego pliku: assets/README.md.

Weryfikacja lokalna

npm ci --ignore-scripts
npm test
npm run check

Z głównego workspace:

node --test --test-concurrency=1 --test-force-exit module-contracts/*.test.js

Testy używają syntetycznych danych i rzeczywistych kopert protokołu hooków, w tym alternatywnego autora dostawcy i wyboru instancji. Nie zastępują testu API na sklepie ani testu Config/callbacku w rzeczywistym interfejsie.

Źródła i wybrane wersje API: docs/api.md.