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:
- Das Gerät ist mit dem Internet verbunden und seine Cloud-Verbindung ist eingeschaltet.
- 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.
- 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
| Methode | Pfad | Berechtigung | Funktion |
|---|---|---|---|
| POST | /api/iot/claim | iot_provisioning.claim | Ein Gerät beanspruchen oder mit einem Probelauf prüfen |
| GET | /api/iot/devices/{deviceId}/ownership | iot_provisioning.claim | Herkunft eines Geräts, sein Zertifikat und seine Freigabeeinstellung |
| PATCH | /api/iot/devices/{deviceId}/ownership | iot_provisioning.release | Freigabe über die eigene Seite des Geräts erlauben oder unterbinden |
| POST | /api/iot/claim/release/{deviceId} | iot_provisioning.release | Ein 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
| Feld | Regel |
|---|---|
serial | Pflicht. 6 bis 32 Buchstaben, Ziffern und Bindestriche; Groß- und Kleinschreibung spielen keine Rolle |
secret | Pflicht. 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 |
name | Optional, 1 bis 128 Zeichen. Standard: die Seriennummer |
iotAssetId | Optional. Der Standort oder das Asset, an das das Gerät gebunden wird |
dryRun | Optional. 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
| Status | status | Bedeutung |
|---|---|---|
| 201 | claimed | Das Gerät gehört jetzt Ihnen |
| 200 | claimed mit alreadyOwned: true | Ihre Organisation besitzt es bereits; nichts hat sich geändert |
| 200 | claimable | Ein Probelauf war erfolgreich; die Antwort enthält serial, model, type und hw |
| 200 | in_progress | Ein Beanspruchen dieses Geräts läuft gerade; lesen Sie die Geräteliste in Kürze erneut |
Weitere Felder einer Beanspruchung:
| Feld | Bedeutung |
|---|---|
name, renamed | Der 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 |
recreated | true, wenn Ihre Organisation das Gerät besaß, sein Gerätedatensatz aber gelöscht worden war; er wurde neu angelegt |
placement | Nur 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.reason | Status | code | Meldung | Was zu tun ist |
|---|---|---|---|---|
not_claimable | 409 | CONFLICT | Dieses 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_button | 409 | CONFLICT | Ö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_secret | 400 | VALIDATION_ERROR | Die Seriennummer oder der Beanspruchungscode ist nicht korrekt. | Den Code auf der Cloud-Seite erneut ablesen |
rate_limited | 429 | RATE_LIMIT_EXCEEDED | Zu viele Versuche. Versuchen Sie es später erneut. | Warten; siehe die Versuchsgrenzen unten |
device_limit | 403 | FEATURE_NOT_AVAILABLE | Das 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 pro | Grenze pro Stunde |
|---|---|
| Seriennummer | 5 falsche Beanspruchungscodes |
| Mitglied | 20 fehlgeschlagene Versuche (bei einem Schlüssel: der Inhaber des Schlüssels) |
| Aufrufende Adresse | 30 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.
| Status | details.reason | Bedeutung |
|---|---|---|
| 400 | confirm_mismatch | „Geben Sie die Seriennummer des Geräts genau ein, um zu bestätigen.“ |
| 404 | not_from_pool | „Dieses Gerät wurde nicht aus dem Werkspool hinzugefügt.“ |
| 409 | still_referenced | Etwas 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 |

