Regenera G10 - Iniciar Aplicacao

Objetivo do modulo

Registrar no ERP o inicio e a finalizacao da etapa de produtos da aplicacao, validando os produtos que serao despejados no tanque e preservando auditoria de cada leitura de QR Code.

O app deve validar a sequencia dos produtos offline. Se o usuario escanear o produto errado, o app deve avisar que a ordem esta incorreta, impedir a confirmacao do despejo daquele produto e registrar a tentativa errada para posterior envio ao ERP.

O vinculo com o pedido vem da Preparacao Eko´s Bio. Os QR Codes dos demais produtos podem ser fixos e conter apenas o codigo do produto, sem vinculo direto com o pedido.

Fluxo esperado no app

Usuario acessa o menu Iniciar Aplicacao.
App busca localmente o registro da Preparacao Eko´s Bio e obtem id_preparo_bio, id_pedido, data_preparo e hora_preparo.
Usuario toca no botao Iniciar.
App verifica se a Preparacao Eko´s Bio ja completou 48 horas.
Se nao completou 48 horas, o app exibe o alerta e pergunta se o usuario deseja continuar.
Se o usuario clicar em Nao, o app cancela o inicio e envia o cancelamento para auditoria.
Se o usuario clicar em Sim, o app continua o fluxo e registra que o usuario decidiu prosseguir com alerta.
App gera um client_event_id unico para a aplicacao.
App registra localmente data, hora, latitude e longitude do inicio.
App solicita a leitura do QR Code do 1º produto.
App valida se o codigo do produto lido e o produto esperado para aquela etapa.
Se estiver correto, o app pede confirmacao do despejo no tanque.
Se o usuario confirmar, o app salva a confirmacao com data, hora, latitude e longitude.
App avanca para o proximo produto ate finalizar os 6 produtos.
Se o usuario escanear um produto fora da ordem, o app registra a tentativa errada e solicita o QR Code correto.
Ao finalizar, o app salva data, hora, latitude e longitude do fim.
Quando houver internet, o app envia a aplicacao completa para f=registrar_aplicacao.
Se a API retornar success=true, o app salva o id_aplicacao retornado.
O id_aplicacao sera usado depois no endpoint de trajeto.

Regra: a aplicacao deve ser salva localmente antes de qualquer tentativa de envio.

Vinculo com pedido e QR Codes dos produtos

A aplicacao deve estar vinculada a um pedido, mas esse vinculo vem exclusivamente da Preparacao Eko´s Bio. O QR Code do Bio e o QR Code que possui vinculo direto com o pedido.

No ERP, a tabela g10_aplicacoes possui os campos nome_tabela e id_tabela. Para este fluxo, o padrao deve ser:

nome_tabela = pedidos
id_tabela = <ID_DO_PEDIDO>

Os demais produtos da aplicacao podem usar QR Codes fixos com apenas o codigo do produto. Eles nao precisam ter vinculo direto com o pedido. Como esses produtos foram enviados na mesma caixa do Bio, o ERP associa as leituras ao id_pedido herdado do Preparo Bio.

Regra: o pedido vem do Bio; a ordem dos demais produtos e validada pelo codigo do produto.

Como o app deve obter o id_pedido

Para o fluxo Iniciar Aplicacao, o app deve obter o id_pedido a partir do registro da Preparacao Eko´s Bio. Esse e o ponto mais proximo da aplicacao e e o QR Code que possui vinculo direto com o pedido.

O QR Code usado na Preparacao Eko´s Bio deve estar sincronizado no app como tipo_conteudo=preparo_bio e vinculado ao pedido no padrao:

nome_tabela = pedidos
id_tabela = <ID_DO_PEDIDO>

Quando o app registrar a Preparacao Eko´s Bio, ele deve salvar localmente o retorno da API, principalmente:

id_preparo_bio
id_pedido
qrcode_id
data_preparo
hora_preparo
cliente_id
id_g10

