G10 Bio UTG — Cadastro do produtor e QR Code

Resumo do fluxo

A UTG cadastra o produtor no aplicativo, mesmo sem internet. O cadastro é salvo primeiro no SQLite e recebe um client_event_id e um pairing_code gerados localmente.

Assim que o cadastro é salvo, o aplicativo da UTG exibe um QR Code contendo o mesmo pairing_code. O produtor lê esse QR Code no aplicativo G10 Bio Produtor.

Os dois aplicativos armazenam seus registros em filas locais e enviam os dados ao ERP quando houver internet. O ERP cruza os dois envios pelo pairing_code e somente disponibiliza a aprovação quando o cadastro da UTG e a leitura do produtor tiverem sido recebidos.

Princípios obrigatórios

O cadastro deve funcionar sem internet.
O registro deve ser salvo no SQLite antes de qualquer tentativa de envio.
O QR Code deve ser exibido imediatamente após o salvamento local.
O pairing_code deve ser criado no aparelho da UTG e ser único.
O client_event_id deve impedir duplicidade nos reenvios.
O cadastro deve permanecer na fila até a confirmação da API.
O aplicativo da UTG não aprova o dispositivo do produtor.
A aprovação ou rejeição será feita por um funcionário no ERP.

Pré-requisito do aplicativo da UTG

Este endpoint é protegido. O aplicativo da UTG já deve possuir:

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

O DEVICE_TOKEN identifica qual UTG está utilizando o aplicativo. Por isso, o corpo da requisição não deve aceitar um id_utg informado livremente pelo aparelho.

Fluxo no aplicativo da UTG

O usuário abre a função de cadastrar produtor.
Preenche os dados cadastrais disponíveis.
O aplicativo gera um client_event_id único.
O aplicativo gera um pairing_code único.
Salva o cadastro no SQLite.
Inclui o registro na fila de sincronização.
Exibe o QR Code contendo o pairing_code.
O produtor lê o QR Code usando o aplicativo Produtor.
Havendo internet, o aplicativo tenta enviar o cadastro.
Em caso de falha, mantém o registro na fila para nova tentativa.
Após confirmação da API, remove apenas a pendência da fila.
Mantém localmente o cadastro e a situação do vínculo.

Dados salvos no SQLite

client_event_id
pairing_code
nome
documento
telefone
email
endereco
numero
bairro
cep
cidade
uf
latitude
longitude
dados_cadastro_json
status_envio
status_vinculo
tentativas_envio
ultima_tentativa_em
criado_em
atualizado_em

Geração do pairing_code

O código deve ser gerado localmente antes da sincronização. Ele será o vínculo entre o cadastro enviado pela UTG e a leitura enviada pelo aplicativo do produtor.

Exemplo:
bio_prod_550e8400-e29b-41d4-a716-446655440000

Usar UUID ou outro identificador criptograficamente aleatório.
Não usar somente data, hora, ID incremental ou documento do produtor.
O mesmo valor deve ser salvo no SQLite, enviado à API e exibido no QR Code.
O QR Code deve conter somente o valor do pairing_code.

Comportamento offline

O cadastro e a exibição do QR Code não dependem de internet.

SEM INTERNET
→ gerar client_event_id
→ gerar pairing_code
→ salvar cadastro no SQLite
→ inserir na fila local
→ exibir QR Code
→ aguardar próxima sincronização

O produtor também poderá ler e salvar o QR Code offline. Os dois envios podem chegar ao ERP em ordens diferentes.

Endpoint: enviar cadastro do produtor

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=receber_cadastro_produtor
client_event_id=<UUID_GERADO_PELO_APP>
pairing_code=<CODIGO_EXIBIDO_NO_QRCODE>
dados_cadastro=<JSON_DO_PRODUTOR>

Exemplo de dados_cadastro

{
  "nome": "José da Silva",
  "documento": "12345678900",
  "telefone": "16999999999",
  "email": "jose@email.com",
  "endereco": "Sítio Boa Esperança",
  "numero": "S/N",
  "bairro": "Zona Rural",
  "cep": "13660000",
  "cidade": "Porto Ferreira",
  "uf": "SP",
  "latitude": -21.8532000,
  "longitude": -47.4795000
}

O JSON pode receber outros campos do cadastro, desde que sejam documentados e preservados pela API.

Resposta: cadastro recebido e aguardando produtor — HTTP 200

{
  "success": true,
  "msg": "Cadastro recebido e aguardando leitura do produtor.",
  "data": {
    "status": "AGUARDANDO_PRODUTOR",
    "client_event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "pairing_code": "bio_prod_xxxxxxxxxxxxxxxxx",
    "cadastro_id": 45,
    "producer_request_received": false
  }
}

