Intune Insights Implementierungshandbuch für die Garantie-Integration

Dies ist ein Entwicklerhandbuch für Partner, die HP- und Lenovo-Garantieabfragen für ein Deployment über die REST-API anschalten möchten, anstatt die Nerdio Manager Intune Insights-Benutzeroberfläche zu verwenden.

Was sich damit steuern lässt

Garantieabfragen für HP- und Lenovo-Geräte werden bereits planmäßig ausgeführt, sobald ein gültiger Schlüssel für das Deployment vorhanden ist. Über diese API legen Sie diesen Schlüssel fest (oder entfernen ihn).

Integrationstyp

Anmeldedatenfelder (innerhalb von credentialsJson)

Anmerkungen

HpWarranty

apiKey, apiSecret

Beide Angaben sind erforderlich, damit der Synchronisierungs-Job HP aufrufen kann.

LenovoWarranty

clientId

Diese Angabe ist erforderlich, damit der Synchronisierungs-Job Lenovo aufrufen kann.

DellWarranty

Keine

Vollständig von Nerdio verwaltet. Es ist im Admin-Bildschirm schreibgeschützt und verfügt über keine Anmeldedatenfelder. Rufen Sie diese API nicht für DellWarranty auf; es gibt nichts einzustellen.

Die beiden Typ-Strings sind Teil des Vertrags und müssen exakt wie dargestellt geschrieben werden.

Wichtig

Bei diesen Strings wird zwischen Groß- und Kleinschreibung unterschieden. Beispiele finden Sie in der Tabelle unten.

Richtig

Falsch

HpWarranty

HPWarranty, HpWaranty, hp-warranty

LenovoWarranty

LenovoWaranty, lenovo-warranty

Weitere Informationen dazu, warum die Strings genau übereinstimmen müssen, finden Sie unten unter Zwei exakte Typ-Strings, keine Allow-List.

Authentifizierung

Alle Aufrufe verwenden Authorization: Bearer <jwt>, wobei das JWT aus demselben Verfahren zur Ausgabe von Admin-Token stammt, das Nerdio bereits für alle anderen Features für Partner nutzt:

POST /api/nerdio/issue-jwt/admin
ApiSecret: <shared secret>
Content-Type: application/json
 
{ "userEmail": "you@example.com", "userName": „Ihr Name“ }

Antwort: 200 OK

{ "jwt": "<admin JWT>" }

Die unten aufgeführten Integrations-Endpoints erfordern einen Instanz-Admin-User; diese Berechtigung ist im Admin-JWT bereits enthalten. Es ist keine weitere Berechtigungserteilung erforderlich.

1. Aktueller Status abrufen

GET /api/admin/integrations/{type}

Antwort: 200 OK

{
  "integrationId": 1,
  "integrationType": "HpWarranty",
  "isEnabled": true,
  "isConfigured": true,
  "configJson": null,
  "createdAt": "2026-09-01T19:13:09.6863181Z",
  "updatedAt": "2026-09-01T19:13:09.6863565Z"
}

isConfigured gibt an, ob eine Anmeldeinformation hinterlegt ist. Die Anmeldeinformation selbst wird von diesem oder einem anderen Endpoint niemals zurückgegeben.

Ein unbekannter oder nie erstellter {type} gibt 404 Not Found zurück.

Um alles aufzulisten, was für das Deployment konfiguriert ist:

GET /api/admin/integrations

Antwort: 200 OK, ein Array mit derselben Struktur, ein Eintrag pro Integrationstyp, der jemals gespeichert wurde (soft-gelöschte sind ausgeschlossen).

2. Integration anschalten und Anmeldedaten festlegen (oder ersetzen)

PUT /api/admin/integrations/{type}
Content-Type: application/json
 
{
  "integrationType": "HpWarranty",
  "isEnabled": true,
  "credentialsJson": "{\"apiKey\":\"...\",\"apiSecret\":\"...\"}"
}
PUT /api/admin/integrations/{type}
Content-Type: application/json
 
{
  "integrationType": "LenovoWarranty",
  "isEnabled": true,
  "credentialsJson": "{\"clientId\":\"...\"}"
}

