Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Claim-API

Lizenzierte Geräte aus einem Programm in Ihre Organisation beanspruchen, ihren Besitz lesen und sie freigeben, mit einer Erklärung jedes Ablehnungscodes.

Diese Seite richtet sich an Integratoren, die lizenzierte Router, Gateways und Controller aus ihren eigenen Werkzeugen heraus einer Organisation hinzufügen, zum Beispiel über eine Installations-App oder ein Inbetriebnahme-Skript. Die Schritte in der App stehen unter Geräte hinzufügen und beanspruchen; wie das Beanspruchen geschützt ist, steht unter Geräteidentität und Sicherheit beim Beanspruchen.

Pfade liegen unter https://<your host>/tenant/<tenantId>. Die Konventionen stehen unter REST-API-Grundlagen.

Bevor Sie aufrufen

Ein lizenziertes Gerät kann nur beansprucht werden, solange jemand am Gerät ist:

  1. Das Gerät ist mit dem Internet verbunden und seine Cloud-Verbindung ist eingeschaltet.
  2. Jemand öffnet das Beanspruchungsfenster auf der eigenen Cloud-Seite des Geräts. Das Fenster bleibt höchstens 15 Minuten offen und schließt sich nach einem erfolgreichen Beanspruchen.
  3. Ihr Programm sendet die Seriennummer und den Beanspruchungscode des Geräts, solange das Fenster offen ist.

Es gibt keinen Aufruf zum Öffnen des Beanspruchungsfensters: Es wird nur am Gerät geöffnet.

Aufrufe

MethodePfadBerechtigungFunktion
POST/api/iot/claimiot_provisioning.claimEin Gerät beanspruchen oder mit einem Probelauf prüfen
GET/api/iot/devices/{deviceId}/ownershipiot_provisioning.claimHerkunft eines Geräts, sein Zertifikat und seine Freigabeeinstellung
PATCH/api/iot/devices/{deviceId}/ownershipiot_provisioning.releaseFreigabe über die eigene Seite des Geräts erlauben oder unterbinden
POST/api/iot/claim/release/{deviceId}iot_provisioning.releaseEin Gerät zurück in den Werkspool freigeben

Alle vier sind standardmäßig Admin-Berechtigungen. Wenn das beanspruchte Gerät im selben Aufruf an einen Standort oder ein Asset gebunden wird, wird zusätzlich iot_asset.relations.manage am Schlüssel benötigt.

Ein Gerät beanspruchen

POST /api/iot/claim

FeldRegel
serialPflicht. 6 bis 32 Buchstaben, Ziffern und Bindestriche; Groß- und Kleinschreibung spielen keine Rolle
secretPflicht. Der 20-stellige Beanspruchungscode von der Cloud-Seite des Geräts. Bindestriche, Leerzeichen und Groß- und Kleinschreibung werden ignoriert; O wird als 0 gelesen, I und L als 1
nameOptional, 1 bis 128 Zeichen. Standard: die Seriennummer
iotAssetIdOptional. Der Standort oder das Asset, an das das Gerät gebunden wird
dryRunOptional. true prüft alles und beansprucht nichts

Der Body ist streng: Ein unbekanntes Feld ergibt ein 400. Der Beanspruchungscode wird nie zurückgesendet.

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"serial":"RT420-2610-000123","secret":"7KQ2-M9XH-D4TB-6WRA-1NZC","name":"Pump house router","iotAssetId":"8d0e…"}'
{
  "status": "claimed",
  "serial": "RT420-2610-000123",
  "deviceId": "6f1c…",
  "model": "…",
  "profileId": "a1b2…",
  "name": "Pump house router",
  "renamed": false,
  "placement": "placed"
}

Antworten

StatusstatusBedeutung
201claimedDas Gerät gehört jetzt Ihnen
200claimed mit alreadyOwned: trueIhre Organisation besitzt es bereits; nichts hat sich geändert
200claimableEin Probelauf war erfolgreich; die Antwort enthält serial, model, type und hw
200in_progressEin Beanspruchen dieses Geräts läuft gerade; lesen Sie die Geräteliste in Kürze erneut

Weitere Felder einer Beanspruchung:

FeldBedeutung
name, renamedDer Name des Geräts. Existiert bereits ein Gerät mit diesem Namen, wird eine Nummer angehängt (Pump house router (2)) und renamed ist true
recreatedtrue, wenn Ihre Organisation das Gerät besaß, sein Gerätedatensatz aber gelöscht worden war; er wurde neu angelegt
placementNur wenn iotAssetId gesendet wurde: placed, not_permitted (dem Schlüssel fehlt iot_asset.relations.manage), unavailable (Standorte und Assets sind deaktiviert) oder failed. Die Beanspruchung bleibt in jedem Fall bestehen

