VALIDOOO DEVELOPERS - API (v1

Schnellstart

Auth: X-API-Key Format: JSON PNG: image/png

Alle Endpoints liegen unter /v1/… und benötigen den Header X-API-Key.

Der API-Schlüssel besteht aus 64 Zeichen. Sie erstellen und verwalten bis zu fünf aktive API-Schlüssel über die Kontoübersicht in Ihrem Kundenkonto.

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/kontostand"

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "kontostand": 100,
    "einheit": "VDS"
  }
}

Base URL

Produktiv:
https://api.validooo.de/

Dokumentation:
https://www.validooo.de/developers/api_v1/

Hinweise

Alle Antworten sind no-store (kein Caching).
Query-Parameter immer setzen (z. B. ?pruefcode=).
Datumsfelder müssen im Format YYYY-MM-DD sein.

Inhalt

Authentifizierung Statuscodes & Fehlerformat Endpoints (Übersicht) Kontostand Farbauswahl Validierungssiegel (Erstellung) Validierungssiegel (Status abrufen) Validierungssiegel (Status ändern) Validierungssiegel (Archivierungsstatus abrufen) Validierungssiegel (Archivierung ändern) Validierungssiegel (Inhalt abrufen) Validierungssiegel (PNG-Ausgabe) FAQ

Authentifizierung

Die VALIDOOO API-Schnittstelle verwendet einen statischen API-Key im HTTP-Header:

X-API-Key: 64_char_lowercase_hex

Fehlt der Header, antwortet die API mit 401 (UNAUTHORIZED).
Bei falschem Format (nicht 64 Zeichen lowercase hex) ebenfalls 401.
Bei ungültigem/gesperrtem Key ebenfalls 401.

Statuscodes & Fehlerformat

Standard-Erfolgsantworten enthalten success: true. Fehlerantworten enthalten success: false und ein Error-Objekt.

Typische HTTP-Statuscodes

Code	Bedeutung
200	OK (Erfolg)
201	Created (Siegelerstellung neu)
400	Bad Request (Parameter/Validierung)
401	Unauthorized (fehlender/ungültiger API-Key)
403	Forbidden (z. B. Kontostand zu gering / Farbe nicht erlaubt)
404	Not Found (Siegel/Datensatz nicht gefunden)
500	Server-/Crypto-/DB-Fehler

Fehlerobjekt (Beispiel)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Parameter muss exakt ?pruefcode= heißen"
  }
}

Hinweis: Manche Responses liefern ergänzende Felder (z. B. vds_status).

Endpoints (Übersicht)

Methode	Pfad	Zweck
GET	/v1/kundenkonto/farbauswahl_aktuell	Aktuelle Farbauswahl des Validierungssiegels anzeigen
GET	/v1/kundenkonto/farbauswahl_liste	Verfügbare Farben für das Kundenkonto anzeigen
POST	/v1/kundenkonto/farbauswahl_aendern	Farbauswahl des Validierungssiegels ändern
GET	/v1/kundenkonto/kontostand	Aktuellen VDS-Kontostand des Kundenkontos anzeigen
POST	/v1/kundenkonto/siegelerstellung	Neues Validierungssiegel erstellen
GET	/v1/kundenkonto/siegelinhalt	Inhalt des Validierungssiegels in Klartext anzeigen
GET	/v1/kundenkonto/siegelgenerator_png	Validierungssiegel als PNG-Bilddatei herunterladen
GET	/v1/kundenkonto/siegelstatus	Aktuellen Status des Validierungssiegels anzeigen
POST	/v1/kundenkonto/siegelstatus_aendern	Status des Validierungssiegels ändern
GET	/v1/kundenkonto/siegelarchivierung	Archivierungsstatus des Validierungssiegels anzeigen
POST	/v1/kundenkonto/siegelarchivierung_aendern	Archivierung des Validierungssiegels ändern

Root-Healthcheck: Ein Aufruf der Domain-Root / (GET) liefert eine kleine Status-Antwort (service/status/version/hint/docs).

Kontostand

GET /v1/kundenkonto/kontostand

Liefert den aktuellen VDS-Kontostand des Kundenkontos, das dem API-Key zugeordnet ist.

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/kontostand"

Response (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "kontostand": 100,
    "einheit": "VDS"
  }
}

Farbauswahl

Farben sind als name_datenbank (technischer Key) und name_anzeige (UI-Name) verfügbar. Eine Farbe kann nur gesetzt werden, wenn sie für das Kundenkonto freigeschaltet ist.

Request (aktuelle Farbauswahl)

GET /v1/kundenkonto/farbauswahl_aktuell

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_aktuell"

Response-Beispiel (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farbauswahl": {
      "name_datenbank": "schwarz_onyx",
      "name_anzeige": "Schwarz (ONYX)"
    }
  }
}

Request (verfügbare Farben)

GET /v1/kundenkonto/farbauswahl_liste

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_liste"

