Aussteller-API

Verwalte Auszeichnungsaussteller — die Organisationen oder Personen, die Auszeichnungen vergeben.

Alle Endpunkte erfordern Authentifizierung über den X-Api-Key-Header. Siehe Authentifizierung.

Aussteller erstellen

Erstellt einen neuen Auszeichnungsaussteller.

POST /issuers

Parameter

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Name der Organisation (mindestens 3 Zeichen)
url	string	Ja	Website der Organisation (muss eine gültige HTTP/HTTPS-URL sein)
email	string	Ja	Kontakt-E-Mail des Ausstellers
logo	string	Nein	Base64-kodiertes Bild (PNG oder JPG)
linkedinOrganizationId	string	Nein	Numerische LinkedIn-Unternehmensseiten-ID. Wenn gesetzt, zeigt jede öffentliche Vergabeseite dieses Ausstellers eine Schaltfläche Zum LinkedIn-Profil hinzufügen.

Beispiel

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Antwort

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Hinweise

• Zählt gegen das Aussteller-Limit deines Plans (Free: 1, Starter: 5, Pro: unbegrenzt). Kein Kontingentabzug.
• Stimmt die Aussteller-E-Mail mit der E-Mail deines Kontos überein, wird der Aussteller automatisch verifiziert.
• Unterscheidet sich die E-Mail, wird eine Verifizierungs-E-Mail an die Aussteller-E-Mail verschickt.

---

Aussteller auflisten

Ruft alle von dir erstellten Aussteller ab.

GET /issuers

Beispiel

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Antwort

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "name": "Acme Academy",
        "url": "https://acme.example.com",
        "email": "badges@acme.example.com",
        "verified": true,
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Aussteller verifizieren

Verifiziert einen Aussteller mit dem Verifizierungs-Code, der an seine E-Mail gesendet wurde.

POST /issuers/{issuerId}/verify

Parameter

Parameter	Typ	Erforderlich	Beschreibung
issuerId	string	Ja	Die Aussteller-ID (Pfadparameter)
code	string	Ja	Der Verifizierungs-Code aus der E-Mail

Beispiel

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Antwort

{
  "statusCode": 200,
  "info": {
    "verified": true
  }
}

---

Aussteller löschen

Löscht einen Aussteller. Der Aussteller darf keine Auszeichnungen haben.

DELETE /issuers/{issuerId}

Beispiel

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Antwort

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Fehler

• 400 — der Aussteller hat Auszeichnungen oder Vergaben und kann nicht gelöscht werden (lösche diese zuerst)
• 404 — Aussteller nicht gefunden

---

Aussteller aktualisieren

Aktualisiert Felder eines nicht verifizierten Ausstellers. Nach der Verifizierung bleiben nur logo und linkedinOrganizationId editierbar, um die Stabilität der Nachweise zu wahren.

PUT /issuers/{issuerId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
issuerId	string	Ja	Die Aussteller-ID (Pfadparameter)
name	string	Nein	Neuer Name (nur wenn nicht verifiziert)
url	string	Nein	Neue URL (nur wenn nicht verifiziert)
email	string	Nein	Neue E-Mail (nur wenn nicht verifiziert — sendet eine neue Verifizierungsmail)
logo	string	Nein	Neues Base64-kodiertes Logo
linkedinOrganizationId	string	Nein	Neue LinkedIn-Organisations-ID (oder leerer String zum Entfernen)

---

Verifizierungs-Code rotieren

Macht den vorherigen Verifizierungs-Link ungültig und verschickt per E-Mail einen neuen. Nur gültig, solange der Aussteller noch nicht verifiziert ist.

POST /issuers/{issuerId}/rotate-code

Antwort

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}