No momento em que o usuario clicar em Iniciar Aplicacao, o app deve consultar localmente a Preparacao Eko´s Bio ja registrada e usar o id_pedido desse preparo como vinculo da aplicacao.

Importante sobre os QR Codes dos demais produtos

Diferente do QR Code da Preparacao Eko´s Bio, os demais produtos da aplicacao podem usar QR Codes fixos, contendo apenas o codigo do produto. Esses QR Codes nao precisam ter vinculo direto com o pedido.

Nesses casos, o app deve validar a ordem da aplicacao usando uma regra interna baseada no codigo do produto. O vinculo com o pedido sera feito pela aplicacao, usando o id_pedido obtido no Preparo Bio.

Fluxo recomendado

Preparacao Eko´s Bio
→ app salva id_pedido localmente

Iniciar Aplicacao
→ app busca id_pedido salvo no preparo Bio

Leitura dos produtos
→ app valida a ordem pelo codigo fixo do produto

Registro da aplicacao
→ app envia id_pedido + leituras dos produtos

Resposta da API
→ API retorna id_aplicacao

Envio do Trajeto
→ app usa id_aplicacao

Regra: no Iniciar Aplicacao, o id_pedido deve vir da Preparacao Eko´s Bio.

Observacao sobre o Eko´s Bio na ordem da aplicacao

A Preparacao Eko´s Bio e um procedimento anterior a aplicacao e pode acontecer ate 48 horas antes. No momento em que o usuario clicar em Iniciar Aplicacao, o app deve verificar a data/hora em que a Preparacao Eko´s Bio foi registrada.

Se a Preparacao Eko´s Bio ainda nao completou 48 horas, o app nao deve bloquear automaticamente o usuario. O app deve exibir um alerta e permitir que ele escolha se deseja continuar ou cancelar.

Mensagem de alerta

Preparacao EKO´S BIO nao completou 48 horas, deseja continuar?

Comportamento esperado

Se o usuario clicar em Sim, o app deve continuar para a leitura do primeiro produto.
Se o usuario clicar em Nao, o app deve cancelar o inicio da aplicacao.
Tanto a decisao de continuar quanto a decisao de cancelar devem ser enviadas para a API, pois o ERP precisa auditar essa ocorrencia.

Regra de validacao das 48 horas

data_hora_preparo = data_preparo + hora_preparo
data_hora_atual = data/hora atual do aparelho

diferenca = data_hora_atual - data_hora_preparo

Se diferenca < 48 horas:
    exibir alerta
Se diferenca >= 48 horas:
    seguir normalmente

Mesmo que o usuario opte por continuar antes de completar 48 horas, a aplicacao deve ser registrada no ERP com indicacao de alerta para auditoria.

Regra: nao bloquear; alertar, registrar a decisao e permitir auditoria no ERP.

Cancelamento antes de iniciar a aplicacao

Se a Preparacao Eko´s Bio ainda nao completou 48 horas e o usuario clicar em Nao no alerta, o app deve cancelar o inicio da aplicacao, mas ainda assim deve enviar esse registro para a API.

Esse registro e importante para auditoria, pois mostra que o usuario tentou iniciar a aplicacao antes do tempo recomendado e optou por nao continuar.

Formato do envio

action=apiG10
f=registrar_aplicacao
client_event_id=<UUID_LOCAL_DA_TENTATIVA>
id_preparo_bio=<ID_DO_PREPARO_BIO>
id_pedido=<ID_DO_PEDIDO>
bio_48h_status=alerta
bio_48h_horas_decorridas=36.2
bio_48h_decisao_usuario=cancelar
bio_48h_mensagem=Preparacao EKO´S BIO nao completou 48 horas, deseja continuar?
data_inicio=YYYY-MM-DD
hora_inicio=HH:MM:SS
latitude_inicio=<LATITUDE>
longitude_inicio=<LONGITUDE>
status=cancelada
observacao=Usuario cancelou o inicio da aplicacao porque a Preparacao Eko´s Bio ainda nao completou 48 horas.
produtos=[]

