JiriUhlir
70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# Meta services
|
|
|
|
Stateless API proxy over the **Meta Marketing API** (Facebook / Instagram
|
|
advertising), running in AppFactory at `https://services.csbot.cz/apps/meta`.
|
|
|
|
The service stores no secrets: every credential is supplied per request in an
|
|
`X-` header and used only to call the Graph API. Structure mirrors the sibling
|
|
`analytics` service.
|
|
|
|
**Phase 1 is read-only** — every endpoint issues a GET upstream, so the service
|
|
cannot spend money. Campaign management is phase 2.
|
|
|
|
## Quick start
|
|
|
|
```
|
|
GET https://services.csbot.cz/apps/meta/health
|
|
GET https://services.csbot.cz/apps/meta/docs ← Swagger, "Try it out"
|
|
```
|
|
|
|
```bash
|
|
curl "https://services.csbot.cz/apps/meta/ads/me/adaccounts" \
|
|
-H "X-Meta-Access-Token: EAAG..." \
|
|
-H "X-Meta-App-Secret: <APP_SECRET>"
|
|
```
|
|
|
|
## Credentials
|
|
|
|
| Header | Required | Meaning |
|
|
| --- | --- | --- |
|
|
| `X-Meta-Access-Token` | one of these | Access token; a Business Manager **System User** token is recommended. |
|
|
| `Authorization: Bearer <token>` | one of these | Equivalent alternative (the X- header wins if both are sent). |
|
|
| `X-Meta-App-Secret` | no, recommended | App secret → the proxy derives `appsecret_proof`. Required if the app enforces app-secret proof. |
|
|
| `X-Meta-Api-Version` | no | Graph version override, e.g. `v25.0`. |
|
|
|
|
Permissions needed for this phase: `ads_read`, `business_management`.
|
|
|
|
## Endpoints
|
|
|
|
| Group | Paths |
|
|
| --- | --- |
|
|
| Infra | `/health`, `/version` |
|
|
| Structure | `/ads/me/adaccounts`, `/ads/me/businesses`, `/ads/businesses/{id}/adaccounts`, `/ads/accounts/{id}` (+ `/campaigns`, `/adsets`, `/ads`, `/adcreatives`), `/ads/campaigns/{id}` (+ `/adsets`, `/ads`), `/ads/adsets/{id}` (+ `/ads`), `/ads/ads/{id}`, `/ads/adcreatives/{id}` |
|
|
| Insights | `/ads/insights/{object_id}`, `/ads/insights/{object_id}/jobs`, `/ads/insights/{object_id}/run`, `/ads/insights/jobs/{report_run_id}`, `/ads/insights/jobs/{report_run_id}/results` |
|
|
| Generic read | `/graph/{path}` |
|
|
|
|
Large reports must go through the async endpoints — see
|
|
[documentation/meta-ads.md](documentation/meta-ads.md).
|
|
|
|
## Configuration
|
|
|
|
Non-secret settings come from environment variables; see the table in
|
|
[documentation/overview.md](documentation/overview.md). The most relevant one is
|
|
`META_API_VERSION` (default `v25.0`), which callers can override per request.
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
.venv/Scripts/pip install -r requirements.txt
|
|
.venv/Scripts/uvicorn app.main:app --reload --port 8000
|
|
# http://127.0.0.1:8000/docs
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [documentation/overview.md](documentation/overview.md) — architecture, config,
|
|
design decisions, what is deliberately not wired.
|
|
- [documentation/meta-ads.md](documentation/meta-ads.md) — endpoints, insight
|
|
fields and levels, pagination, errors, curl examples.
|