G10 Bio UTG — Entrega de kits e produtos

Resumo do fluxo

Selecionar produtor
→ ler QR Codes das caixas e produtos
→ montar carrinho local
→ revisar a entrega
→ capturar localização
→ enviar para o ERP
→ reservar estoque
→ exibir QR Code temporário
→ aguardar confirmação futura do produtor

Nesta etapa, o aplicativo UTG cria a entrega. A baixa definitiva do estoque ocorrerá somente quando o aplicativo Produtor confirmar o recebimento.

Regras obrigatórias

O aplicativo não envia um id_utg livremente. A API identifica a UTG pelo X-DEVICE-TOKEN.
Cada caixa ou produto físico possui um codigo_qr único.
O mesmo volume não pode estar em duas entregas simultâneas.
A entrega deve ser salva no ERP somente depois da revisão do carrinho.
O client_event_id deve ser gerado uma única vez e reutilizado em todos os reenvios.
A localização é obrigatória no momento de concluir a entrega.
O carrinho local só pode ser limpo depois de success=true.
A criação reserva o estoque, mas não reduz quantidade_atual.

Fluxo de telas no aplicativo

Abrir o módulo Entregas.
Tocar em Nova entrega.
Selecionar um produtor vinculado à UTG.
Abrir o leitor de QR Code.
Ler uma caixa de kit ou produto avulso.
Consultar o volume na API e adicioná-lo ao carrinho.
Repetir a leitura para todos os volumes.
Revisar produtor, caixas, produtos, lotes e quantidades.
Capturar data, hora e localização.
Gerar o client_event_id.
Enviar a criação da entrega.
Exibir o qr_content retornado pela API.
Acompanhar o status até a confirmação futura do produtor.

Pré-requisitos

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

Endpoint base:

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

SQLite — carrinho da entrega

O carrinho deve existir localmente para não perder as leituras se a tela for fechada ou houver instabilidade.

CREATE TABLE app_entregas_rascunho (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  client_event_id TEXT UNIQUE,
  id_utg_produtor INTEGER,
  nome_produtor TEXT,
  status TEXT NOT NULL DEFAULT 'RASCUNHO',
  data_hora_utg TEXT,
  latitude_utg REAL,
  longitude_utg REAL,
  accuracy_utg REAL,
  id_entrega_erp INTEGER,
  token_confirmacao TEXT,
  expira_em TEXT,
  criado_em TEXT NOT NULL,
  atualizado_em TEXT
);

CREATE TABLE app_entregas_volumes (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  id_rascunho INTEGER NOT NULL,
  id_volume INTEGER NOT NULL,
  codigo_qr TEXT NOT NULL,
  tipo_volume TEXT NOT NULL,
  descricao TEXT,
  quantidade REAL NOT NULL,
  lote TEXT,
  validade TEXT,
  payload_json TEXT NOT NULL,
  criado_em TEXT NOT NULL,
  UNIQUE(id_rascunho, id_volume)
);

1. Listar produtores

f=listar_produtores_entrega

action=apiG10bio_utg
f=listar_produtores_entrega

Usar o campo id_utg_produtor na criação da entrega. Não usar diretamente o id_cliente.

2. Consultar QR Code do volume

f=consultar_volume_qrcode

action=apiG10bio_utg
f=consultar_volume_qrcode
codigo_qr=G10-VOL-8F7A2C91

Comportamento do app

Mostrar carregamento durante a consulta.
Não adicionar o mesmo id_volume duas vezes.
Exibir kit, produto, lote, validade e quantidade retornados.
Em erro volume_unavailable, mostrar o status recebido.
Em erro volume_from_another_utg, bloquear a inclusão.

3. Montar e revisar o carrinho

A tela deve apresentar:

nome do produtor;
quantidade total de volumes;
tipo de cada volume: KIT ou PRODUTO;
descrição;
lote e validade;
botão para remover um volume antes do envio;
botão Concluir entrega.

Importante: remover do carrinho não altera nada no ERP enquanto a entrega ainda não tiver sido criada.

4. Criar a entrega

f=criar_entrega

action=apiG10bio_utg
f=criar_entrega
id_utg_produtor=4
client_event_id=550e8400-e29b-41d4-a716-446655440000
data_hora_utg=2026-08-03 13:00:00
latitude_utg=-21.8532000
longitude_utg=-47.4795000
accuracy_utg=8.50
volumes=[101,102,103]

O campo volumes contém os IDs retornados por consultar_volume_qrcode.