Nesse caso, o app nao deve avancar para a leitura do primeiro produto. Mesmo assim, a API deve retornar um id_aplicacao com status=cancelada, para fins de auditoria.

Resposta esperada no cancelamento

{
  "success": true,
  "msg": "Inicio da aplicacao cancelado e registrado para auditoria.",
  "data": {
    "id_aplicacao": 123,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "id_preparo_bio": 45,
    "id_pedido": 1490,
    "status": "cancelada",
    "bio_48h_status": "alerta",
    "bio_48h_decisao_usuario": "cancelar",
    "already_registered": false
  }
}

Regra: cancelar tambem deve gerar registro de auditoria.

Relacao com o envio do trajeto

O endpoint registrar_aplicacao deve retornar o id_aplicacao, que corresponde ao campo g10_aplicacoes.id.

O app deve guardar esse ID localmente. Quando o usuario realizar o trajeto da aplicacao, o endpoint de trajeto deve receber esse mesmo id_aplicacao.

registrar_aplicacao
→ retorna id_aplicacao
→ app salva id_aplicacao localmente
→ receber_trajeto_aplicacao usa id_aplicacao

Importante: sem id_aplicacao, o trajeto nao deve ser enviado ao ERP.

Endpoint

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

Headers obrigatorios

X-APP-KEY: <APP_KEY_FIXA_DO_APP>
X-DEVICE-TOKEN: <DEVICE_TOKEN_DO_APARELHO>

Body

action=apiG10
f=registrar_aplicacao
client_event_id=<UUID_LOCAL_DA_APLICACAO>
id_preparo_bio=<ID_DO_PREPARO_BIO>
id_pedido=<ID_DO_PEDIDO>
bio_48h_status=ok|alerta
bio_48h_horas_decorridas=<HORAS_DECORRIDAS>
bio_48h_decisao_usuario=nao_aplicavel|continuar|cancelar
bio_48h_mensagem=<MENSAGEM_DO_ALERTA_OU_VAZIO>
data_inicio=YYYY-MM-DD
hora_inicio=HH:MM:SS
latitude_inicio=<LATITUDE>
longitude_inicio=<LONGITUDE>
data_fim=YYYY-MM-DD
hora_fim=HH:MM:SS
latitude_fim=<LATITUDE>
longitude_fim=<LONGITUDE>
status=finalizada|finalizada_com_alerta|cancelada
observacao=<OPCIONAL>
produtos=<JSON_COM_AS_LEITURAS_E_CONFIRMACOES>

O envio deve ser feito em multipart/form-data ou application/x-www-form-urlencoded.

Campos enviados pelo app

Campo	Obrigatorio	Exemplo	Descricao
`client_event_id`	Sim	`550e8400-e29b-41d4-a716-446655440000`	ID unico local da aplicacao. Deve ser reutilizado em reenvios para evitar duplicidade.
`id_preparo_bio`	Sim	`45`	ID do registro da Preparacao Eko´s Bio usado para iniciar a aplicacao.
`id_pedido`	Sim	`1490`	ID do pedido obtido a partir da Preparacao Eko´s Bio.
`bio_48h_status`	Sim	`ok`	Usar `ok` quando completou 48h ou `alerta` quando ainda nao completou.
`bio_48h_horas_decorridas`	Nao	`36.2`	Quantidade aproximada de horas entre a preparacao Bio e o inicio da aplicacao.
`bio_48h_decisao_usuario`	Sim	`continuar`	Usar `nao_aplicavel`, `continuar` ou `cancelar`.
`bio_48h_mensagem`	Nao	`Preparacao EKO´S BIO nao completou 48 horas, deseja continuar?`	Mensagem exibida ao usuario quando houve alerta.
`data_inicio`	Sim	`2026-04-27`	Data em que o usuario clicou em Iniciar Aplicacao.
`hora_inicio`	Sim	`08:10:00`	Hora em que o usuario clicou em Iniciar Aplicacao.
`latitude_inicio`	Sim	`-21.8588800`	Latitude do inicio da aplicacao.
`longitude_inicio`	Sim	`-47.4845167`	Longitude do inicio da aplicacao.
`data_fim`	Sim, exceto cancelada	`2026-04-27`	Data em que a etapa dos produtos foi finalizada.
`hora_fim`	Sim, exceto cancelada	`08:18:00`	Hora em que a etapa dos produtos foi finalizada.
`latitude_fim`	Nao	`-21.8589000`	Latitude ao finalizar a etapa dos produtos.
`longitude_fim`	Nao	`-47.4845450`	Longitude ao finalizar a etapa dos produtos.
`status`	Sim	`finalizada_com_alerta`	Usar `finalizada`, `finalizada_com_alerta` ou `cancelada`.
`observacao`	Nao	`Usuario decidiu continuar antes de 48h.`	Texto livre opcional enviado pelo app.
`produtos`	Sim	`[{...}]`	JSON contendo leituras corretas, confirmacoes e leituras erradas dos produtos. Em cancelamento, enviar `[]`.

