REST-API v1 Dokumentation & Spezifikation

HevLink Developer & REST-API

Integrieren Sie unsere URL-Kürzungs-, Verifizierungs- und Sicherheits-Features nahtlos in Ihre eigenen Applikationen, Pipelines und Marketing-Tools.

Offizielle REST-API v1 Spezifikation

Hochverfügbare Schnittstelle für URL-Kürzungen, Sicherheitsanalysen und Klick-Statistiken. Vollständig kompatibel mit Bearer-Token-Authentifizierung, standardisiertem JSON und gängigen HTTP-Clients.

1. Authentifizierung & Basis-Konfiguration

Alle Anfragen an die HevLink API werden verschlüsselt über HTTPS übertragen. Der Zugriff erfordert ein persönliches Bearer-Token im HTTP-Header.

Basis-URL
https://www.hevlink.com/v1

Alle Endpunkt-Pfade sind relativ zu dieser Root-URL definiert.

Inhaltsformat
application/json; charset=utf-8

Sowohl Anfrage-Payloads als auch Server-Antworten nutzen ausnahmslos JSON.

Bearer-Token Authentifizierung

Übertragen Sie Ihren API-Schlüssel bei jeder Anfrage im standardisierten Authorization-Header mit dem Präfix Bearer:

HTTP Request Header 
Authorization: Bearer  YOUR_API_TOKEN
Content-Type: application/json
Wichtiger Sicherheitshinweis: Halten Sie Ihr Bearer-Token stets geheim. Veröffentlichen Sie Tokens niemals in clientseitigem Code oder öffentlichen Git-Repositories.

2. API-Endpunkte

Übersicht aller verfügbaren REST-Methoden für Link-Erstellung, Auswertung und Sicherheitsprüfungen.

POST /api/v1/links/create
Erfordert Bearer-Token

Neuen Kurzlink erstellen

Kürzt eine beliebige Ziel-URL. Unterstützt optionale benutzerdefinierte Aliase, Tags, UTM-Kampagnen-Parameter sowie Ablaufdaten.

Feld Typ Status Beschreibung
url string Erforderlich Die vollständige Ziel-URL inklusive Protokoll (http:// oder https://).
title string Optional Hilft Ihnen dabei, den Shortlink in der Übersicht eindeutig zu identifizieren.
custom_alias string Optional Gewünschter individueller Pfad (z. B. sommer-sale) Mindestens 8 Zeichen.
tag string Optional Kategorie/Tag zur Gruppierung (z. B. Marketing, Docs, Social).
utm_source string Optional Google Analytics UTM-Quelle (z. B. newsletter, twitter).
utm_campaign string Optional UTM-Kampagnenname für Trackings.
expires_at string Optional Ablaufdatum nach ISO 8601 (z. B. 2026-12-31T23:59:59Z).
Request Body (JSON) 
{
  "url": "https://ihre-domain.de/kampagne/landingpage",
  "custom_alias": "sommer-kampagne",
  "tag": "Marketing",
  "utm_source": "newsletter"
}
Response (201 Created) 
{
  "status": "success",
  "data": {
    "id": "lnk_987654321",
    "short_url": "https://www.hevlink.com/sommer-kampagne",
    "short_code": "sommer-kampagne",
    "original_url": "https://ihre-domain.de/kampagne/landingpage?utm_source=newsletter",
    "created_at": "2026-09-03T16:00:00Z",
    "qr_code_url": "https://www.hevlink.com/qr/sommer-kampagne"
  }
}
GET /api/v1/links/{code}
Erfordert Bearer-Token

Link-Details & Klick-Analysen abrufen

Liefert Echtzeit-Statistiken, Klickzahlen, Erstellungszeitpunkt und Ziel-URL für einen konkreten Kurzcode.

Response (200 OK) 
{
  "status": "success",
  "data": {
    "code": "api-reference",
    "title": "",
    "short_url": "https://www.hevlink.com/api-reference",
    "original_url": "https://example.app/api-doc-2020.html",
    "is_active": true,
    "is_starred": false,
    "clicks": 865,
    "tag": "Marketing",
    "created_at": "2026-09-02T14:27:10Z",
    "expires_at": null,
    "modified_at": "2026-09-03T14:22:10Z",
    "requested_at": "2026-09-15T14:27:10Z"
  }
}
DELETE /api/v1/links/{code}
Erfordert Bearer-Token

Kurzlink deaktivieren & löschen

Deaktiviert einen bestehenden Kurzlink dauerhaft. Weiterleitungen werden umgehend gestoppt.

Response (200 OK oder 204 No Content) 
{
  "status": "success",
  "message": "Link 'sommer-kampagne' wurde erfolgreich gelöscht."
}
POST /api/v1/links/verify
Erfordert Bearer-Token

URL-Sicherheitsprüfung (Verify Source)

Prüft eine Ziel-URL oder einen Kurzlink automatisiert gegen Reputationsdatenbanken, Phishing-Listen und SSL-Zertifikatsstandards.

Response (200 OK) 
{
  "status": "success",
  "data": {
    "target_url": "https://example.app/features/enterprise-security-whitepaper",
    "safety_score": 98,
    "verdict": "safe",
    "is_ssl_valid": true,
    "is_phishing": false,
    "is_malware": false
  }
}

3. Implementierungsbeispiele

Kopierfertige Snippets für typische Entwicklungs-Umgebungen mit Bearer-Token Autorisierung.

cURL (Terminal)

bash / curl 
curl -X POST https://www.hevlink.com/v1/links/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ihre-domain.de/produkt-angebot",
    "custom_alias": "produkt-aktion"
  }'

