Κωδικοί QR προετοιμασίας (provisioning)

Δημιουργήστε έναν κωδικό QR που εγγράφει μια νέα ή επαναφερμένη στις εργοστασιακές ρυθμίσεις συσκευή Android στην εταιρεία σας με μια συγκεκριμένη πολιτική.

Πώς λειτουργεί

Κάθε αίτημα δημιουργεί ένα νέο διακριτικό εγγραφής για την πολιτική και επιστρέφει έναν κωδικό QR που το περιέχει. Ο κωδικός παύει να λειτουργεί 24 ώρες μετά τη δημιουργία του· η απόκριση παρέχει την ακριβή ώρα στο expiresAt. Δημιουργήστε έναν κωδικό όταν κάποιος πρόκειται να ρυθμίσει συσκευές, και δημιουργήστε έναν νέο αντί να επαναχρησιμοποιήσετε έναν παλαιότερο.

Για να χρησιμοποιήσετε τον κωδικό, πατήστε στην οθόνη υποδοχής του οδηγού ρύθμισης της συσκευής έξι φορές, συνδεθείτε σε Wi-Fi εάν σας ζητηθεί, και σαρώστε τον. Μια συσκευή μπορεί να εγγραφεί με αυτόν τον τρόπο μόνο όταν είναι καινούργια ή έχει επαναφερθεί στις εργοστασιακές ρυθμίσεις.

Οι πολιτικές αποκλειστικά για VR δεν μπορούν να προετοιμαστούν με κωδικό QR: οι συσκευές τους προετοιμάζονται με το Nomid Ops μέσω USB.

Απαιτήσεις

Ένα κλειδί API με το δικαίωμα PROVISIONING, σε συνδυασμό με το POLICIES_READ. Μόνο ένας χρήστης της πύλης στον οποίο επιτρέπεται να προετοιμάζει συσκευές και έχει πρόσβαση σε όλες τις πολιτικές μπορεί να δημιουργήσει ένα κλειδί με το PROVISIONING.
Η εταιρεία πρέπει να έχει ολοκληρώσει την εγγραφή της στο Android Enterprise.
Οι πελάτες MCP που συνδέονται με το Sign in with Nomid αντί για κλειδί API χρειάζονται το εύρος mcp:provisioning, και η ρύθμιση προετοιμασίας (provisioning) της εταιρείας στην ενότητα πρόσβασης εκπροσώπου AI στην πύλη πρέπει να είναι ενεργοποιημένη.

Τελικό σημείο

Η διαδρομή είναι σχετική με τη βασική διεύθυνση URL του API και απαιτεί την κεφαλίδα X-API-Key. Ένα επιτυχές αίτημα επιστρέφει 201 Created.

Μέθοδος	Endpoint	Περιγραφή
POST	/policies/{policyId}/provisioning-qr-codes	Δημιουργήστε έναν κωδικό QR προετοιμασίας για μια πολιτική, με ένα νέο διακριτικό εγγραφής

Σώμα αιτήματος

Κάθε πεδίο είναι προαιρετικό: στείλτε ένα κενό αντικείμενο JSON για έναν κωδικό χωρίς Wi-Fi και με την προεπιλεγμένη προσωπική χρήση. Ένα άγνωστο πεδίο επιστρέφει 400.

Πεδίο	Τιμές	Περιγραφή
personalUsage	UNSPECIFIED, ALLOWED, DISALLOWED, USERLESS	Πώς χρησιμοποιείται η συσκευή: ALLOWED για προφίλ εργασίας σε συσκευή προσωπικής ιδιοκτησίας, DISALLOWED για πλήρως διαχειριζόμενη συσκευή εταιρικής ιδιοκτησίας, USERLESS για αποκλειστική συσκευή χωρίς λογαριασμό χρήστη. Το UNSPECIFIED είναι η προεπιλογή όταν παραλείπεται.
wifiSsid		Ένα δίκτυο Wi-Fi στο οποίο συνδέεται η συσκευή κατά τη ρύθμιση. Έως 32 byte σε UTF-8. Τα κενά διαστήματα γύρω από αυτό διατηρούνται ως μέρος του ονόματος.
wifiPassword		Ο κωδικός πρόσβασης του wifiSsid, έως 63 byte σε UTF-8. Ένας κωδικός πρόσβασης WPA έχει τουλάχιστον 8 byte. Ένα κλειδί WEP αποτελείται από 5 ή 13 χαρακτήρες ASCII ή 10 ή 26 δεκαεξαδικά ψηφία. Δεν επιστρέφεται ποτέ.
wifiSecurity	NONE, WPA, WEP	Η ασφάλεια του wifiSsid. Η προεπιλογή είναι WPA όταν δίνεται κωδικός πρόσβασης και NONE διαφορετικά. Το NONE δεν δέχεται κωδικό πρόσβασης, ενώ τα WPA και WEP απαιτούν έναν.
wifiHidden		Το αν το wifiSsid είναι κρυφό δίκτυο. Η προεπιλογή είναι false.

Τα wifiPassword, wifiSecurity και wifiHidden απαιτούν το wifiSsid.

Απόκριση

Πεδίο	Περιγραφή
policyId	Το όνομα διαδρομής της πολιτικής, το policyId με το οποίο εγγράφονται οι συσκευές.
policyName	Το όνομα εμφάνισης της πολιτικής.
personalUsage	Η λειτουργία προσωπικής χρήσης του διακριτικού εγγραφής.
expiresAt	Πότε ο κωδικός QR σταματά να εγγράφει συσκευές.
wifiSsid	Το δίκτυο Wi-Fi στο οποίο συνδέεται η συσκευή κατά τη ρύθμιση. Παραλείπεται όταν δεν έχει οριστεί κανένα.
image	Η εικόνα του κωδικού QR: mimeType (image/png) και data, τα byte της εικόνας σε base64.
portalUrl	Ένας σύνδεσμος προς την πολιτική στην πύλη Nomid.