O app nao deve enviar manualmente device_id, device_name ou account_type. Esses dados devem ser resolvidos pelo ERP a partir do X-DEVICE-TOKEN.

Campos de cada produto/leitura

Campo	Obrigatorio	Exemplo	Descricao
`client_step_id`	Sim	`step_001`	ID unico local da etapa/produto. Evita duplicidade em reenvios.
`ordem_esperada`	Sim	`1`	Ordem que o app esperava para a etapa atual.
`ordem_lida`	Nao	`1`	Ordem identificada pela regra interna do codigo do produto, quando disponivel.
`qrcode`	Sim	`PROD_A`	Conteudo do QR Code escaneado. Para produtos fixos, normalmente sera o codigo do produto.
`codigo_produto`	Recomendado	`PROD_A`	Codigo extraido do QR Code fixo para validar a ordem da aplicacao.
`tipo_conteudo`	Nao	`g10_produto_aplicacao`	Tipo do conteudo do QR Code.
`data_leitura`	Sim	`2026-04-27`	Data da leitura do QR Code.
`hora_leitura`	Sim	`08:10:00`	Hora da leitura do QR Code.
`latitude_leitura`	Nao	`-21.8588800`	Latitude no momento da leitura.
`longitude_leitura`	Nao	`-47.4845167`	Longitude no momento da leitura.
`confirmado`	Sim	`1`	Indica se o usuario confirmou que despejou o produto no tanque.
`data_confirmacao`	Nao	`2026-04-27`	Data da confirmacao do despejo no tanque.
`hora_confirmacao`	Nao	`08:10:25`	Hora da confirmacao do despejo no tanque.
`latitude_confirmacao`	Nao	`-21.8588810`	Latitude no momento da confirmacao.
`longitude_confirmacao`	Nao	`-47.4845170`	Longitude no momento da confirmacao.
`ordem_status`	Sim	`correta`	Usar `correta` ou `errada`.
`status`	Sim	`confirmado`	Usar `confirmado` para produto correto confirmado ou `erro_ordem` para leitura fora da ordem.
`observacao`	Nao	`Produto lido fora da ordem esperada.`	Observacao opcional para auditoria.

Validacao da ordem dos QR Codes

O app deve validar a ordem dos produtos usando uma regra interna baseada no codigo do produto lido no QR Code. Os QR Codes dos produtos podem ser fixos e conter apenas o codigo do produto, sem vinculo direto com o pedido.

O vinculo com o pedido da aplicacao vem da Preparacao Eko´s Bio. Portanto, todas as leituras realizadas durante a aplicacao serao associadas ao id_pedido obtido no preparo Bio.

Etapa atual: 2
Produto esperado: codigo PROD_B

Se QR Code lido = PROD_B:
    ordem_status = correta
    status = confirmado apos o usuario confirmar o despejo

Se QR Code lido = PROD_D:
    ordem_status = errada
    status = erro_ordem
    confirmado = 0
    app mostra alerta e pede o QR Code correto

