AdPlatform-Server/TikTokApi/README.md

TikTokApi - TikTok Marketing API Provider Service

Standalone microservice for TikTok advertising integration. Mirrors the GoogleApi/MetaApi architecture — the Gateway routes provider="tiktok" requests here via internal HTTP.

Architecture

Gateway  ──(POST /internal/execute)──►  TikTokApi  ──(REST)──►  TikTok Marketing API
         X-Internal-Key auth              │                      business-api.tiktok.com
                                          ├── Emulated mode (default)
                                          └── Real API mode (TikTok__EnableRealApi=true)

Platform Comparison

Aspect	GoogleApi	MetaApi	TikTokApi
Parent entity	MCC (Manager)	Business Manager	Business Center (BC)
Child accounts	Customer ID	Ad Account (act_XXX)	Advertiser ID (numeric)
Auth	OAuth refresh tokens	System User token	OAuth → long-lived token
Token expiry	Requires refresh	Never (if user active)	Never (unless revoked)
SDK	Google.Ads NuGet	HttpClient (Graph API)	HttpClient (REST)
Auth header	OAuth Bearer	query param	Access-Token header
Base URL	via SDK	graph.facebook.com	business-api.tiktok.com
API versioning	SDK version	URL path (/v21.0/)	URL path (/v1.3/)
Hierarchy	Campaign→Ad Group→Ad	Campaign→Ad Set→Ad	Campaign→Ad Group→Ad
Status values	ENABLED/PAUSED	ACTIVE/PAUSED	ENABLE/DISABLE
Response format	gRPC via SDK	JSON {data}	JSON {code,message,data}
Fund management	N/A	N/A	BC Transfer API

Operations

Operation	Description	Endpoint	Real API
Ping / TestPing	Health check	N/A	N/A
CreateCampaign	Create campaign	POST /campaign/create/	✅
GetCampaign	Retrieve campaign	GET /campaign/get/	✅
UpdateCampaign	Update name/budget	POST /campaign/update/	✅
UpdateCampaignStatus	Enable/disable/delete	POST /campaign/status/update/	✅
ListCampaigns	List with filters	GET /campaign/get/	✅
GetReport	Performance metrics	POST /report/integrated/get/	✅
CreateAdvertiser	Create ad account under BC	POST /bc/advertiser/create	✅
ListAdvertisers	List BC ad accounts	GET /bc/advertiser/get	✅
TransferFunds	Recharge/deduct ad account	POST /bc/transfer/	✅

Environment Variables

Variable	Required	Description
TIKTOK_INTERNAL_KEY	Yes	Gateway→TikTokApi shared auth key
TikTok__EnableRealApi	No	false (default) = emulated responses
TikTok__AppId	For real API	App ID from TikTok Developer Portal
TikTok__AppSecret	For real API	App Secret from Developer Portal
TikTok__AccessToken	For real API	Long-lived token from OAuth flow
TikTok__BusinessCenterId	For real API	USIM's Business Center numeric ID
TikTok__ApiVersion	No	API version (default: v1.3)
TikTok__ApiBaseUrl	No	https://business-api.tiktok.com (prod) or https://sandbox-ads.tiktok.com (sandbox)

---

TikTok Business Center & API Setup

Phase 1: Business Center Setup

1. Create TikTok For Business Account

   • Go to https://www.tiktok.com/business/
   • Sign up with a business email (use USIM company email)
   • Complete business verification

2. Create Business Center

   • Go to https://business.tiktok.com/
   • Click "Create Business Center"
   • Choose Agency type (not Advertiser — this is critical for managing client accounts)
   • Enter USIM business details, complete verification
   • Note the Business Center ID (numeric, visible in the URL)

3. Verify Business

   • Business Center → Settings → Verification
   • Upload required business documentation
   • Verification typically takes 1-3 business days
   • Required before creating ad accounts programmatically

Phase 2: Developer App Registration

4. Register as Developer

   • Go to https://business-api.tiktok.com/portal
   • Click "Become a Developer" (top right)
   • Fill in developer application:
     • Company name: USIM
     • Website: your company URL
     • Use case description: "Agency platform for managing client TikTok advertising campaigns programmatically via API. Creating and managing advertiser accounts, campaigns, ad groups, ads, and pulling performance reports."
   • Submit and wait for approval (usually 1-2 business days)

5. Create App

   • My Apps → Create New
   • App Name: "USIM AdPlatform" (or similar)
   • Description: "Multi-channel advertising management platform for SMB clients"
   • Advertiser Redirect URL: https://adptestapi.usimdev.com/auth/tiktok/callback (for OAuth flow)
   • Scope of Permissions — select all that apply:
     • ✅ Ad Account Management (ad_account_management)
     • ✅ Campaign Management (campaign_management)
     • ✅ Ad Management (ad_management)
     • ✅ Creative Management (creative_management)
     • ✅ Reporting (reporting)
     • ✅ Audience Management (audience_management)
     • ✅ Business Center Management (bc_management)
   • Note your App ID and App Secret

6. App Review

   • After creating the app, it goes through TikTok review
   • Basic access is granted immediately (sandbox)
   • For production access to campaign management, you may need additional review

Phase 3: Access Token Generation