Παράδειγμα

Δημιουργήστε έναν κωδικό για μια πλήρως διαχειριζόμενη συσκευή που συνδέεται σε δίκτυο WPA κατά τη ρύθμιση. Το jq δημιουργεί το σώμα από μια μεταβλητή περιβάλλοντος, ώστε να γίνεται σωστά διαφυγή του κωδικού πρόσβασης και να μην καταλήγει στο ιστορικό του shell σας.

curl -X POST "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/provisioning-qr-codes" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg password "$WIFI_PASSWORD" \
    '{personalUsage: "DISALLOWED", wifiSsid: "Warehouse", wifiPassword: $password}')"

HTTP/1.1 201 Created

{
  "policyId": "p7k2m9qa4xz",
  "policyName": "Warehouse scanners",
  "personalUsage": "DISALLOWED",
  "expiresAt": "2026-10-11T14:30:00Z",
  "wifiSsid": "Warehouse",
  "image": {
    "mimeType": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "portalUrl": "https://portal.nomid.tech/#/acme/acme/policy/p7k2m9qa4xz"
}

Αποκωδικοποιήστε το πεδίο data από base64 για να λάβετε το PNG. Τα δεδομένα εικόνας έχουν συντομευτεί εδώ.

Σφάλμα: Πολιτική μόνο για VR

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Policy q4vr8headset is a VR-only policy: its devices are provisioned with Nomid Ops over USB, not with a QR code.",
  "instance": "/emm/api/v1/policies/q4vr8headset/provisioning-qr-codes",
  "code": "unsupported",
  "retryable": false
}

Σφάλματα

Μόλις επικυρωθεί το κλειδί API, τα σφάλματα χρησιμοποιούν το application/problem+json με δύο επιπλέον πεδία: code, ένα σταθερό αναγνωριστικό για διακλάδωση, και retryable, το οποίο δηλώνει εάν το ίδιο αίτημα μπορεί να σταλεί ξανά. Ένα σώμα που δεν μπορεί να διαβαστεί αποτελεί εξαίρεση, η οποία περιγράφεται στη γραμμή 400. Ένα κλειδί που λείπει ή δεν είναι έγκυρο λαμβάνει την κοινόχρηστη απόκριση 401, ένα μικρό αντικείμενο JSON με error, message και status. Το εργαλείο MCP επιστρέφει τον ίδιο κωδικό και μήνυμα ως σφάλμα εργαλείου.

Κατάσταση	Κωδικός	Σημασία
400	invalid_arguments	Μια επιλογή δεν είναι έγκυρη: μια άγνωστη τιμή personalUsage ή wifiSecurity, ένα πεδίο Wi-Fi χωρίς wifiSsid, ή ένα όνομα, κωδικός πρόσβασης ή ασφάλεια Wi-Fi που δεν συμμορφώνεται με τους παραπάνω κανόνες. Η λεπτομέρεια αναφέρει ποιο. Ένα σώμα που δεν είναι έγκυρο JSON, ή που περιέχει ένα άγνωστο πεδίο, επιστρέφει επίσης 400, ως λεπτομέρειες προβλήματος χωρίς code ή retryable.
401	-	Το κλειδί API λείπει, δεν είναι έγκυρο, έχει λήξει ή έχει ανακληθεί.
403	forbidden	Το κλειδί δεν διαθέτει PROVISIONING ή POLICIES_READ.
404	not_found	Δεν υπάρχει πολιτική με αυτό το policyId στην εταιρεία του κλειδιού.
409	unsupported	Η πολιτική δεν μπορεί να διαμορφώσει συσκευές με κωδικό QR: είναι πολιτική μόνο για VR ή η εταιρεία δεν έχει ολοκληρώσει την εγγραφή της στο Android Enterprise.
422	refused	Η πολιτική διαγράφηκε.
429	rate_limited	Πάρα πολλά αιτήματα εγγραφής για αυτό το κλειδί. Η κεφαλίδα Retry-After και οι λεπτομέρειες παρέχουν τα δευτερόλεπτα αναμονής. Το retryable είναι true.
502	provider_error	Η Google δεν δημιούργησε το διακριτικό εγγραφής. Δεν δημιουργήθηκε κωδικός QR. Το retryable είναι true: δοκιμάστε ξανά σε λίγο.

Όρια ρυθμού

Κάθε αίτημα προσμετράται στο όριο εγγραφής των 10 αιτημάτων ανά λεπτό ανά κλειδί, το οποίο είναι κοινό με τα τελικά σημεία εντολών συσκευής και αλλαγής πολιτικής, καθώς και με τα εργαλεία εγγραφής MCP. Μια σύνδεση Sign in with Nomid που καλεί το create_provisioning_qr_code καταναλώνει το ίδιο όριο, το οποίο υπολογίζεται ανά σύνδεση. Τα αιτήματα που αποτυγχάνουν στους ελέγχους δικαιωμάτων ή στην επικύρωση ορισμάτων δεν προσμετρώνται.

Εργαλείο MCP

Το εργαλείο MCP create_provisioning_qr_code δέχεται τις ίδιες επιλογές, με το policyId ως όρισμα. Επιστρέφει τον κωδικό QR ως μπλοκ εικόνας MCP, ώστε ο βοηθός να μπορεί να τον εμφανίσει στον χρήστη χωρίς να τον διαβάσει.

Διακομιστής MCP