Mesmo leituras erradas devem ser salvas localmente e enviadas ao ERP, porque servem como evidencia de tentativa fora da sequencia.

Regra: os produtos validam ordem por codigo; o pedido vem do Preparo Bio.

Exemplo de payload — aplicacao concluida com alerta de 48h

O campo produtos deve ser enviado como string JSON no corpo do POST.

action=apiG10
f=registrar_aplicacao
client_event_id=550e8400-e29b-41d4-a716-446655440000
id_preparo_bio=45
id_pedido=1490
bio_48h_status=alerta
bio_48h_horas_decorridas=36.2
bio_48h_decisao_usuario=continuar
bio_48h_mensagem=Preparacao EKO´S BIO nao completou 48 horas, deseja continuar?
data_inicio=2026-04-27
hora_inicio=08:10:00
latitude_inicio=-21.8588800
longitude_inicio=-47.4845167
data_fim=2026-04-27
hora_fim=08:18:00
latitude_fim=-21.8589000
longitude_fim=-47.4845450
status=finalizada_com_alerta
observacao=Usuario decidiu continuar aplicacao antes de completar 48 horas do preparo Bio.
produtos=[
  {
    "client_step_id": "step_001",
    "ordem_esperada": 1,
    "ordem_lida": 1,
    "qrcode_id": null,
    "qrcode": "PROD_A",
    "codigo_produto": "PROD_A",
    "tipo_conteudo": "g10_produto_aplicacao",
    "data_leitura": "2026-04-27",
    "hora_leitura": "08:10:00",
    "latitude_leitura": -21.8588800,
    "longitude_leitura": -47.4845167,
    "confirmado": 1,
    "data_confirmacao": "2026-04-27",
    "hora_confirmacao": "08:10:25",
    "latitude_confirmacao": -21.8588810,
    "longitude_confirmacao": -47.4845170,
    "ordem_status": "correta",
    "status": "confirmado"
  },
  {
    "client_step_id": "step_002_errado",
    "ordem_esperada": 2,
    "ordem_lida": 4,
    "qrcode_id": null,
    "qrcode": "PROD_D",
    "codigo_produto": "PROD_D",
    "tipo_conteudo": "g10_produto_aplicacao",
    "data_leitura": "2026-04-27",
    "hora_leitura": "08:11:00",
    "latitude_leitura": -21.8588820,
    "longitude_leitura": -47.4845180,
    "confirmado": 0,
    "data_confirmacao": null,
    "hora_confirmacao": null,
    "latitude_confirmacao": null,
    "longitude_confirmacao": null,
    "ordem_status": "errada",
    "status": "erro_ordem",
    "observacao": "Produto lido fora da ordem esperada."
  }
]

Resposta esperada da API

Sucesso HTTP 200

{
  "success": true,
  "msg": "Aplicacao registrada com sucesso.",
  "data": {
    "id_aplicacao": 123,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "id_preparo_bio": 45,
    "id_pedido": 1490,
    "device_id": 26,
    "device_name": "testeG10",
    "account_type": "produtor",
    "total_produtos_esperados": 6,
    "total_produtos_confirmados": 6,
    "total_leituras_erradas": 1,
    "bio_48h_status": "alerta",
    "bio_48h_decisao_usuario": "continuar",
    "status": "finalizada_com_alerta",
    "already_registered": false
  }
}

Reenvio idempotente

{
  "success": true,
  "msg": "Aplicacao ja registrada.",
  "data": {
    "id_aplicacao": 123,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "already_registered": true
  }
}

O app deve salvar id_aplicacao localmente para usar no trajeto.

Como salvar no app

O app deve manter a aplicacao em uma fila local ate conseguir sincronizar com o ERP. O mesmo client_event_id deve ser reutilizado em todas as tentativas de envio da mesma aplicacao.

Estrutura local sugerida