Response-Beispiel (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farben":[
      {"name_anzeige":"Grau (SMOKYTONES)","name_datenbank":"grau_smokytones"},
      {"name_anzeige":"Grün (SMARAGD)","name_datenbank":"gruen_smaragd"},
      {"name_anzeige":"Rot (LAVA)","name_datenbank":"rot_lava"},
      {"name_anzeige":"Schwarz (ONYX)","name_datenbank":"schwarz_onyx"},
      {"name_anzeige":"Standard (VALIDOOO-BLAU)","name_datenbank":"standard_validoooblau"}
    ]
  }
}

Request (Farbauswahl ändern)

POST /v1/kundenkonto/farbauswahl_aendern

Body (JSON) muss exakt das Feld farbe enthalten.

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "farbe": "standard_validoooblau"
  }' \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_aendern"

Response-Beispiel (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farbauswahl": {
      "name_datenbank": "standard_validoooblau",
      "name_anzeige": "Standard (VALIDOOO-BLAU)"
    }
  }
}

Validierungssiegel (Erstellung)

POST /v1/kundenkonto/siegelerstellung

Erstellt ein neues Validierungssiegel (Achtung: Dieser Vorgang kostet bei der Neuerstellung 1 VDS) und liefert den eindeutigen Prüfcode (bestehend aus 4 Blöcken mit jeweils 4 Zeichen, z. B. X4yB-x3XT-zx2Y-XZY1) und den neuen Kontostand zurück. Wenn für denselben Prüfcode bereits ein Datensatz existiert, wird er ausschließlich aktualisiert (insb. zusätzliche/weitere Informationen, Dokumentenversion) und der Kontostand nicht erneut reduziert.

Content-Type

application/json (empfohlen)
alternativ: application/x-www-form-urlencoded

Body Parameter

Feld	Pflicht	Beschreibung
dokument_version	JA	Verfügbare Versionen: modern oder klassisch
dokument_art	JA	Verfügbare Dokumentenarten: Zertifikat Zeugnis Urkunde (Teilnahme) Gutachten / Prüfdokument Bestätigung / Nachweis Vertrag Protokoll / Bericht Zahlungen / Finanzen Gutschein / Nachlass Kündigung / Rückabwicklung Ausweis / Ticket
text-A	JA	Inhalt VALIdot-A / Vorname (Inhaltsvorgaben gemäß Handbuch)
text-B	JA	Inhalt VALIdot-B / Nachname (Inhaltsvorgaben gemäß Handbuch)
text-C	JA	Inhalt VALIdot-C/ Geburtsdatum (Inhaltsvorgaben gemäß Handbuch)
text-D	JA	Inhalt VALIdot-D / Geburtsort (Inhaltsvorgaben gemäß Handbuch)
text-E	JA	Inhalt VALIdot-E / Ausstellungsdatum (Inhaltsvorgaben gemäß Handbuch)
text-zusatzinfos	NEIN	Maximal 500 Zeichen, keine Zeilenumbrüche, Inhaltsregeln wie VALIdots

Request (JSON, Beispiel „modern“)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dokument_version": "modern",
    "dokument_art": "Zertifikat",
    "text-A": "Beispielinhalt A (100 Zeichen)",
    "text-B": "Beispielinhalt B (30 Zeichen)",
    "text-C": "Beispielinhalt C (30 Zeichen)",
    "text-D": "Beispielinhalt D (30 Zeichen)",
    "text-E": "Beispielinhalt E (30 Zeichen)",
    "text-zusatzinfos": "Optionaler Zusatztext (500 Zeichen)"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelerstellung"

Request (JSON, Beispiel „klassisch“)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dokument_version": "klassisch",
    "dokument_art": "Zeugnis",
    "text-A": "Vorname (50 Zeichen)",
    "text-B": "Nachname (50 Zeichen)",
    "text-C": "1999-01-01",
    "text-D": "Geburtsort (50 Zeichen)",
    "text-E": "2025-12-31",
    "text-zusatzinfos": "Optionaler Zusatztext (500 Zeichen)"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelerstellung"

Response (201 – neu erstellt)

{
  "success": true,
  "pruefcode": "XXXX-XXXX-XXXX-XXXX",
  "dokument_version": "modern",
  "dokument_art": "Zertifikat",
  "kontostand": 99
}

Response (200 – bereits vorhanden, aktualisiert)

{
  "success": true,
  "hinweis": "Siegel war bereits vorhanden und wurde aktualisiert",
  "pruefcode": "XXXX-XXXX-XXXX-XXXX",
  "dokument_version": "modern",
  "dokument_art": "Zertifikat",
  "kontostand": 100
}

Wichtig: Es werden nur bestimmte Zeichen akzeptiert. Bei Version klassisch müssen text-C und text-E echte Kalenderdaten im Format YYYY-MM-DD sein.

Validierungssiegel (Status abrufen)

GET /v1/kundenkonto/siegelstatus?pruefcode=XXXX-XXXX-XXXX-XXXX

Prüft den Aktivierungsstatus eines Siegels über den Prüfcodestring. Der Prüfcodestring ist case-sensitiv (Groß-/Kleinschreibung wird beachtet).

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelstatus?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200)

