Kody QR do aprowizacji

Jak to działa

Każde żądanie tworzy nowy token rejestracji dla zasady i zwraca kod QR, który go zawiera. Kod przestaje działać po 24 godz. od jego utworzenia; odpowiedź podaje dokładny czas w expiresAt. Utwórz kod, gdy ktoś ma właśnie konfigurować urządzenia, i twórz nowy zamiast używać starszego ponownie.

Aby użyć kodu, dotknij sześć razy ekranu powitalnego kreatora konfiguracji urządzenia, połącz się z Wi-Fi, jeśli pojawi się monit, i zeskanuj go. Urządzenie można zarejestrować w ten sposób tylko wtedy, gdy jest nowe lub zostało zresetowane do ustawień fabrycznych.

Zasady przeznaczone wyłącznie dla VR nie mogą być aprowizowane za pomocą kodu QR: ich urządzenia są aprowizowane za pomocą Nomid Ops przez USB.

Wymagania

• Klucz API z uprawnieniem PROVISIONING, połączonym z POLICIES_READ. Tylko użytkownik portalu, który ma uprawnienia do aprowizacji urządzeń i dostęp do wszystkich zasad, może utworzyć klucz z PROVISIONING.
• Firma musi ukończyć rejestrację w programie Android Enterprise.
• Klienci MCP, którzy łączą się za pomocą Sign in with Nomid zamiast klucza API, wymagają zakresu mcp:provisioning, a ustawienie aprowizacji firmy w sekcji AI agent access w portalu musi być włączone.

Punkt końcowy

Ścieżka jest względna względem bazowego adresu URL API i wymaga nagłówka X-API-Key. Pomyślne żądanie zwraca 201 Created.

Treść żądania

Każde pole jest opcjonalne: prześlij pusty obiekt JSON dla kodu bez Wi-Fi i z domyślnym użytkiem osobistym. Nieznane pole zwraca 400.

Pola wifiPassword, wifiSecurity i wifiHidden wymagają wifiSsid.

Odpowiedź

Przykład

Utwórz kod dla w pełni zarządzanego urządzenia, które łączy się z siecią WPA podczas konfiguracji. Narzędzie jq tworzy treść żądania ze zmiennej środowiskowej, dzięki czemu hasło jest prawidłowo poprzedzane znakami ucieczki i nie trafia do historii powłoki.

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"
}

Zdekoduj data z base64, aby uzyskać plik PNG. Dane obrazu zostały tutaj skrócone.

Błąd: zasady tylko dla 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
}

Błędy

Po uwierzytelnieniu klucza API błędy używają typu application/problem+json z dwoma dodatkowymi polami: code, stabilnym identyfikatorem do obsługi warunkowej, oraz retryable, które informuje, czy to samo żądanie może zostać wysłane ponownie. Treść, której nie można odczytać, jest wyjątkiem opisanym w wierszu 400. Brakujący lub nieprawidłowy klucz otrzymuje wspólną odpowiedź 401 — mały obiekt JSON z polami error, message i status. Narzędzie MCP zwraca ten sam kod i komunikat jako błąd narzędzia.

Limity żądań

Każde żądanie wlicza się do limitu zapisu wynoszącego 10 żądań na minutę na klucz, dzielonego z punktami końcowymi poleceń urządzeń i zmian polityk oraz narzędziami zapisu MCP. Połączenie Sign in with Nomid wywołujące create_provisioning_qr_code zużywa ten sam limit, liczony na połączenie. Żądania, które nie przejdą weryfikacji uprawnień lub walidacji argumentów, nie są wliczane.

Narzędzie MCP

Narzędzie MCP create_provisioning_qr_code przyjmuje te same opcje, z policyId jako argumentem. Zwraca kod QR jako blok obrazu MCP, dzięki czemu asystent może wyświetlić go użytkownikowi bez konieczności jego odczytywania.

Serwer MCP