Após essa resposta, remover o registro da fila de envio. Manter o cadastro salvo localmente com o status AGUARDANDO_PRODUTOR.

Resposta: cadastro pronto para aprovação — HTTP 200

{
  "success": true,
  "msg": "Cadastro recebido e pronto para aprovação.",
  "data": {
    "status": "PRONTO_APROVACAO",
    "client_event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "pairing_code": "bio_prod_xxxxxxxxxxxxxxxxx",
    "cadastro_id": 45,
    "producer_request_received": true
  }
}

Essa resposta indica que a leitura do aplicativo Produtor já havia chegado ao ERP e os dois registros foram relacionados.

Idempotência e reenvio

O mesmo client_event_id pode ser reenviado quando houver falha de comunicação. A API não deve criar outro cadastro.

MESMO client_event_id + MESMO pairing_code
→ retornar o registro já recebido

MESMO client_event_id + pairing_code DIFERENTE
→ HTTP 409 request_conflict

O aplicativo só deve remover o item da fila quando receber uma resposta de sucesso da API.

Ordem de chegada dos dados

Cadastro da UTG chega primeiro

UTG envia cadastro
→ status AGUARDANDO_PRODUTOR
→ produtor envia leitura depois
→ ERP relaciona pelo pairing_code
→ status PRONTO_APROVACAO

Leitura do produtor chega primeiro

Produtor envia leitura
→ solicitação permanece PENDENTE
→ UTG envia cadastro depois
→ ERP relaciona pelo pairing_code
→ status PRONTO_APROVACAO

Regra para aparecer no ERP

A solicitação só pode ser apresentada como pronta para aprovação quando existirem os dois lados:

Cadastro enviado pelo aplicativo da UTG
+
Leitura do QR Code enviada pelo aplicativo do Produtor
+
Mesmo pairing_code
=
PRONTO_APROVACAO

Enquanto apenas um dos lados tiver chegado, o ERP deve informar que o vínculo ainda está incompleto.

O que acontece após a aprovação no ERP

O ERP valida o cadastro enviado pela UTG.
Localiza ou cria o produtor na tabela clientes.
Cria ou confirma o vínculo em programas_utgs_produtores.
Gera o DEVICE_TOKEN definitivo do aparelho do produtor.
Atualiza a solicitação para APROVADO.
O aplicativo Produtor recebe o token pelo endpoint consultar_status_vinculo.
O aplicativo da UTG poderá receber o novo status em uma sincronização posterior.

Erros comuns

401 missing_api_key: APP_KEY não enviada.
401 missing_device_token: DEVICE_TOKEN não enviado.
403 invalid_api_key: APP_KEY inválida.
403 invalid_device_token: dispositivo da UTG inválido ou inativo.
400 invalid_client_event_id: identificador ausente ou inválido.
400 invalid_pairing_code: código ausente ou inválido.
400 invalid_registration_data: JSON do cadastro inválido.
409 request_conflict: evento já utilizado com dados diferentes.
409 pairing_conflict: pairing_code já vinculado a outro cadastro.

Em falhas de rede ou erro temporário do servidor, manter o item na fila e tentar novamente.

Regra da fila local

status_envio = PENDENTE
→ tentar enviar quando houver internet

HTTP 200 / success = true
→ remover da fila de envio
→ manter cadastro salvo no SQLite
→ atualizar status_vinculo retornado pela API

ERRO DE REDE OU HTTP 5xx
→ manter na fila
→ incrementar tentativas_envio
→ registrar ultima_tentativa_em

HTTP 400, 403 ou 409
→ manter o cadastro local
→ marcar como ERRO_VALIDACAO
→ exibir a mensagem para correção

NÃO IMPLEMENTAR no aplicativo da UTG

Aprovação ou rejeição do aparelho do produtor.
Criação direta do DEVICE_TOKEN do produtor.
Inserção direta em tabelas do ERP.
Envio livre de id_utg no corpo da requisição.
Uso do documento do produtor como pairing_code.
Dependência de internet para salvar o cadastro ou exibir o QR Code.
Remoção do registro local antes da confirmação da API.
Reaproveitamento do mesmo pairing_code para produtores diferentes.

Checklist de implementação

Cadastro salvo primeiro no SQLite.
client_event_id único por cadastro.
pairing_code único por produtor.
QR Code exibido imediatamente após salvar.
Fila local com tentativas de reenvio.
APP_KEY e DEVICE_TOKEN enviados nos headers.
JSON completo preservado em dados_cadastro.
Tratamento idempotente do reenvio.
Status local atualizado com a resposta da API.
Aprovação mantida exclusivamente no ERP.