7. Authorize the App

   • Navigate to the Authorization URL (found in app details):

     https://business-api.tiktok.com/portal/auth?app_id={APP_ID}&state=usim&redirect_uri={REDIRECT_URI}
     

   • Log in with the TikTok Business account that owns the Business Center
   • Grant all requested permissions
   • DO NOT close the redirect page — copy the auth_code from the URL

8. Exchange Auth Code for Access Token

   curl -X POST "https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/" \
     -H "Content-Type: application/json" \
     -d '{
       "app_id": "YOUR_APP_ID",
       "secret": "YOUR_APP_SECRET",
       "auth_code": "AUTH_CODE_FROM_REDIRECT"
     }'
   

   Response:

   {
     "code": 0,
     "message": "OK",
     "data": {
       "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
       "advertiser_ids": ["7123456789012345678", "7123456789012345679"]
     }
   }
   

   Important: The access token does NOT expire unless the advertiser revokes authorization. Store it securely in Azure Key Vault.

9. Verify Token Works

   curl "https://business-api.tiktok.com/open_api/v1.3/oauth2/advertiser/get/?app_id={APP_ID}&secret={APP_SECRET}" \
     -H "Access-Token: YOUR_ACCESS_TOKEN"
   

   This should return the list of advertiser IDs you have access to.

Phase 4: Sandbox Testing (Recommended)

10. Use Sandbox Environment First
    • Sandbox URL: https://sandbox-ads.tiktok.com
    • Set TikTok__ApiBaseUrl=https://sandbox-ads.tiktok.com in env vars
    • Sandbox uses the same endpoints but with test data
    • Create test campaigns, verify response formats
    • Switch to production URL when ready

Phase 5: Deploy TikTokApi Container

11. Configure Azure Container Apps

    # Create container
    az containerapp create \
      --name usim-adp-tiktokapi \
      --resource-group USIM-AdPlatform \
      --environment usim-adp-env \
      --image <registry>/usim-adp-tiktokapi:latest \
      --target-port 5400 \
      --ingress internal \
      --env-vars \
        TIKTOK_INTERNAL_KEY=secretref:tiktok-internal-key \
        TikTok__EnableRealApi=false
    
    # Add secrets (when ready for real API)
    az containerapp secret set \
      --name usim-adp-tiktokapi \
      --resource-group USIM-AdPlatform \
      --secrets \
        tiktok-access-token=<token> \
        tiktok-app-secret=<secret>
    

12. Configure Gateway

    • Add environment variables to Gateway container:

      TIKTOK_PROVIDER_URL=https://usim-adp-tiktokapi.internal.<env>.azurecontainerapps.io
      TIKTOK_INTERNAL_KEY=<matching-key>
      

    • Gateway's ExecutionService.GetProviderUrl() routes provider="tiktok" to TIKTOK_PROVIDER_URL

Phase 6: Database Setup

13. Add TikTok channel references (if not already present)

    • Ensure tbChannelConfig has tiktok channel entry
    • Create vwTikTokAccount view (mirrors vwGoogleAccount pattern)
    • Create vwTikTokCampaign view
    • Create spTikTokAccount stored procedure for account linking

14. Gateway MultiChannel config

    • Verify appsettings.json MultiChannel section includes tiktok with StatusMappings:

      {
        "tiktok": {
          "StatusMappings": {
            "ENABLE": "active",
            "DISABLE": "paused",
            "DELETE": "cancelled"
          }
        }
      }
      

---

TikTok API Quick Reference

Response Envelope

All TikTok Marketing API responses follow this format:

{
  "code": 0,
  "message": "OK",
  "data": { ... },
  "request_id": "202502171234567890..."
}

• code: 0 = success
• Non-zero = error (e.g., 40001 = auth error, 40002 = permission denied)

Key Endpoint Patterns

GET  /open_api/v1.3/campaign/get/?advertiser_id=XXX
POST /open_api/v1.3/campaign/create/  (JSON body with advertiser_id)
POST /open_api/v1.3/campaign/update/  (JSON body)
POST /open_api/v1.3/campaign/status/update/  (separate from update)
POST /open_api/v1.3/report/integrated/get/  (reporting)
POST /open_api/v1.3/bc/advertiser/create  (BC operations)
POST /open_api/v1.3/bc/transfer/  (fund management)

Common Error Codes

Code	Meaning
0	Success
40001	Authentication error (invalid/expired token)
40002	No permission for this operation
40100	Invalid parameter
40700	Rate limit exceeded
50000	Internal server error

---

Project Structure

TikTokApi/
├── Configuration/
│   └── TikTokConfig.cs         # Config + TikTokApiContext
├── Controllers/
│   └── InternalController.cs   # /internal/execute + /internal/health
├── Models/
│   ├── OperationPayloads.cs    # TikTok-specific payloads + enums
│   └── ProviderModels.cs       # ProviderRequest/Response (Gateway contract)
├── Security/
│   └── InternalAuthFilter.cs   # X-Internal-Key validation
├── Services/
│   ├── TikTokApiClient.cs      # HTTP wrapper for business-api.tiktok.com
│   └── TikTokMarketingService.cs # Operation dispatcher (emulated/real)
├── Program.cs
├── appsettings.json
└── TikTokApi.csproj

Local Development

dotnet run --project TikTokApi
# → http://localhost:5400
# → Swagger: http://localhost:5400/swagger

Port Assignments

Service	Port
Gateway	5000
GoogleApi	5200
MetaApi	5300
TikTokApi	5400
Creative	5100