REST-API

Alles, was das Dashboard kann, über HTTPS mit einem API-Schlüssel.

Authentifizierung

Erstellen Sie unter Einstellungen → API keys einen Schlüssel und senden Sie ihn als Bearer-Token. Schlüssel werden nur einmal angezeigt.

curl https://api.adjoin.dev/v1/me \
  -H "Authorization: Bearer adj_live_…"

read: GET-Anfragen.
write: Kampagnen, Sites und Placements anlegen und ändern.
conversions: Nur die Server-zu-Server-Conversion-Endpunkte.

Ein Schlüssel ist nie Admin und kann keine Schlüssel erstellen oder Auszahlungen anfordern — das braucht eine angemeldete Person.

Beträge sind immer ganze Zahlen in Micros: 1 USD = 1.000.000.

Endpunkte

GET /v1/me: Wem der Schlüssel gehört.
GET /v1/campaigns: Ihre Kampagnen mit Status, Gebot, Budget und Ausgaben.
POST /v1/campaigns: Kampagne anlegen; startet in der Prüfung. Das Budget wird vom Guthaben reserviert.
POST /v1/campaigns/plan: Startgebot, Reichweitenprognose und Reserve für ein Budget, bevor Sie sich festlegen.
GET /v1/refunds?campaign_id=cmp_…: Gefilterte, nicht berechnete Klicks mit Grund.
POST /v1/conversions/s2s: Conversion vom Server bestätigen.
POST /v1/conversions/s2s/refund: Bestätigte Bestellung innerhalb der Rückgabefrist stornieren.
GET /v1/sites · POST /v1/sites: Ihre Sites; Domain registrieren.
POST /v1/sites/{site_id}/verify: Domain-Besitz prüfen (DNS TXT, Datei oder Meta-Tag).
GET /v1/placements?site_id= · POST /v1/placements: Slots einer Site; Slot anlegen.
GET /v1/placements/{placement_id}/live: Ob ein Slot in den letzten 24 Stunden Anfragen erhielt.
GET /v1/boost · POST /v1/boost: Status des Launch Day Boost; für eine Kampagne einlösen.
GET /v1/credits: Cross-Promotion-Guthaben und letzte Aktivität.
GET /v1/segments: Zielgruppen-Labels der Publisher mit Seitenaufrufen der letzten 7 Tage (nur ab 100). Beim Anlegen einer Kampagne in target_segments / exclude_segments verwenden.

Kampagne anlegen

pricing_model ist cpc, cpm, cpa, affiliate, guaranteed oder cross_promo (mit Guthaben bezahlt, kein Barbudget). 402 bedeutet: verfügbares Guthaben zu niedrig.

curl -X POST https://api.adjoin.dev/v1/campaigns \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{
    "name": "Launch",
    "pricing_model": "cpc",
    "bid_micros": 300000,
    "total_budget_micros": 50000000,
    "daily_cap_micros": 5000000,
    "target_categories": ["devtools"],
    "creatives": [{ "headline": "Ship faster", "body": "…", "cta": "Try it",
                    "landing_url": "https://myapp.dev", "format": "card" }]
  }'

Server-zu-Server-Conversions

Stellen Sie die Conversion-Quelle der Kampagne auf s2s und bestätigen Sie Bestellungen von Ihrem Server mit einem Schlüssel mit conversions-Bereich. Das Pixel berechnet diese Kampagne dann nicht mehr, eine Bestellung wird also nie über beide Wege berechnet. Klicks lassen sich 7 Tage lang bestätigen.

# the ad click lands on https://myapp.dev/?aj_t=… — keep aj_t with the order
curl -X POST https://api.adjoin.dev/v1/conversions/s2s \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "click_token": "<aj_t>", "order_id": "order_1234", "value_micros": 29000000 }'

# a return or cancellation, inside the return window
curl -X POST https://api.adjoin.dev/v1/conversions/s2s/refund \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "campaign_id": "cmp_…", "order_id": "order_1234" }'

Fehler

Fehler sind JSON mit einem detail-Feld. 401: Schlüssel fehlt oder ungültig. 403: Bereich fehlt. Auch für Objekte anderer Konten kommt 404, ihre Existenz wird nie verraten.

Fragen: [email protected]