aplicacoes_local
- client_event_id
- id_aplicacao
- id_preparo_bio
- id_pedido
- data_inicio
- hora_inicio
- latitude_inicio
- longitude_inicio
- data_fim
- hora_fim
- latitude_fim
- longitude_fim
- bio_48h_status
- bio_48h_horas_decorridas
- bio_48h_decisao_usuario
- bio_48h_mensagem
- status_local
- sincronizado
- created_at
- updated_at

aplicacao_produtos_local
- client_event_id
- client_step_id
- ordem_esperada
- ordem_lida
- qrcode_id
- qrcode
- codigo_produto
- tipo_conteudo
- data_leitura
- hora_leitura
- latitude_leitura
- longitude_leitura
- confirmado
- data_confirmacao
- hora_confirmacao
- latitude_confirmacao
- longitude_confirmacao
- ordem_status
- status
- observacao

Exemplo TypeScript — montagem do payload

type ProdutoAplicacao = {
  client_step_id: string;
  ordem_esperada: number;
  ordem_lida?: number | null;
  qrcode_id?: number | null;
  qrcode: string;
  codigo_produto?: string | null;
  tipo_conteudo?: string | null;
  data_leitura: string;
  hora_leitura: string;
  latitude_leitura?: number | null;
  longitude_leitura?: number | null;
  confirmado: 0 | 1;
  data_confirmacao?: string | null;
  hora_confirmacao?: string | null;
  latitude_confirmacao?: number | null;
  longitude_confirmacao?: number | null;
  ordem_status: 'correta' | 'errada';
  status: 'confirmado' | 'erro_ordem' | 'lido';
  observacao?: string | null;
};

type RegistrarAplicacaoPayload = {
  action: 'apiG10';
  f: 'registrar_aplicacao';
  client_event_id: string;
  id_preparo_bio: number;
  id_pedido: number;
  bio_48h_status: 'ok' | 'alerta';
  bio_48h_horas_decorridas?: number | null;
  bio_48h_decisao_usuario: 'nao_aplicavel' | 'continuar' | 'cancelar';
  bio_48h_mensagem?: string;
  data_inicio: string;
  hora_inicio: string;
  latitude_inicio: number;
  longitude_inicio: number;
  data_fim?: string;
  hora_fim?: string;
  latitude_fim?: number | null;
  longitude_fim?: number | null;
  status: 'finalizada' | 'finalizada_com_alerta' | 'cancelada';
  observacao?: string;
  produtos: string;
};

Erros comuns

missing_app_key: header X-APP-KEY nao enviado.
invalid_api_key: APP_KEY invalida.
missing_device_token: header X-DEVICE-TOKEN nao enviado.
device_token_not_found: aparelho nao pareado ou token invalido.
missing_client_event_id: client_event_id nao enviado.
invalid_client_event_id: client_event_id invalido.
missing_id_preparo_bio: id_preparo_bio nao enviado.
preparo_bio_not_found: Preparacao Eko´s Bio nao localizada.
missing_id_pedido: id_pedido nao enviado.
pedido_not_found: pedido nao localizado no ERP.
invalid_produtos_json: campo produtos nao e um JSON valido.
empty_produtos: lista de produtos vazia em aplicacao nao cancelada.
produto_codigo_invalido: codigo do produto nao reconhecido na regra da aplicacao.
produto_ordem_invalida: produto lido fora da ordem esperada.

Resumo para o desenvolvedor

O app registra a aplicacao offline e envia depois.
O endpoint e f=registrar_aplicacao.
O id_pedido da aplicacao vem da Preparacao Eko´s Bio.
Os demais produtos podem usar QR Codes fixos com o codigo do produto.
O app deve validar a ordem dos produtos pelo codigo lido no QR Code.
Todas as leituras serao associadas ao id_pedido obtido no Preparo Bio.
Leituras erradas devem ser salvas e enviadas para auditoria.
Se o Bio nao completou 48h, o app deve alertar, registrar a decisao e nao bloquear automaticamente.
O ERP identifica o aparelho pelo X-DEVICE-TOKEN.
A API retorna id_aplicacao.
O app deve salvar id_aplicacao e usa-lo no envio do trajeto.