Códigos QR de aprovisionamento

Crie um código QR que inscreva um dispositivo Android novo ou restaurado para os valores de fábrica na sua empresa com uma determinada política.

Como funciona

Cada pedido cria um novo token de inscrição para a política e devolve um código QR que o inclui. O código deixa de funcionar 24 horas após a sua criação; a resposta indica a hora exata em expiresAt. Crie um código quando alguém estiver prestes a configurar dispositivos e crie um novo em vez de reutilizar um antigo.

Para utilizar o código, toque seis vezes no ecrã de boas-vindas do assistente de configuração do dispositivo, ligue-se ao Wi-Fi se solicitado e leia o código. Um dispositivo só pode ser inscrito desta forma quando for novo ou tiver sido restaurado para os valores de fábrica.

As políticas exclusivas de RV não podem ser aprovisionadas com um código QR: os respetivos dispositivos são aprovisionados com o Nomid Ops através de USB.

Requisitos

Uma chave de API com a permissão PROVISIONING, combinada com POLICIES_READ. Apenas um utilizador do portal com permissão para aprovisionar dispositivos e com acesso a todas as políticas pode criar uma chave com PROVISIONING.
A empresa deve ter concluído a respetiva inscrição no Android Enterprise.
Os clientes MCP que se ligam através de Sign in with Nomid em vez de uma chave de API necessitam do âmbito mcp:provisioning, e a definição de aprovisionamento da empresa em "Acesso a agentes de IA" no portal deve estar ativada.

Endpoint

O caminho é relativo ao URL base da API e requer o cabeçalho X-API-Key. Um pedido com êxito devolve 201 Created.

Método	Endpoint	Descrição
POST	/policies/{policyId}/provisioning-qr-codes	Criar um código QR de aprovisionamento para uma política, com um novo token de inscrição

Corpo do pedido

Todos os campos são opcionais: envie um objeto JSON vazio para obter um código sem Wi-Fi e com a utilização pessoal predefinida. Um campo desconhecido devolve 400.

Campo	Valores	Descrição
personalUsage	UNSPECIFIED, ALLOWED, DISALLOWED, USERLESS	Como o dispositivo é utilizado: ALLOWED para um perfil de trabalho num dispositivo de propriedade pessoal, DISALLOWED para um dispositivo totalmente gerido e pertencente à empresa, USERLESS para um dispositivo dedicado sem conta de utilizador. UNSPECIFIED é a predefinição quando omitido.
wifiSsid		Uma rede Wi-Fi à qual o dispositivo se liga durante a configuração. Até 32 bytes em UTF-8. Os espaços em redor são mantidos como parte do nome.
wifiPassword		A palavra-passe de wifiSsid, até 63 bytes em UTF-8. Uma palavra-passe WPA tem pelo menos 8 bytes. Uma chave WEP tem 5 ou 13 carateres ASCII, ou 10 ou 26 dígitos hexadecimais. Nunca é devolvida.
wifiSecurity	NONE, WPA, WEP	A segurança de wifiSsid. Assume o valor predefinido WPA quando é fornecida uma palavra-passe e NONE caso contrário. NONE não requer palavra-passe, e WPA e WEP necessitam de uma.
wifiHidden		Indica se wifiSsid é uma rede oculta. O valor predefinido é false.

wifiPassword, wifiSecurity e wifiHidden necessitam de wifiSsid.

Resposta

Campo	Descrição
policyId	O nome do caminho da política, o policyId com o qual os dispositivos são registados.
policyName	O nome a apresentar da política.
personalUsage	O modo de utilização pessoal do token de registo.
expiresAt	Quando o código QR deixa de registar dispositivos.
wifiSsid	A rede Wi-Fi à qual o dispositivo se liga durante a configuração. Omitido quando nenhuma tiver sido fornecida.
image	A imagem do código QR: mimeType (image/png) e data, os bytes da imagem em base64.
portalUrl	Uma ligação para a política no portal Nomid.

Exemplo

Crie um código para um dispositivo totalmente gerido que se ligue a uma rede WPA durante a configuração. O jq compõe o corpo a partir de uma variável de ambiente, garantindo que a palavra-passe é corretamente escapada e não fica registada no histórico da sua 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"
}

Descodifique data a partir de base64 para obter o PNG. Os dados da imagem foram encurtados aqui.

Erro: política apenas para RV

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
}

Erros

Assim que a chave de API for autenticada, os erros usam application/problem+json com dois campos adicionais: code, um identificador estável para ramificação, e retryable, que indica se o mesmo pedido pode ser enviado novamente. Um corpo que não possa ser lido é a exceção, descrita na linha 400. Uma chave em falta ou inválida recebe a resposta 401 partilhada, um pequeno objeto JSON com error, message e status. A ferramenta MCP devolve os mesmos code e message como um erro da ferramenta.

Estado	Código	Significado
400	invalid_arguments	Uma opção é inválida: um valor personalUsage ou wifiSecurity desconhecido, um campo de Wi-Fi sem wifiSsid, ou um nome, palavra-passe ou segurança de Wi-Fi que não esteja em conformidade com as regras acima. O detalhe indica qual. Um corpo que não seja JSON válido, ou que tenha um campo desconhecido, também devolve 400, como detalhes do problema sem code ou retryable.
401	-	A chave de API está em falta, inválida, expirada ou revogada.
403	forbidden	A chave não tem PROVISIONING ou POLICIES_READ.
404	not_found	Nenhuma política com este policyId na empresa da chave.
409	unsupported	A política não pode aprovisionar dispositivos com um código QR: é uma política apenas de RV ou a empresa não concluiu a respetiva inscrição no Android Enterprise.
422	refused	A política foi eliminada.
429	rate_limited	Demasiados pedidos de escrita para esta chave. O cabeçalho Retry-After e os detalhes indicam os segundos a aguardar. retryable é true.
502	provider_error	A Google não criou o token de inscrição. Nenhum código QR foi criado. retryable é true: tente novamente dentro de momentos.

Limites de pedidos

Cada pedido conta para o limite de escrita de 10 pedidos por minuto por chave, partilhado com os endpoints de comandos de dispositivos e de alteração de políticas e as ferramentas de escrita do MCP. Uma ligação com o Sign in with Nomid que chame create_provisioning_qr_code consome o mesmo limite, contabilizado por ligação. Os pedidos que falhem nas verificações de permissões ou na validação de argumentos não contam.

Ferramenta MCP

A ferramenta MCP create_provisioning_qr_code aceita as mesmas opções, com o policyId como argumento. Devolve o código QR como um bloco de imagem do MCP, para que o assistente o possa mostrar ao utilizador sem o ler.

Servidor MCP