{
  "success": true,
  "vds_status": "aktiviert"
}

Mögliche Werte: aktiviert oder deaktiviert.

Validierungssiegel (Status ändern)

POST /v1/kundenkonto/siegelstatus_aendern

Aktiviert oder deaktiviert ein Siegel. Der Request-Body (JSON) muss exakt die Felder pruefcode und status enthalten. status akzeptiert nur aktiviert oder deaktiviert.

Request

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pruefcode": "XXXX-XXXX-XXXX-XXXX",
    "status": "deaktiviert"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelstatus_aendern"

Response (200)

{
  "success": true,
  "vds_status": "deaktiviert"
}

Validierungssiegel (Archivierungsstatus abrufen)

GET /v1/kundenkonto/siegelarchivierung?pruefcode=XXXX-XXXX-XXXX-XXXX

Prüft den Archivierungsstatus eines Siegels über den Prüfcodestring. Der Prüfcodestring ist case-sensitiv (Groß-/Kleinschreibung wird beachtet).

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelarchivierung?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200)

{
  "success": true,
  "vds_archiv": "archiviert"
}

Mögliche Werte: archiviert oder bereitgestellt.

Validierungssiegel (Archivierung ändern)

POST /v1/kundenkonto/siegelarchivierung_aendern

Archivierung oder Bereitstellung eines Siegels. Der Request-Body (JSON) muss exakt die Felder pruefcode und archiv enthalten. archiv akzeptiert nur archivierung oder bereitstellung.

Request

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pruefcode": "XXXX-XXXX-XXXX-XXXX",
    "archiv": "bereitstellung"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelarchivierung_aendern"

Response (200)

{
  "success": true,
  "vds_archiv": "bereitgestellt"
}

Validierungssiegel (Inhalt abrufen)

GET /v1/kundenkonto/siegelinhalt?pruefcode=XXXX-XXXX-XXXX-XXXX

Gibt den im Siegel hinterlegten Inhalt sowie den optionalen Zusatztext aus. Die Schlüsselbezeichnungen unterscheiden sich je nach dokument_version.

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelinhalt?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200 – Beispiel modern)

{
  "success": true,
  "dokument_art": "Zertifikat",
  "dokument_version": "modern",
  "daten": {
    "VALIdot-A": "Beispielinhalt A (100 Zeichen)",
    "VALIdot-B": "Beispielinhalt B (30 Zeichen)",
    "VALIdot-C": "Beispielinhalt C (30 Zeichen)",
    "VALIdot-D": "Beispielinhalt D (30 Zeichen)",
    "VALIdot-E": "Beispielinhalt E (30 Zeichen)"
  },
  "dokument_zusatztext": "Optionaler Zusatztext (500 Zeichen)"
}

Response (200 – Beispiel klassisch)

{
  "success": true,
  "dokument_art": "Zeugnis",
  "dokument_version": "klassisch",
  "daten": {
    "Vorname": "Vorname (50 Zeichen)",
    "Nachname": "Nachname (50 Zeichen)",
    "Geburtsdatum": "1999-01-01",
    "Geburtsort": "Geburtsort (50 Zeichen)",
    "Ausstellungsdatum": "2025-12-31"
  },
  "dokument_zusatztext": "Optionaler Zusatztext (500 Zeichen)"
}

Validierungssiegel (PNG-Ausgabe)

GET /v1/kundenkonto/siegelgenerator_png?pruefcode=XXXX-XXXX-XXXX-XXXX

Liefert das Validierungssiegel als PNG-Datei (Content-Type: image/png) und setzt Content-Disposition: attachment (Browser-Download).

Request (Download in Datei)

curl -L \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelgenerator_png?pruefcode=XXXX-XXXX-XXXX-XXXX" \
  --output IHR_INDIVIDUELLER_DATEINAME.png

Hinweis: Dieser Endpoint liefert keine JSON-Ausgabe, sondern eine Binärdatei (PNG-Bilddatei).

Rate-Limits

Wie sind Rate-Limits konfiguriert?

Die Rate-Limits sind so konfiguriert, dass pro API-Schlüssel maximal 80 Anfragen pro Minute zulässig sind, während pro IP-Adresse bis zu 200 Anfragen pro Minute verarbeitet werden.

Wie erkenne ich, ob ein Rate-Limit ausgelöst wurde?

Ob ein Rate-Limit ausgelöst wurde, lässt sich daran erkennen, dass die API mit einem entsprechenden HTTP-Statuscode (z. B. 429 Too Many Requests) antwortet oder im Response eindeutige Hinweise auf eine Limitüberschreitung enthält.

Wie wird mit fehlerhaften oder unzulässigen Anfragen umgegangen?

Sämtliche 401-, 403- und 404-Fehler werden streng überwacht und bei auffälligem Verhalten automatisch gesperrt. Eine Freigabe erfolgt ebenfalls automatisiert gemäß interner Richtlinien und kann nicht vorzeitig aufgehoben werden.