Ein beanspruchtes Gerät erhält eine Kopie des Geräteprofils seines Modells und sein Werkszertifikat als X.509-Zugangsdaten und verbindet sich innerhalb von Sekunden erneut mit Ihrer Organisation. Es wird ein Webhook-Ereignis iot.device.claimed gesendet (siehe Referenz der Webhook-Ereignisse).

Ablehnungen

Jede Ablehnung trägt einen von fünf Codes in details.reason. Verzweigen Sie auf diesen Code, nicht auf die Meldung.

details.reasonStatuscodeMeldungWas zu tun ist
not_claimable409CONFLICTDieses Gerät kann nicht hinzugefügt werden. Prüfen Sie die Seriennummer; ist sie richtig, gehört das Gerät einem anderen Konto: Bitten Sie den Verkäufer, es freizugeben.Prüfen Sie die Seriennummer. Eine unbekannte Seriennummer, ein ausgemustertes Gerät und ein Gerät einer anderen Organisation liefern alle diese Antwort; der Eigentümer wird nie genannt
press_claim_button409CONFLICTÖffnen Sie das Beanspruchungsfenster auf der Cloud-Seite des Geräts (es bleibt 15 Minuten offen) und versuchen Sie es dann erneut.Fenster am Gerät öffnen und erneut versuchen
bad_secret400VALIDATION_ERRORDie Seriennummer oder der Beanspruchungscode ist nicht korrekt.Den Code auf der Cloud-Seite erneut ablesen
rate_limited429RATE_LIMIT_EXCEEDEDZu viele Versuche. Versuchen Sie es später erneut.Warten; siehe die Versuchsgrenzen unten
device_limit403FEATURE_NOT_AVAILABLEDas Geräte-Limit dieses Kontos ist erreicht.Ein Gerät entfernen oder den Tarif ändern

Solange das Beanspruchungsfenster geschlossen ist, wird der Beanspruchungscode gar nicht geprüft; ein geschlossenes Fenster verrät daher nie, ob ein Code richtig war. Das Geräte-Limit wird zuletzt geprüft, bevor etwas angelegt wird.

Versuchsgrenzen

Fehlgeschlagene Versuche (eine unbekannte Seriennummer, ein geschlossenes Beanspruchungsfenster, ein falscher Code) werden über eine gleitende Stunde gezählt. Ist eine dieser Grenzen erreicht, liefern die davon betroffenen Versuche rate_limited:

Gezählt proGrenze pro Stunde
Seriennummer5 falsche Beanspruchungscodes
Mitglied20 fehlgeschlagene Versuche (bei einem Schlüssel: der Inhaber des Schlüssels)
Aufrufende Adresse30 fehlgeschlagene Versuche

Ein Probelauf führt dieselben Prüfungen durch, und ein fehlgeschlagener Probelauf zählt wie ein fehlgeschlagenes Beanspruchen. Testen Sie keine Codes in einer Schleife: Fünf falsche Codes sperren die Seriennummer für die Stunde.

Besitz

GET /api/iot/devices/{deviceId}/ownership antwortet mit { ownership, capabilities }. Bei einem beanspruchten Gerät hat ownership fromPool: true, serial, model, claimedAt, claimedByUserId, certificate (status, notAfter), allowDeviceRelease und blockers (was noch auf das Gerät verweist). Ein in Ihrer Organisation angelegtes Gerät antwortet mit fromPool: false. Der Name des Beanspruchenden (claimedBy) erfordert eine Mitgliederberechtigung, die Schlüssel nie besitzen; ein Schlüssel erhält daher nur die ID.

PATCH mit { "allowDeviceRelease": false } verhindert, dass jemand das Gerät mit dem Button auf seiner eigenen Cloud-Seite freigibt. Der Standardwert ist true.

Ein Gerät freigeben

POST /api/iot/claim/release/{deviceId} mit { "confirmSerial": "RT420-2610-000123", "reason": "Returned to supplier" } (reason bis zu 500 Zeichen) gibt das Gerät in den Werkspool zurück. Die Antwort lautet 200 { serial, unitStatus, certificateKept }. Seine Daten bleiben in Ihrer Organisation; der nächste Eigentümer muss am Gerät sein, um es zu beanspruchen. Es wird ein Webhook-Ereignis iot.device.released gesendet.

Statusdetails.reasonBedeutung
400confirm_mismatch„Geben Sie die Seriennummer des Geräts genau ein, um zu bestätigen.“
404not_from_pool„Dieses Gerät wurde nicht aus dem Werkspool hinzugefügt.“
409still_referencedEtwas verweist noch auf das Gerät, zum Beispiel ein Standort oder ein Asset, an dem es platziert ist; details.moduleId und details.count nennen, was es ist. Entfernen Sie das zuerst