# 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**
   ```bash
   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:
   ```json
   {
     "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**
   ```bash
   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**
    ```bash
    # 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:
      ```json
      {
        "tiktok": {
          "StatusMappings": {
            "ENABLE": "active",
            "DISABLE": "paused",
            "DELETE": "cancelled"
          }
        }
      }
      ```

---

## TikTok API Quick Reference

### Response Envelope
All TikTok Marketing API responses follow this format:
```json
{
  "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

```bash
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 |