first

2026-07-20 07:36:55 +02:00
parent 496104f65a
commit a7cb53e0e6
16 changed files with 1856 additions and 19 deletions
@@ -1,3 +1,69 @@
 # Meta services

-Generated by AppFactory.
+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.