VoltMaster - Lead API Dokumentation

Inhaltsverzeichnis

Übersicht
Authentifizierung
API-Endpoints
Datenstrukturen
Beispiele
Fehlerbehandlung
Rate Limiting
Support & Kontakt

Übersicht

Die VoltMaster Lead-Management API ermöglicht es externen Systemen, Leads zu erstellen, zu verwalten und zu verfolgen. Alle Leads werden sicher in unserem System gespeichert und können über das Admin-Panel verwaltet werden.

Lead-Erstellung

Sichere Erstellung neuer Leads

CRUD-Operationen

Vollständige Verwaltung

A-E Qualifizierung

Lead-Ranking System

Konvertierung

Lead zu Kunde

Authentifizierung

API-Token erforderlich: Um die API zu nutzen, benötigen Sie einen API-Token mit entsprechenden Berechtigungen.

Token anfordern

Kontaktieren Sie uns zur Token-Erstellung:

E-Mail: voltmaster.saas@gmail.com

Token verwenden

Authorization: Bearer YOUR_API_TOKEN_HERE
Content-Type: application/json

Verfügbare Berechtigungen

Berechtigung	Beschreibung
`leads:create`	Leads erstellen
`leads:read`	Leads anzeigen/auflisten
`leads:update`	Leads bearbeiten
`leads:delete`	Leads löschen
`leads:status`	Lead-Status ändern
`leads:convert`	Leads zu Kunden konvertieren

API-Endpoints

POST/leads

Beschreibung: Erstellt einen neuen Lead im System.

Erforderliche Berechtigung: leads:create

Request Body (Minimum):

{
  "name": "Firmenname"
}

Request Body (Vollständig):

{
  "name": "Beispiel GmbH & Co. KG",
  "contact_person": "Max Mustermann",
  "department": "Geschäftsführung",
  "email": "kontakt@beispiel.de",
  "phone": "+49 30 12345678",
  "website": "https://www.beispiel.de",
  "street": "Musterstraße 123",
  "address_line_2": "2. OG, Büro 42",
  "postal_code": "10115",
  "city": "Berlin",
  "state": "Berlin",
  "country": "Deutschland",
  "country_code": "DE",
  "ranking": "A",
  "notes": "Interessanter Lead mit großem Potenzial",
  "contact_source": "Website-Kontaktformular",
  "is_active": true
}

GET/leads

Beschreibung: Ruft eine paginierte Liste aller Leads ab.

Erforderliche Berechtigung: leads:read

Query Parameter:

page (int): Seitennummer (Standard: 1)
per_page (int): Einträge pro Seite (Max: 100, Standard: 15)
search (string): Suchbegriff
ranking (string): Filter nach Ranking (A, B, C, D, E)
city (string): Filter nach Stadt
is_active (boolean): Filter nach Status

GET/leads/{id}

Beschreibung: Ruft Details eines spezifischen Leads ab.

Erforderliche Berechtigung: leads:read

PUT/leads/{id}

Beschreibung: Aktualisiert die Daten eines bestehenden Leads.

Erforderliche Berechtigung: leads:update

DELETE/leads/{id}

Beschreibung: Löscht einen Lead aus dem System.

Erforderliche Berechtigung: leads:delete

PATCH/leads/{id}/convert-to-customer

Beschreibung: Konvertiert einen Lead in einen Kunden.

Erforderliche Berechtigung: leads:convert

Datenstrukturen

Lead-Rankings

Code	Beschreibung	Bedeutung
A	Heißer Lead	Sehr interessiert, hohe Abschlusswahrscheinlichkeit
B	Warmer Lead	Interessiert, mittlere Abschlusswahrscheinlichkeit
C	Kalter Lead	Wenig Interesse, niedrige Priorität
D	Unqualifiziert	Lead muss noch qualifiziert werden
E	Nicht interessiert	Kein Interesse, Follow-up nicht empfohlen

Herkunft des Kontakts (contact_source)

Das Feld contact_source speichert die Herkunft des Leads und hilft bei der Analyse der Akquisitionskanäle.

Feld	Typ	Beschreibung	Validierung
`contact_source`	Text	Herkunft des Kontakts	Optional, max. 1000 Zeichen

Typische Werte für contact_source:

Website-Kontaktformular - Lead über Website generiert
Telefonakquise - Durch aktive Anrufe gewonnen
Empfehlung - Weiterempfehlung von bestehenden Kunden
Messe/Event - Auf Veranstaltungen kennengelernt
Social Media - Über soziale Netzwerke kontaktiert
Google Ads - Über Werbeanzeigen gefunden
Partner - Über Vertriebspartner vermittelt
Newsletter - Über E-Mail Marketing gewonnen

Beispiele

Beispiel 1: Minimaler Lead

curl -X POST https://voltmaster.cloud/api/app/leads \
  -H "Authorization: Bearer sb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'

Beispiel 2: Vollständiger Lead

curl -X POST https://voltmaster.cloud/api/app/leads \
  -H "Authorization: Bearer sb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Solutions GmbH",
    "contact_person": "Anna Schmidt",
    "department": "Einkauf",
    "email": "anna.schmidt@tech-solutions.de",
    "phone": "+49 40 987654321",
    "website": "https://www.tech-solutions.de",
    "street": "Innovationsallee 42",
    "postal_code": "20095",
    "city": "Hamburg",
    "state": "Hamburg",
    "country": "Deutschland",
    "country_code": "DE",
    "ranking": "A",
    "notes": "Großes Potenzial für Solaranlagen-Projekt",
    "is_active": true
  }'

Fehlerbehandlung

Standard HTTP-Statuscodes

Code	Beschreibung
`200`	Erfolgreich
`201`	Erfolgreich erstellt
`400`	Fehlerhafte Anfrage
`401`	Nicht authentifiziert
`403`	Berechtigung fehlt
`404`	Ressource nicht gefunden
`422`	Validierungsfehler
`500`	Serverfehler

Fehler-Response Format

{
  "success": false,
  "message": "Beschreibung des Fehlers",
  "errors": {
    "field_name": ["Spezifische Fehlermeldung"]
  }
}

Rate Limiting

Rate Limits:

Standard-Token: 1000 Anfragen pro Stunde
Premium-Token: 5000 Anfragen pro Stunde

Bei Überschreitung: Status 429 Too Many Requests

Support & Kontakt

Technischer Support

E-Mail: voltmaster.saas@gmail.com
Support-Zeiten: Mo-Fr, 9:00-17:00 Uhr

VoltMaster Lead API