Perguntas frequentes

Esta página organiza os problemas mais comuns durante a integração. Comece pelo sintoma mais parecido com o que você está vendo; os esquemas de endpoint, parâmetros e listas completas de erros ficam na documentação de referência.

Buscar por sintoma

O que você vê	Comece aqui
Você não tem uma API key e não sabe onde criar uma	A chamada à API ainda não funciona
A emissão do token falha, ou as requisições retornam 401 / 403	A chamada à API ainda não funciona
Falta um dispositivo, ou seu estado não parece atual	Os dados do dispositivo não parecem corretos
Você quer monitorar continuamente periféricos, desconexões ou quedas de energia	Os dados do dispositivo não parecem corretos
Um comando foi aceito, mas o dispositivo não respondeu ou deu timeout	Uma operação não terminou como esperado
O WebSocket não conecta, desconecta com frequência ou perde eventos	A conexão em tempo real está instável
Você não sabe se deve usar REST API ou WebSocket	REST API ou WebSocket
As requisições retornam 429, 503 ou gateway indisponível	As requisições estão limitadas ou o serviço está temporariamente indisponível
O problema continua depois de seguir a documentação	Prepare os dados para o suporte

A chamada à API ainda não funciona

Como crio um API Client e obtenho credenciais?

Crie um API Client no Developer Console do WLTE.

1. Entre no Developer Console: https://developer.svnwi.com/wlte
2. Abra uma aplicação e vá para o gerenciamento de API Client.
3. Crie um API Client e selecione as permissões mínimas exigidas pela integração.
4. Guarde o clientId e o clientSecret gerados.

Ao criar um API Client você obtém um clientId e um clientSecret, usados juntos para conseguir um access token.

O clientSecret só é exibido na criação ou na rotação. Guarde-o imediatamente no armazenamento de segredos do seu servidor. Se você o perder, rotacione o segredo, porque o valor original não pode ser visualizado novamente. Veja Obter API Keys.

A emissão do access token falha

Verifique estes itens em ordem:

1. O API Client existe e está ativo.
2. O clientId e o clientSecret pertencem ao mesmo cliente.
3. A aplicação e a conta estão ativas.
4. A URL, o método e o corpo da requisição coincidem com Criar access token (em inglês).

Não tente credenciais inválidas repetidamente sem limite, porque a autenticação também tem limites de taxa.

O code da resposta é AUTH_INVALID

As credenciais, ou o estado atual do seu proprietário, são inválidos. As causas comuns são credenciais incorretas, um API Client desativado ou excluído, uma aplicação desativada ou uma conta em estado inválido.

Se você acabou de rotacionar o segredo, verifique se está usando o novo. Ramifique pelo code, não pelo message.

O code da resposta é AUTH_SCOPE_DENIED

O API Client não tem a permissão exigida pelo endpoint. data.requiredScope identifica a permissão que falta.

Adicione essa permissão no Developer Console, salve a alteração, obtenha um token novo e tente novamente. Veja Permissões (em inglês).

Um token antigo ainda pode ser usado depois que um API Client é desativado ou excluído?

Não. Os endpoints protegidos validam o estado atual do API Client, da aplicação e da conta, não apenas a expiração do JWT.

Depois que o cliente é desativado ou excluído, não é possível emitir tokens novos, e os existentes são rejeitados.

O clientSecret pode ser armazenado em um site ou aplicativo móvel?

Não. O clientSecret é uma credencial de servidor. Nem os recursos do navegador, nem os pacotes de aplicativo, nem os logs do cliente conseguem protegê-lo de forma confiável.

Mantenha as credenciais em um servidor sob seu controle. Não escreva o clientSecret, os access token nem os tickets de WebSocket em código de frontend, repositórios públicos ou logs.

Os dados do dispositivo não parecem corretos

Falta um dispositivo na lista

Primeiro confirme que o dispositivo pertence à conta atual e que o API Client tem permissão para acessá-lo.

Se o dispositivo aparece no Developer Console mas não na API, verifique as concessões do dispositivo e o scope device:read. Se a causa continuar indefinida, registre o requestId antes de contatar o suporte.

O estado da lista não corresponde ao dispositivo físico agora mesmo

A lista de dispositivos retorna o estado já sincronizado pela plataforma. Ela não atualiza ativamente cada dispositivo físico em cada requisição, e é voltada para visualizações de lista, painéis e leituras em massa.

Para uma atualização explícita do usuário, ou antes e depois de uma operação, use Consultar dispositivo (em inglês) ou uma requisição de status via WebSocket.

Posso fazer sondagem HTTP com frequência para periféricos, desconexão ou energia?

Não é recomendado. O estado de periféricos, o estado offline e os eventos de energia são dados voltados para tempo real. Uma sondagem HTTP agressiva aumenta a pressão de atualização sobre os dispositivos e torna mais provável atingir os limites de taxa.

Abordagem recomendada:

