Initial import into Gitea

2026-03-14 13:50:09 -07:00
parent 8e7e03702e
commit 34c1f09e01
154 changed files with 17666 additions and 1548 deletions
--- a/TikTokApi/README.md
+++ b/TikTokApi/README.md
@@ -0,0 +1,299 @@
+# 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 |