Antwort: 200 OK, das resultierende IntegrationResponseDto (gleiche Struktur wie in Abschnitt 1).

Wichtig

Drei Dinge an diesem Body können leicht falsch gemacht werden:

  • integrationType ist im Body erforderlich, zusätzlich zur Angabe in der Route. Wird das Feld weggelassen, wird 400 mit {"errors":{"IntegrationType":["The IntegrationType field is required."]}} zurückgegeben. Sein Wert muss nicht mit der Route übereinstimmen (Nerdio Manager speichert und sucht immer anhand des Routenwerts), aber wenn Sie ihn ganz weglassen, schlägt die Validierung fehl. Senden Sie ihn daher jedes Mal mit.

  • credentialsJson ist ein String, der JSON enthält, kein verschachteltes JSON-Objekt. Der Admin-Bildschirm von Nerdio Manager selbst erstellt den Wert vor dem Senden mit JSON.stringify(...). Wenn Sie den Wert als echtes verschachteltes Objekt statt als String senden, erhalten Sie 400 mit "The JSON value could not be converted to System.String". Für einen rohen HTTP-Client gibt es hier keinen stillen Fehlermodus: Ein falsch geformtes credentialsJson wird sofort abgelehnt.

  • Das Weglassen von credentialsJson bei einer bestehenden Integration behält die zuvor gespeicherten Anmeldedaten bei. So schalten Sie isEnabled via PUT um, ohne das Geheimnis zum erneuten Senden zur Hand zu haben. Senden Sie credentialsJson nur, wenn Sie den gespeicherten Wert tatsächlich ersetzen möchten.

Dieser Aufruf ist ein Upsert: Das erste PUT für einen {type} erstellt ihn, jedes nachfolgende PUT aktualisiert dieselbe Zeile.

3. Integration ausschalten (oder wieder anschalten), ohne die Anmeldedaten zu ändern

PATCH /api/admin/integrations/{type}/toggle
Content-Type: application/json
 
{ "isEnabled": false }

Antwort: 204 No Content. Ein unbekannter {type} gibt 404 Not Found zurück.

4. Vollständig entfernen

DELETE /api/admin/integrations/{type}

Antwort: 204 No Content bei Erfolg, 404 Not Found, wenn für diesen Typ nichts gespeichert ist. Dies ist ein Soft-Delete: Ein erneuter Aufruf von PUT für denselben {type} erstellt einen brandneuen Datensatz (eine neue integrationId), der gelöschte wird nicht wiederhergestellt.

So sieht „es funktioniert nicht“ aus

Nerdio Manager hat keine Möglichkeit, einen HP- oder Lenovo-Schlüssel vor dem Speichern beim Anbieter zu überprüfen. Das Speichern eines falsch eingegebenen oder abgelaufenen Schlüssels wird sofort mit 200 OK und isConfigured: true erfolgreich abgeschlossen – mit genau derselben Antwort, die Sie für einen korrekten Schlüssel erhalten würden.

Der Fehler tritt später und unbemerkt auf: Die nächste geplante Synchronisierung versucht den Anbieteraufruf, dieser schlägt fehl und eine Warnung wird in das Hintergrund-Synchronisierungsprotokoll geschrieben. An den Aufrufer dieser API wird nichts zurückgegeben, und es erscheint keine sichtbare Fehlermeldung. Aus Sicht des Admins ist das einzige sichtbare Symptom, dass die Garantiedaten für diesen Anbieter auf den Geräten einfach nie aufgefüllt werden. Wenn das passiert, überprüfen Sie den Anmeldedatenwert selbst; dass der API-Aufruf 200 zurückgegeben hat, bedeutet nicht, dass der Schlüssel gültig ist.

Zwei exakte Typ-Strings, keine Allow-List

PUT validiert {type} nicht gegen eine bekannte Liste. PUT /api/admin/integrations/HPWaranty (mit Tippfehler) gibt 200 OK zurück und erstellt eine Zeile, die exakt wie eine korrekt geschriebene aussieht; es gibt kein 404, um den Fehler abzufangen.