1. Use Listar dispositivos (em inglês) para listas, painéis e sincronização em segundo plano.
2. Use Consultar dispositivo (em inglês) ou device.state.get via WebSocket quando o usuário atualizar explicitamente a página de detalhe de um dispositivo.
3. Use eventos WebSocket para monitorar continuamente desconexões, energia e mudanças em periféricos; após reconectar, confirme novamente o estado crítico via HTTP ou device.state.get.

Não chame o endpoint de atualização em tempo real a cada poucos segundos para cada dispositivo. Ele não garante entrega de eventos sem perdas e pode afetar outras requisições normais da mesma conta.

deviceType é UNSUPPORTED

A plataforma ainda não oferece uma definição de tipo utilizável para esse dispositivo. O dispositivo pode continuar pertencendo à conta, mas o cliente não deve assumir que seu esquema de estado ou capacidades de controle estão disponíveis.

Não deduza as capacidades a partir do prefixo do ID do dispositivo.

Como sei se um dispositivo suporta uma operação?

Consulte Listar definições de tipo de dispositivo (em inglês) e verifique capabilities.supportedOperations.

Só devem ser exibidas ou chamadas as operações listadas ali. Por exemplo, não mostre o transceptor RS485 a menos que exista device.rs485.transceive.

Uma operação não terminou como esperado

A resposta é COMMAND_ACCEPTED, mas o dispositivo não se moveu

COMMAND_ACCEPTED significa que a plataforma aceitou a requisição. Não significa que o dispositivo tenha completado a operação.

Guie-se pelo status do comando: SUCCESS significa que o dispositivo confirmou a operação; TIMEOUT significa que nenhuma confirmação final chegou a tempo. Use Consultar resultado de comando (em inglês) para recuperar o estado de um comando anterior.

O comando está em TIMEOUT. O dispositivo com certeza não executou?

Não necessariamente. O dispositivo pode não ter recebido o comando, ou pode tê-lo executado enquanto a confirmação foi atrasada ou perdida.

Não repita o comando cegamente. Leia primeiro o estado atual do dispositivo, especialmente para operações que não é seguro duplicar.

O code da resposta é COMMAND_REJECTED

Verifique primeiro duas coisas:

1. A definição de tipo de dispositivo inclui a operação solicitada.
2. Os parâmetros correspondem à capacidade do dispositivo, como um índice de relé válido.

Se ambos estiverem corretos, verifique a conectividade do dispositivo e o caminho subjacente até ele.

Uma nova tentativa deve usar um Idempotency-Key novo?

Reutilize a chave original ao tentar novamente a mesma operação de negócio após uma falha de rede. Dispositivos diferentes, estados de destino diferentes ou operações de negócio diferentes exigem chaves diferentes.

Não use uma chave fixa para todas as requisições. Veja Comportamento HTTP (em inglês).

A conexão em tempo real está instável

O WebSocket não consegue conectar

Confirme que o access token é válido e depois crie um wsTicket novo. O ticket tem vida curta e uso único: não deve ser armazenado em cache nem reutilizado.

Veja Criar WebSocket Ticket e depois Estabelecer conexão (ambos em inglês).

Como o cliente deve se recuperar após uma desconexão?

Reconecte com backoff e crie um ticket novo para cada nova conexão. Após reconectar, recarregue o estado necessário em vez de assumir que os eventos do período desconectado serão totalmente reproduzidos.

Veja Heartbeat e reconexão (em inglês).

Chegam eventos duplicados, ou parece que faltam alguns

O tratamento de eventos deve ser idempotente. O WebSocket notifica mudanças ao cliente e não deve ser a única fonte permanente de estado.

Após recarregar a página, reconectar ou detectar uma lacuna de estado, consulte o estado via REST API ou com uma requisição de status via WebSocket para estabelecer uma nova base.

As requisições estão limitadas ou o serviço está temporariamente indisponível

A resposta é HTTP 429

Pare de tentar novamente de imediato. Leia o Retry-After e tente novamente após o tempo indicado. Coordene o backoff entre as instâncias do seu serviço para evitar outra rajada sincronizada.

A atualização em tempo real e o controle de dispositivos têm limites mais rígidos do que as consultas de estado sincronizado. Veja Limites de taxa e tentativas (em inglês).

A resposta é 503 ou GATEWAY_UNAVAILABLE

O caminho em tempo real até o dispositivo está temporariamente indisponível. Registre o requestId e tente novamente um número limitado de vezes com backoff.

Se a situação persistir, pare de tentar e prepare os dados para o suporte.

Prepare os dados para o suporte

Se o problema persistir, reúna:

Informação	Exemplo ou orientação
requestId	ID de rastreamento retornado pela resposta da API
ID do API Client	Nunca inclua o clientSecret
Método e caminho da requisição	GET /wlte/v1/devices
Marca de tempo em UTC	Momento exato do problema
Status HTTP e code de negócio	Por exemplo, 403 / AUTH_SCOPE_DENIED
Parâmetros depurados	Remova senhas, tokens e informações pessoais

Depois envie o caso em Contatar suporte.