Resposta esperada

{
  "success": true,
  "data": {
    "id_entrega": 12,
    "status": "AGUARDANDO_CONFIRMACAO",
    "id_utg_produtor": 4,
    "nome_produtor": "José da Silva",
    "quantidade_volumes": 3,
    "token_confirmacao": "ent_xxxxxxxxx",
    "qr_content": "ent_xxxxxxxxx",
    "expira_em": "2026-08-03 13:30:00",
    "already_registered": false
  }
}

Idempotência e reenvio

Ao tocar em concluir, o app gera o client_event_id e salva no SQLite antes da requisição. Se ocorrer timeout, deve reenviar o mesmo produtor, os mesmos volumes e o mesmo identificador.

success=true
OU
already_registered=true
→ considerar a entrega registrada
→ salvar id_entrega_erp
→ remover a pendência de envio
→ manter o histórico local

Não gerar outro UUID para repetir a mesma tentativa.

5. Exibir o QR Code da entrega

Depois de criar a entrega, transformar somente o valor de qr_content em QR Code.

Conteúdo do QR:
ent_36f9...token...

Não incluir nome do produtor, JSON ou URL junto ao token.

Tela

Nome do produtor
Número da entrega
Quantidade de volumes
QR Code em tamanho grande
Contagem regressiva até expira_em

Ações

Atualizar status
Gerar novo QR quando expirado
Voltar ao histórico

6. Listar entregas

f=listar_entregas_utg

action=apiG10bio_utg
f=listar_entregas_utg
status=AGUARDANDO_CONFIRMACAO

O filtro status é opcional. A tela pode ter abas:

Aguardando | Confirmadas | Canceladas | Todas

7. Abrir detalhes

f=detalhes_entrega_utg

action=apiG10bio_utg
f=detalhes_entrega_utg
id_entrega=12

Usar pode_exibir_qr e qr_expirado para controlar a interface. O token não será retornado quando não puder mais ser exibido.

8. Renovar QR Code

f=renovar_qr_entrega

action=apiG10bio_utg
f=renovar_qr_entrega
id_entrega=12

Mostrar o botão somente quando a entrega estiver em AGUARDANDO_CONFIRMACAO e o QR tiver expirado. O token anterior deixa de funcionar.

Erros que precisam ser tratados

Erro	Ação no aplicativo
`volume_not_found`	Informar que o QR Code não foi cadastrado.
`volume_from_another_utg`	Bloquear a inclusão e orientar a conferir a caixa.
`volume_unavailable`	Mostrar que o volume já está reservado, entregue ou cancelado.
`insufficient_stock`	Não limpar o carrinho; solicitar conferência do estoque no ERP.
`request_conflict`	Bloquear o reenvio e registrar o conflito para análise.
`invalid_latitude` / `invalid_longitude`	Capturar novamente a localização.
`device_token_inactive`	Encerrar a sessão e voltar ao primeiro acesso.

Efeito no ERP

Ao criar a entrega:
bio_entregas.status = AGUARDANDO_CONFIRMACAO
bio_volumes.status = RESERVADO
bio_utg_estoque.quantidade_reservada += quantidade
bio_utg_estoque.quantidade_atual permanece igual
bio_utg_estoque_movimentos = RESERVA_ENTREGA

Não implementar nesta etapa

Baixa definitiva do estoque pelo aplicativo UTG.
Confirmação manual sem o aplicativo Produtor.
Alteração manual do saldo.
Uso do mesmo volume em outra entrega.
Cancelamento local sem endpoint específico.
Marcar o volume como ENTREGUE ao gerar o QR.

Bibliotecas previstas no React Native com Expo

expo-camera para leitura dos QR Codes.
expo-location para latitude, longitude e precisão.
expo-crypto para gerar o UUID do client_event_id.
expo-sqlite para carrinho, histórico e fila local.
expo-secure-store para o DEVICE_TOKEN.
Biblioteca de QR Code compatível com React Native para exibir qr_content.

Checklist para considerar a tela pronta

Produtores carregados pela API.
Leitor bloqueia QR duplicado no carrinho.
Carrinho permanece salvo ao fechar o app.
Localização validada antes da conclusão.
client_event_id salvo antes do envio.
Timeout reaproveita o mesmo evento.
QR temporário exibido após sucesso.
Histórico e detalhes funcionando.
Renovação disponível após expiração.
Nenhuma baixa definitiva feita pelo app UTG.