# Eduard's TikTok Shop quickstart

**Phase 1:** import orders into Hello Pine, synchronize their state and report fulfillment.
**Phase 2:** export product data to TikTok Shop. Use existing test-shop products for phase 1.

**Access status — checked 23 September 2026:** our public app is a draft; scopes await
review. [Development Shops](https://partner.tiktokshop.com/v2_sandbox/guide) currently
reports Sandbox unavailable in our region. Preparation can start; the token/API steps
need an authorized test seller. [TikTok requires test sellers for unpublished apps](https://partner.tiktokshop.com/docv2/page/test-your-app).
Nabil needs to clarify test access with TikTok. No successful API call is recorded yet.

## 1. Set up the tools and orient yourself

Install [Postman Desktop](https://www.postman.com/downloads/). Create a collection
`Hello Pine — TikTok Orders` and a test environment. No TikTok SDK is required for this
manual HTTP workflow.

Open [our Hello-Pine app](https://partner.tiktokshop.com/service/gather?service_id=7629646293844625173)
and [TikTok's API Testing Tool](https://partner.tiktokshop.com/dev/api-testing-tool).
The [tool guide](https://partner.tiktokshop.com/docv2/page/api-testing-tool) explains selecting
our own app key, authorizing a test seller and generating a cURL request. Once a request
works there, [import its cURL into Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data)
and save it in the collection. Keep secrets in local secret storage, outside shared exports.

Read the docs as needed: **Developer Guide** explains flows; **API Reference** provides
each endpoint's scope, method, parameters and example; **Webhooks** explains event payloads.
On every endpoint, check scope and version before copying its example.

Note: TikTok's test guide links a [Postman walkthrough](https://partner.tiktokshop.com/docv2/page/call-tts-apis-with-postman),
but it returned “Kein Dokument gefunden” during this check. Use the working tool/import
instructions above; this handoff does not depend on a downloadable TikTok collection.

## 2. Authorize a test seller and obtain the access token

Read [Authorization overview](https://partner.tiktokshop.com/docv2/page/authorization-overview-202407).
Our Partner Center login identifies the developer; the token represents a seller's grant.

1. In app details, find App Key/App Secret and confirm a development Redirect URL.
   Check approved scopes for the chosen endpoints: orders use `seller.order.info`,
   shipment reporting uses `seller.fulfillment.basic`.
2. Once test access is available, authorize our app from the **test seller**. Use the
   tool's authorization flow for manual testing. For Pine's own flow, use the guide's
   ROW seller link, validate `state`, and receive `code` at the Redirect URL.
3. Exchange that code with **GET `https://auth.tiktok-shops.com/api/v2/token/get`**:
   `app_key`, `app_secret`, `auth_code` and `grant_type=authorized_code`.
   The code is single-use and expires after 30 minutes.
4. Retain `access_token`, `refresh_token`, expiry timestamps and `granted_scopes`.
   The same guide documents `/api/v2/token/refresh`; implement refresh before expiry.

**Check:** the token belongs to the intended DE/local seller (`user_type=0`) and contains
the required grants. Keep token request URLs and secrets out of logs and handoff files.

## 3. Make the first API calls

Follow [Call Get Authorized Shops](https://partner.tiktokshop.com/docv2/page/call-get-authorized-shops)
and [Sign your API request](https://partner.tiktokshop.com/docv2/page/sign-your-api-request).
Resource requests use `x-tts-access-token`, `app_key`, `timestamp` and an HMAC `sign`;
shop calls also require `shop_cipher`. In Postman, regenerate timestamp/signature for
each send using a pre-request script based on the signing guide. An imported cURL's
fixed signature is not a reusable signing implementation.

| Run in this order | Documentation | Check |
|---|---|---|
| Get Authorized Shops | [First request](https://partner.tiktokshop.com/docv2/page/call-get-authorized-shops) | `code=0`; save the intended shop's ID and cipher |
| Get Order List — **POST**, version 202309 | [Endpoint](https://partner.tiktokshop.com/docv2/page/get-order-list-202309) | Use a narrow time window and `page_size`; follow `next_page_token` |
| Get Order Detail — **GET**, version 202507 | [Endpoint](https://partner.tiktokshop.com/docv2/page/get-order-detail-202507) | Retrieve one returned order ID; inspect line items, shipping mode, status and packages |

Read the [order lifecycle](https://partner.tiktokshop.com/docv2/page/order-api-overview)
before deciding which state releases an order to fulfillment. **Do not fulfill ON_HOLD
orders.** For incremental synchronization, order-list filters include update timestamps.

## 4. Report one test fulfillment

Read [Fulfillment overview](https://partner.tiktokshop.com/docv2/page/fulfillment-api-overview)
and inspect the order's fulfillment/shipping mode. For **seller shipping in Germany**:

1. Resolve the carrier for the order's `delivery_option_id` with
   [Get Shipping Providers](https://partner.tiktokshop.com/docv2/page/get-shipping-providers-202309).
2. For an eligible synthetic test order, call [Mark Package As Shipped](https://partner.tiktokshop.com/docv2/page/mark-package-as-shipped-202309)
   with the order/line mapping, shipping-provider ID and test tracking data.
3. Read the order/package back and verify TikTok accepted the shipment information.

TikTok shipping uses a different package/label flow; FBT is fulfilled by TikTok.
Select the flow from the actual order instead of applying seller shipping universally.

## 5. Move the verified flow into Hello Pine

Build a channel-specific client and token store per shop. Map TikTok order/line IDs to
Pine once, then reuse the existing order-transfer path. Make order import switchable per
connection, with an explicit restart cutoff. Use [webhooks](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview)
for changes, verify their signatures, deduplicate deliveries and reconcile through polling.

Source entry points, inspected at Hello Pine commit `015277c49`:
[order fetch pattern](https://github.com/Hello-Pine/hello-pine/blob/015277c49/app/Jobs/Channels/Kaufland/Orders/FetchAndProcessOrders.php#L97),
[transfer to the source shop](https://github.com/Hello-Pine/hello-pine/blob/015277c49/app/Jobs/Orders/PushNewOrderToShop.php#L266),
[channel fulfillment subscriber](https://github.com/Hello-Pine/hello-pine/blob/015277c49/app/Listeners/Channels/Etsy/EtsySubscriber.php#L100).
These are patterns to adapt, not existing TikTok support. The [development background](tiktok-shop-development-start.md)
contains the account evidence and repository context.

**First milestone:** one authorized test shop → one order read → exactly one order in
the connected test shop system → fulfillment returned to TikTok. Replaying the event
must not create another order; disabling order import must prevent transfer.