Resumo do fluxo

O produtor lê o QR Code apresentado pelo franqueado. A leitura é salva primeiro no SQLite.

Havendo internet, o aplicativo tenta enviar a solicitação imediatamente. Sem internet ou em caso de falha, o registro permanece em uma fila local para nova tentativa.

O acesso somente será liberado depois da aprovação da franqueadora.

MANTER do G10 Cytrus

Leitura de QR Code.
Funcionamento offline com SQLite.
client_event_id para evitar duplicidade.
Captura de data, hora e geolocalização.
Fila local com tentativas de reenvio.
Armazenamento seguro do device_token.

ALTERAR em relação ao G10 Cytrus

A leitura do QR Code não libera o aplicativo imediatamente.
O registro deve ser salvo primeiro no SQLite.
O primeiro envio não utiliza f=sincronizacao_offline.
A sincronização offline normal somente será usada após a geração do device_token.
O aplicativo deve aguardar a aprovação da franqueadora.

Fluxo no aplicativo

Informar o nome do aparelho.
Ler o QR Code apresentado pelo franqueado.
Gerar um client_event_id.
Salvar a leitura no SQLite.
Tentar enviar a solicitação caso exista internet.
Manter na fila local caso o envio não seja concluído.
Exibir o status Aguardando aprovação.
Consultar a situação sempre que o aplicativo for aberto.
Quando aprovado, salvar o device_token e liberar o acesso.

Dados salvos no SQLite

client_event_id
pairing_code
device_name
data_leitura
hora_leitura
latitude
longitude
status_envio
status_solicitacao
tentativas_envio
ultima_tentativa_em
ultima_consulta_em
motivo_rejeicao

Endpoint 1: enviar solicitação de vínculo

POST https://agroecologia.grupoekos.com.br/router/action.php

Headers

X-APP-KEY: <APP_KEY_FIXA_DO_APP_PRODUTOR>

Body

action=apiG10bio_produtor
f=enviar_solicitacao_vinculo
pairing_code=
device_name=
client_event_id=
data_leitura=
hora_leitura=
latitude=
longitude=

Este endpoint não exige X-DEVICE-TOKEN, pois o aparelho ainda não foi pareado.

Resposta do envio — HTTP 200

{
"success": true,
"msg": "Solicitação recebida e aguardando aprovação.",
"data": {
"status": "PENDENTE",
"client_event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}

Após essa resposta, remover o registro da fila de envio, mas manter a solicitação salva no SQLite como PENDENTE.

Endpoint 2: consultar situação da solicitação

POST https://agroecologia.grupoekos.com.br/router/action.php

Headers

X-APP-KEY: <APP_KEY_FIXA_DO_APP_PRODUTOR>

Body

action=apiG10bio_produtor
f=consultar_status_vinculo
pairing_code=
client_event_id=

O aplicativo deve consultar este endpoint sempre que for aberto enquanto ainda não possuir device_token.

Resposta: aprovado — HTTP 200

{
"success": true,
"msg": "Dispositivo aprovado e liberado com sucesso.",
"data": {
"status": "APROVADO",
"device_token": "dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"device_id": 123,
"account_type": "produtor",
"pairing_burned": true
}
}

status: situação atual da solicitação.
device_token: token permanente do aparelho.
device_id: identificador do aparelho na API.
account_type: perfil liberado para o aplicativo.
pairing_burned: informa se o código temporário foi consumido.

Depois da aprovação, salvar o device_token em armazenamento seguro e liberar o aplicativo.

Resposta: aguardando aprovação — HTTP 200

{
"success": true,
"msg": "Solicitação aguardando aprovação da franqueadora.",
"data": {
"status": "PENDENTE",
"device_token": null
}
}

Manter o usuário na tela de espera e consultar novamente na próxima abertura do aplicativo.

Resposta: rejeitado — HTTP 200

{
"success": true,
"msg": "Solicitação rejeitada.",
"data": {
"status": "REJEITADO",
"device_token": null,
"motivo_rejeicao": "Dados cadastrais divergentes."
}
}

Exibir o motivo e permitir que o produtor faça uma nova leitura de QR Code.

Erros comuns

403 invalid_api_key: APP_KEY inválida.
404 pairing_not_found: código não localizado.
409 request_conflict: solicitação incompatível ou já vinculada.
410 pairing_expired: código expirado.
400: campos obrigatórios ausentes ou inválidos.

Em caso de falha no envio, manter o registro na fila do SQLite e tentar novamente quando houver internet.

Regra ao abrir o aplicativo

SE já existir device_token


→ validar o token
→ abrir o aplicativo normalmente

SE existir solicitação ainda não enviada
→ verificar internet
→ chamar enviar_solicitacao_vinculo
→ se falhar, manter na fila local

SE existir solicitação pendente já enviada
→ verificar internet
→ chamar consultar_status_vinculo
→ PENDENTE: manter tela de espera
→ REJEITADO: mostrar o motivo
→ APROVADO: salvar device_token e liberar o acesso

SE estiver sem internet e não existir device_token
→ mostrar o último status salvo no SQLite

Após a aprovação

Somente depois de receber o device_token, o aplicativo poderá utilizar endpoints protegidos, incluindo:

action=apiG10bio_produtor
f=sincronizacao_offline

Headers:
X-APP-KEY: 
X-DEVICE-TOKEN:

NÃO IMPLEMENTAR no app produtor

Cadastro do produtor pelo franqueado.
Geração do QR Code.
Aprovação ou rejeição da solicitação.
Cadastro direto na tabela clientes.
Criação ou transferência do vínculo com o franqueado.
Chamadas ao controlador apiG10bio_franqueado.
Uso de sincronizacao_offline antes do pareamento.