Standalone microservice for Meta (Facebook/Instagram) advertising integration. Mirrors the GoogleApi architecture pattern — the Gateway routes provider="meta" requests here via internal HTTP.

Architecture

Gateway  ──(POST /internal/execute)──►  MetaApi  ──(Graph API)──►  Meta Marketing API
         X-Internal-Key auth             │
                                         ├── Emulated mode (default)
                                         └── Real API mode (Meta__EnableRealApi=true)

Key Differences from GoogleApi

Aspect	GoogleApi	MetaApi
Auth	OAuth refresh tokens	System User token (no expiry)
SDK	Google.Ads.GoogleAds NuGet	HttpClient → graph.facebook.com
Account format	Numeric customer ID	`act_XXXXXXXXXXXXXXX`
Hierarchy	Campaign → Ad Group → Ad	Campaign → Ad Set → Ad
API versioning	SDK version	URL path (`/v21.0/`)

Operations

Operation	Description	Real API
Ping / TestPing	Health check	N/A
CreateCampaign	Create Meta campaign	✅
GetCampaign	Retrieve campaign details	✅
UpdateCampaign	Update name/status/budget	✅
ListCampaigns	List campaigns with filters	✅
GetCampaignInsights	Campaign performance metrics	Emulated only
GetAccountInsights	Account-level metrics	Emulated only
CreateAdAccount	Create ad account under BM	✅
ListAdAccounts	List BM-owned ad accounts	✅

Environment Variables

Variable	Required	Description
`META_INTERNAL_KEY`	Yes	Gateway→MetaApi shared auth key
`Meta__EnableRealApi`	No	`false` (default) = emulated responses
`Meta__AppId`	For real API	Meta App ID from Developer Portal
`Meta__AppSecret`	For real API	Meta App Secret
`Meta__SystemUserToken`	For real API	System User token from Business Manager
`Meta__BusinessManagerId`	For real API	USIM's Business Manager numeric ID
`Meta__ApiVersion`	No	Graph API version (default: `v21.0`)

Local Development

dotnet run --project MetaApi
# → http://localhost:5300
# → Swagger: http://localhost:5300/swagger

Deploy to Azure Container Apps

az containerapp create \
  --name usim-adp-metaapi \
  --resource-group USIM-AdPlatform \
  --environment usim-adp-env \
  --image <registry>/usim-adp-metaapi:latest \
  --target-port 5300 \
  --ingress internal \
  --env-vars \
    META_INTERNAL_KEY=secretref:meta-internal-key \
    Meta__EnableRealApi=false

Gateway Integration

Add to Gateway environment:

META_PROVIDER_URL=https://usim-adp-metaapi.internal.<env>.azurecontainerapps.io
META_INTERNAL_KEY=<matching-key>

Gateway's ExecutionService.GetProviderUrl() already routes provider="meta" to META_PROVIDER_URL.

Project Structure

MetaApi/
├── Configuration/
│   └── MetaConfig.cs          # Config + MetaApiContext
├── Controllers/
│   └── InternalController.cs  # /internal/execute + /internal/health
├── Models/
│   ├── OperationPayloads.cs   # Meta-specific request payloads + enums
│   └── ProviderModels.cs      # ProviderRequest/Response (Gateway contract)
├── Security/
│   └── InternalAuthFilter.cs  # X-Internal-Key validation
├── Services/
│   ├── MetaGraphClient.cs     # HTTP wrapper for graph.facebook.com
│   └── MetaMarketingService.cs # Operation dispatcher (emulated/real)
├── Program.cs
├── appsettings.json
└── MetaApi.csproj