JavaScript (Fetch API)

javascript / node.js 
const API_TOKEN = "YOUR_API_TOKEN";

async function createShortUrl(targetUrl, alias) {
  const response = await fetch("https://www.hevlink.com/v1/links/create", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      url: targetUrl,
      custom_alias: alias
    })
  });

  const data = await response.json();
  console.log("Kurzlink:", data.data.short_url);
  return data;
}

Python (Requests)

python 
import requests

API_TOKEN = "YOUR_API_TOKEN"
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "url": "https://ihre-domain.de/whitepaper/sicherheitsbericht",
    "tag": "Marketing"
}

response = requests.post("https://www.hevlink.com/v1/links/create", headers=headers, json=payload)
print(response.json())

4. HTTP-Status-Codes & Fehlerbehandlung

Die HevLink REST-API verwendet standardisierte HTTP-Codes zur Signalisierung des Anfrage-Ergebnisses.

Status-Code Bedeutung Detailbeschreibung
200 OK Erfolg Die Anfrage wurde erfolgreich verarbeitet.
201 Created Erstellt Neuer Kurzlink wurde erfolgreich angelegt.
400 Bad Request Ungültige Anfrage Der Request-Body oder die Parameter sind fehlerhaft (z. B. ungültiges URL-Format).
401 Unauthorized Nicht autorisiert Fehlendes, abgelaufenes oder fehlerhaftes Bearer-Token im Authorization-Header.
404 Not Found Nicht gefunden Der angeforderte Kurzlink oder die Ressource existiert nicht.
409 Conflict Konflikt Der gewünschte benutzerdefinierte Alias ist bereits vergeben.
429 Too Many Requests Rate-Limit erreicht Das Abfragelimit (Standard: 120 Requests/Minute) wurde überschritten.
500 Internal Error Serverfehler Unerwarteter interner Verarbeitungsfehler im Backend.

Einheitliches Fehlerformat (JSON)

Response (401 Unauthorized) 
{
  "status": "error",
  "code": "AUTH_TOKEN_INVALID",
  "message": "Ungültiges Bearer-Token übergeben. Bitte überprüfen Sie Ihren Authorization-Header.",
  "timestamp": "2026-09-03T16:04:12Z"
}