Diese Zeile ist dann für den Synchronisierungsjob für immer unsichtbar. Der Lesepfad (GET/PUT/DELETE) gleicht {type} ohne Berücksichtigung der Groß-/Kleinschreibung mit der Datenbank ab, daher gibt GET /api/admin/integrations/hpwarranty problemlos die HpWarranty-Zeile zurück und lässt eine mit Tippfehler oder falscher Groß-/Kleinschreibung gespeicherte Zeile bei der Überprüfung in Ordnung aussehen. Der Synchronisierungsjob lädt jedoch aktivierte Integrationen und gleicht dann den Typ im Speicher durch einen exakten, die Groß- und Kleinschreibung berücksichtigenden String-Vergleich mit den Literalen "HpWarranty" und "LenovoWarranty" ab. Eine Zeile, die als HPWaranty, hpwarranty oder in einer anderen Variante gespeichert ist, besteht jede leseseitige Prüfung, wird aber bei jeder Synchronisierungsausführung stillschweigend übersprungen.

Wichtig

Es gibt nirgendwo in diesem Pfad einen Fehler: weder bei dem PUT, das die Zeile erstellt hat, noch bei einem späteren GET, noch beim Synchronisierungsjob (der einfach nichts findet, das übereinstimmt, und fortfährt). Die beiden Typ-Strings beim ersten Mal exakt richtig zu haben, ist die einzige Schutzmaßnahme, die heute existiert. Eine robustere und explizitere Fehlerberichterstattung ist für eine zukünftige Version geplant.

Fehler

Status

Wann

400 Bad Request

Fehlerhafter JSON-Body, credentialsJson als verschachteltes Objekt statt als String gesendet, isEnabled als nicht boolescher Wert gesendet oder integrationType fehlt im PUT-Body.

401 Nicht autorisiert

Fehlendes oder ungültiges Bearer-Token bei jedem /api/admin/integrations/*-Aufruf. Wird auch von /api/nerdio/issue-jwt/admin selbst zurückgegeben, wenn der ApiSecret-Header vorhanden ist, aber nicht übereinstimmt.

403 Unzulässig

Das Token ist gültig, aber der User ist kein Instanz-Admin.

404 Nicht gefunden

GET, PATCH .../toggle oder DELETE für einen {type}, für den kein Datensatz vorhanden ist. Bei einem unbekannten {type} gibt PUT kein Nicht zurück; siehe Zwei exakte Typzeichenfolgen, keine Zulassungsliste.

500 Interner Serverfehler

POST /api/nerdio/issue-jwt/admin mit einem vorhandenen, aber falschen ApiSecret-Header. Das vollständige Fehlen des Headers gibt stattdessen 400 zurück (ein Fehler bei der Validierung erforderlicher Header), aber ein vorhandener, jedoch inkorrekter Wert ist derzeit eine unbehandelte Ausnahme und kein sauberes 401.

Kurzreferenz

Aktion

Methode

Pfad

Textkörper

Einen Admin-JWT abrufen

POST

/api/nerdio/issue-jwt/admin

{ "userEmail": "...", "userName": "..." }, ApiSecret-Header

Alle Integrationen auflisten

GET

/api/admin/integrations

Keine

Status einer Integration abrufen

GET

/api/admin/integrations/{type}

Keine

Anschalten / Anmeldedaten festlegen

PUT

/api/admin/integrations/{type}

{ "integrationType": "...", "isEnabled": true, "credentialsJson": "..." }

Ausschalten / Anschalten, Anmeldedaten beibehalten

PATCH

/api/admin/integrations/{type}/toggle

{ "isEnabled": false }

Vollständig entfernen

LÖSCHEN ( )

/api/admin/integrations/{type}

Keine

{type} ist HpWarranty oder LenovoWarranty. Rufen Sie diese API nicht für DellWarranty auf.

War dieser Beitrag hilfreich?

0 von 0 fanden dies hilfreich
Haben Sie Fragen? Anfrage einreichen

Kommentare (0 Kommentare)

Zu diesem Beitrag können keine Kommentare hinterlassen werden.