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 · Ad Set anlegen

// 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("/meta/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: Pagination, Rate-Limits und Idempotenz.

Pagination

Listen liefern data[] im selben Umschlag wie jede andere Antwort. Geblättert wird über limit (Standard 25, höchstens 100) und offset. Kommen weniger als limit Einträge zurück, war es die letzte Seite.

{
  "data": [ { "id": "a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77", "name": "…" } ],
  "request_id": "9f2c1b70-5a83-4c2e-9d11-7e40b6a8c5d3"
}

// nächste Seite:
GET /v1/meta/adsets?limit=25&offset=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 bestimmt den Kunden und damit das Werbekonto. Es gibt keine Tarifstufen und keine Kontingente in der API.

Ist ein Zugang gesperrt, antworten schreibende Aufrufe (Ad-Sets, Ads, Creatives anlegen oder aktivieren) mit 402 payment_required. Lesende Aufrufe (Status, Insights, Listen) funktionieren weiter, damit du laufende Anzeigen weiter auswerten kannst. Die Freischaltung erfolgt über deinen Ansprechpartner.

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.