API-Dokumentation

Die CampaignKit API ist eine Middleware vor der Meta Marketing API: deine Kundenplattform sendet einfache, immer gleiche Requests — wir übersetzen sie in die korrekten Meta-Calls im richtigen Werbekonto. Push-Modell (du sendest uns Daten, wir holen nichts ab), REST, JSON, eine gepinnte Meta-Version.

Maschinenlesbar

In drei Schritten zur ersten Anbindung. Beispiele sind auf Next.js (TypeScript, fetch) ausgelegt — der API-Key lebt ausschließlich serverseitig.

1 · API-Key hinterlegen

// .env.local
CAMPAIGNKIT_API_KEY=ck_live_xxxxxxxxxxxxxxxx

// lib/campaignkit.ts — schmaler Server-Wrapper (nur serverseitig nutzen)
const BASE = "https://api.campaignkit.ventureon.io/v1";

export async function campaignkit<T>(
  path: string,
  init: RequestInit = {},
): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (!res.ok) throw new Error(`CampaignKit ${res.status}: ${await res.text()}`);
  return res.json() as Promise<T>;
}

2 · Verbindung prüfen

// app/api/check/route.ts  (Next.js Route Handler)
import { campaignkit } from "@/lib/campaignkit";

export async function GET() {
  const health = await campaignkit("/health");
  return Response.json(health); // { data: { status: "ok", api_version: "v1" }, … }
}

3 · Kampagne anlegen (geplant)

// Server Action / Route Handler
import { campaignkit } from "@/lib/campaignkit";

// Ad Set unter dem von uns eingerichteten Ziel anlegen (target = Ziel-Schlüssel).
const adset = await campaignkit("/adsets", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    target: "sommerfest-2026",
    daily_budget_cents: 5000,
  }),
});

Jeder API-Call trägt den API-Key im Authorization-Header als Bearer-Token. Der Key bestimmt Kunde, Werbekonto und Plan — dahinter liegt der Meta-Token, den die Plattform nie sieht.

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx

Standard-Header

Zugang zur Doku

Gelten für alle Endpunkte: Cursor-Pagination, Rate-Limits und Idempotenz.

Pagination (Cursor)

Listen liefern data[] + paging.after. Den Cursor an die nächste Anfrage als after übergeben.

{
  "data": [ { "id": "238471029384", "name": "…" } ],
  "paging": { "after": "QVFIUm...", "has_next": true }
}

// nächste Seite:
GET /v1/adsets?offset=25&limit=25

Rate-Limits

Jede Antwort trägt X-RateLimit-*. Bei 429 die Sekundenzahl aus Retry-After abwarten (exponentielles Backoff empfohlen).

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
Retry-After: 12

Idempotenz

Bei POST-Erstellungen einen Idempotency-Key (UUID) mitsenden. Wiederholungen mit gleichem Key liefern dasselbe Ergebnis — keine doppelten Kampagnen bei Netzwerk-Retries.

Einheitliches Fehler-Objekt mit stabilem code, lesbarer message und request_id für den Support. 4xx = dein Request, 5xx = wir/Meta.

{
  "error": {
    "code": "validation_error",
    "message": "objective must be OUTCOME_TRAFFIC or OUTCOME_SALES",
    "details": [
      { "field": "objective", "issue": "invalid_enum" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Der API-Key trägt den Plan des Kunden. Pläne unterscheiden sich nur in den Kosten — der volle API-Funktionsumfang ist überall identisch.

Publizierte Ads oder Media-Spend über dem Plan-Limit → 402 quota_exceeded: neue Ads werden gesperrt, bis der Kunde upgradet (POST /v1/plan/upgrade). Downgrade jederzeit zum nächsten Zyklus.

Gleich in allen Plänen: Account-Erstellung · API-Automatisierung · Reporting · Support · Rate-Limit

Statt zu pollen, registrierst du eine HTTPS-URL und wir pushen Statusänderungen (z. B. Ad genehmigt/abgelehnt). Jeder Request ist HMAC-signiert.

Signatur verifizieren

Header X-CampaignKit-Signature = HMAC-SHA256 des Roh-Bodys mit deinem Webhook-Secret. Immer verifizieren, bevor du das Event verarbeitest.

// app/api/webhooks/campaignkit/route.ts
import crypto from "node:crypto";

export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get("X-CampaignKit-Signature") ?? "";
  const expected = crypto
    .createHmac("sha256", process.env.CAMPAIGNKIT_WEBHOOK_SECRET!)
    .update(raw)
    .digest("hex");
  if (sig !== expected) return new Response("invalid signature", { status: 401 });

  const event = JSON.parse(raw); // { type: "ad.status_changed", data: {…} }
  // … Status verarbeiten, schnell 200 zurückgeben
  return new Response("ok");
}

Event-Payload

{
  "id": "evt_2026_0001",
  "type": "ad.status_changed",
  "created": 1748505600,
  "data": {
    "ad_id": "120210394857",
    "effective_status": "DISAPPROVED",
    "reason": "Text-Overlay > 20%"
  }
}

Die Version steckt im Pfad-Präfix (/v1). Innerhalb von v1 sind nur additive, nicht-brechende Änderungen erlaubt — neue Felder/Endpunkte kommen hinzu, bestehende verschwinden nicht.

• Pinnen: optionaler Header CampaignKit-Version: v1 fixiert das Verhalten unabhängig vom Account-Default.
• Breaking Changes erscheinen nur in einer neuen Major-Version (/v2) — niemals in /v1.
• Deprecation: abgekündigte Versionen laufen mind. 6 Monate weiter; Hinweise via Sunset-Header + Changelog.