Entwickler-API

API-Dokumentation

Erstelle geschützte Links, rufe datenschutzbewusste Analysen ab und erfasse Conversions aus deinem Produkt.

Sende deine erste Anfrage

Die API ist für Server-zu-Server-Kommunikation gedacht. Lege Tokens nie in Browser-JavaScript oder öffentlichen Mobile-Bundles offen.

1Starte Pro oder BusinessAPI-Zugriff ist in unterstützten Bezahlplänen und während der Pro-Testphase verfügbar.
2Erstelle ein Token mit passenden RechtenWähle in der Entwicklerkonsole nur die Rechte, die deine Integration benötigt.
3Sende es über HTTPSAuthorization: Bearer 4ul_live_…
4Bewahre es wie ein Passwort aufDas vollständige Token wird einmal angezeigt. Widerrufe es sofort, wenn es offengelegt sein könnte.

curl "https://4ul.ink/api/v1/links?per_page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpunktreferenz

Jeder Objektzugriff ist auf den dem Token zugewiesenen Workspace beschränkt.

MethodePfadBerechtigungErgebnis

GET/api/v1/linkslinks:readPaginierte Links

POST/api/v1/linkslinks:writeErstellt einen geschützten Link

PATCH/api/v1/links/{id}links:writeAktualisiert übergebene Felder

DELETE/api/v1/links/{id}links:writeDeaktiviert ohne Analysen zu löschen

GET/api/v1/links/{id}/analyticsanalytics:readAggregierte Analysen

POST/api/v1/conversionslinks:writeErfasst ein zugeordnetes Ereignis

GET/api/v1/domainsdomains:readEigene Domains

POST/api/v1/domainsdomains:writeVerbinde eine Domain

POST/api/v1/domains/{id}/verifydomains:writeDNS überprüfen

DELETE/api/v1/domains/{id}domains:writeEntfernen

GET/api/v1/webhookswebhooks:readWebhook-Endpunkte

POST/api/v1/webhookswebhooks:writeEndpunkt hinzufügen

PATCH/api/v1/webhooks/{id}webhooks:writeAktualisiert übergebene Felder

POST/api/v1/webhooks/{id}/testwebhooks:writeTest senden

POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeSecret rotieren

DELETE/api/v1/webhooks/{id}webhooks:writeLöschen

Anfragen und Antworten

Die Feldnamen entsprechen exakt der produktiven v1-API.

POST

Link erstellen

links:write

{
    "destination_url": "https://example.com",
    "slug": "launch",
    "title": "Launch article"
}

destination_url: Erforderliche öffentliche HTTP- oder HTTPS-URL.
title: Optional, bis zu 190 Zeichen.
slug: Optionaler Alias mit 3 bis 80 Zeichen.

201

Link-Antwort

application/json

{
  "data": {
    "id": 123,
    "slug": "launch",
    "short_url": "https://4ul.ink/launch",
    "destination_url": "https://example.com/article",
    "title": "Launch article",
    "click_count": 0,
    "is_active": true,
    "created_at": "2026-07-25 12:00:00"
  }
}

GET

Links auflisten

?page=1&per_page=25

{
  "data": [{ "id": 123, "slug": "launch", "is_active": true }],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

per_page akzeptiert 1 bis 100. Link-Objekte verwenden die oben gezeigte vollständige Antwortstruktur.

GET

Analysen abrufen

analytics:read

/api/v1/links/123/analytics?period=custom
  &from=2026-07-01
  &to=2026-07-20

Zeiträume sind 7, 30, 90 oder custom. Die Antwort enthält Übersicht, Vergleiche, Traffic-Qualität, Conversions, Tagesreihen, Zielgruppen und Stundenmuster – niemals rohe Besucher-IP-Adressen.

PATCH

Link aktualisieren

/api/v1/links/123

{
  "destination_url": "https://example.com/new",
  "title": "New title",
  "slug": "new-alias",
  "is_active": true
}

Nur übergebene Felder ändern sich. Ein neues Ziel stellt automatisch eine Nova-Shield-Analyse in die Warteschlange.

POST

Conversion erfassen

/api/v1/conversions

{
  "click_token": "4ul_click_…",
  "event": "sale",
  "external_id": "order_1042",
  "amount": 49.00,
  "currency": "USD"
}

Ereignisse sind lead, sale oder refund. Ein doppeltes externes Ereignis liefert HTTP 409 und wird nie doppelt gezählt.

Token-Berechtigungen

links:read: listet Links auf.
links:write: erstellt, aktualisiert und deaktiviert Links und erfasst Conversions.
analytics:read: liest Link-Analysen.
domains:read / domains:write: Eigene Domains
webhooks:read / webhooks:write: Signierte Webhooks

Anfragelimits

Tokens erlauben 120 Anfragen pro Minute plus das monatliche Workspace-Kontingent. Analysen haben zusätzlich 60 Anfragen pro Minute. HTTP 429 enthält Retry-After- und RateLimit-Header. Normale Weiterleitungen funktionieren weiter.

Idempotenz

Sende beim Erstellen einen Idempotency-Key mit 8–128 druckbaren Zeichen. Er gilt 24 Stunden im Workspace. Ein identischer Versuch spielt die Antwort erneut ab; andere Daten mit demselben Schlüssel liefern HTTP 409.

HTTP

Fehler

Fehler haben ein einheitliches JSON-Format. Häufig: 400 ungültiges JSON, 401 ungültiges Token, 403 fehlende Rechte oder Plan, 404 nicht gefunden, 409 Konflikt, 413 Body zu groß, 415 falscher Typ, 422 Validierung und 429 Limit.

{
  "error": "destination_url must be a valid public HTTP or HTTPS URL.",
  "code": "invalid_destination",
  "field": "destination_url",
  "request_id": "req_7fd9c0c8d821e84b3d69d171",
  "error_details": {
    "code": "invalid_destination",
    "message": "destination_url must be a valid public HTTP or HTTPS URL.",
    "field": "destination_url",
    "request_id": "req_7fd9c0c8d821e84b3d69d171"
  }
}

HMAC

Prüfe jeden Webhook

Ereignisse: link.created, link.updated, link.disabled, link.clicked, conversion.created, shield.status_changed und endpoint.test. Die automatische Zustellung versucht es bis zu fünfmal.

Verfügbarkeits-Webhooks verwenden shield.availability_changed und enthalten Statuswechsel sowie begrenzte HTTP-Diagnosen ohne Ziel-URLs.

Zustellungsheader

X-4ulink-Event: conversion.created
X-4ulink-Delivery: EVENT_UUID
X-4ulink-Timestamp: UNIX_TIMESTAMP
X-4ulink-Signature: sha256=HEX_HMAC

PHP-Prüfung

$raw = file_get_contents('php://input');
$signed = $timestamp . '.' . $raw;
$expected = 'sha256=' . hash_hmac('sha256', $signed, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Verwende den unveränderten Body, vergleiche Signaturen in konstanter Zeit, lehne Zeitstempel über fünf Minuten ab und speichere X-4ulink-Delivery für idempotente Wiederholungen. Endpunkte benötigen öffentliches HTTPS auf Port 443.