G10 Bio UTG — Primeiro acesso

Resumo do fluxo

Um funcionário autorizado gera, no ERP, um código temporário de primeiro acesso para uma UTG específica.

O aplicativo da UTG lê o QR Code ou recebe o código digitado, informa o nome do aparelho e envia a solicitação de pareamento.

Quando o código é válido, a API cria um device_token definitivo, vinculado à UTG e ao aparelho, consome o código temporário e libera o aplicativo.

MANTER do G10 Cytrus

Leitura de QR Code.
Identificação do aparelho por device_name.
Uso de X-APP-KEY para identificar o aplicativo.
Armazenamento seguro do device_token.
Validação automática do token ao abrir o aplicativo.
Funcionamento offline depois que o aparelho estiver pareado.

ALTERAR em relação ao G10 Cytrus

O acesso pertence a uma UTG, e não a um colaborador.
O token definitivo deve usar tipo_usuario=utg.
O token definitivo deve usar entity_type=programas_utgs.
A API exclusiva da UTG utiliza id_api=4.
O código temporário é gerado no ERP, dentro da aba Dispositivos da UTG.
Não existe cadastro de funcionário da UTG para liberar o aplicativo.

Fluxo no aplicativo

Informar o nome do aparelho.
Ler o QR Code apresentado pelo ERP ou digitar o código temporário.
Salvar temporariamente o código e o nome do aparelho.
Verificar se existe conexão com a internet.
Enviar a solicitação de pareamento.
Receber o device_token.
Salvar o token em armazenamento seguro.
Remover o código temporário do armazenamento local.
Executar a validação do token.
Liberar o acesso ao aplicativo.

Dados salvos antes do pareamento

pairing_code
device_name
status_envio
tentativas_envio
ultima_tentativa_em

Esses dados podem ser mantidos localmente até que o pareamento seja concluído. Sem internet, o aplicativo deve permanecer bloqueado e tentar novamente quando houver conexão.

Como o código é gerado no ERP

Na tela da UTG, acessar a aba Dispositivos e selecionar Gerar acesso para UTG.

O ERP cria um token temporário com as seguintes características:

id_api=4
entity_type=programas_utgs
entity_id=<ID_DA_UTG>
tipo_usuario=utg
tipo=1
ativo=1
uso_maximo=1
expira_em=<DATA_HORA_DE_EXPIRACAO>

O conteúdo desse token é exibido como código e pode ser transformado em QR Code.

Endpoint 1: parear aparelho da UTG

POST https://institutog10bio.com.br/router/action.php

Headers

X-APP-KEY: <APP_KEY_FIXA_DO_APP_UTG>

Body

action=apiG10bio_utg
f=parear_device_utg
pairing_code=<CODIGO_TEMPORARIO>
device_name=<NOME_DO_APARELHO>

Este endpoint não exige X-DEVICE-TOKEN, pois o aparelho ainda não possui token definitivo.

Resposta do pareamento — HTTP 200

{
  "success": true,
  "msg": "Aparelho da UTG pareado com sucesso.",
  "data": {
    "device_token": "dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "device_id": 123,
    "account_type": "utg",
    "id_utg": 7,
    "id_programa": 2,
    "nome_utg": "UTG Porto Ferreira",
    "pairing_burned": true
  }
}

device_token: token permanente do aparelho.
device_id: identificador do token em api_tokens.
account_type: perfil liberado, sempre utg.
id_utg: UTG vinculada ao aparelho.
id_programa: programa ao qual a UTG pertence.
pairing_burned: confirma que o código temporário foi consumido.

Regra de consumo do código temporário

O código deve ser consumido somente depois da criação bem-sucedida do token definitivo.

api_tokens temporário:
ativo = 0
usos = usos + 1
ultimo_uso_em = NOW()

Depois disso, o mesmo código não poderá parear outro aparelho.

Endpoint 2: validar DEVICE_TOKEN

POST https://institutog10bio.com.br/router/action.php

Headers

X-APP-KEY: <APP_KEY_FIXA_DO_APP_UTG>
X-DEVICE-TOKEN: <DEVICE_TOKEN_DA_UTG>

Body

action=apiG10bio_utg
f=valida_device_token

O aplicativo deve chamar esse endpoint ao abrir, sempre que já existir um device_token salvo.

Resposta: token válido — HTTP 200

{
  "success": true,
  "msg": "Dispositivo validado com sucesso.",
  "data": {
    "account_type": "utg",
    "device_id": 123,
    "id_utg": 7,
    "id_programa": 2,
    "nome_utg": "UTG Porto Ferreira",
    "device_name": "Tablet UTG 01"
  }
}

Resposta: token inválido ou revogado

{
  "success": false,
  "error": "invalid_device_token",
  "msg": "DEVICE_TOKEN da UTG inválido ou inativo.",
  "data": {}
}

Apagar o token local, bloquear o aplicativo e retornar à tela de primeiro acesso.

Erros comuns

401 missing_api_key: APP_KEY não informada.
403 invalid_api_key: APP_KEY inválida.
400 missing_pairing_code: código temporário não informado.
404 pairing_not_found: código não encontrado.
409 pairing_already_used: código já utilizado.
410 pairing_expired: código expirado.
403 utg_inactive: UTG inativa.
409 device_already_registered: aparelho já possui vínculo ativo.

Em caso de falha por falta de conexão, manter o código localmente e tentar novamente. Para códigos expirados ou já utilizados, solicitar um novo código ao responsável pelo ERP.

Regra ao abrir o aplicativo

SE existir device_token
→ verificar internet
→ chamar valida_device_token
→ token válido: abrir o aplicativo
→ token inválido/revogado: apagar token e voltar ao primeiro acesso

SE não existir device_token e existir pairing_code salvo
→ verificar internet
→ chamar parear_device_utg
→ se falhar por conexão, manter o código
→ se aprovado, salvar device_token e liberar o aplicativo

SE não existir device_token nem pairing_code
→ exibir tela para nome do aparelho e leitura do QR Code

Após o pareamento

Somente depois de receber o device_token, o aplicativo poderá utilizar os endpoints protegidos da UTG.

action=apiG10bio_utg
f=sincronizacao_offline

Headers:
X-APP-KEY: <APP_KEY_FIXA_DO_APP_UTG>
X-DEVICE-TOKEN: <DEVICE_TOKEN_DA_UTG>

NÃO IMPLEMENTAR no primeiro acesso da UTG

Login com usuário e senha.
Seleção manual de outra UTG.
Criação de device_token no próprio aplicativo.
Reutilização do mesmo código temporário em vários aparelhos.
Uso da API do Produtor.
Liberação do aplicativo sem validar o código no servidor.
Uso de sincronizacao_offline antes do pareamento.