7) Preparação Eko´s Bio

O aplicativo terá no menu o botão Preparação Eko´s Bio. O usuário deve escanear o QRCode específico do produto/preparo, previamente sincronizado no app como tipo_conteudo=preparo_bio. Após validar o QRCode offline, o app registra localmente o evento, gera um client_event_id único e envia para o ERP o qrcode_id, data, hora, geolocalização e as credenciais padrão do app. A API identifica o aparelho pelo X-DEVICE-TOKEN e registra também possíveis divergências entre o cliente do QRCode e o cliente do aparelho.

Menu liberado: produtor + produtor_funcionario + colaborador Endpoint: router/action.php Auth: X-APP-KEY + X-DEVICE-TOKEN Tabela: g10_preparo_bio Obrigatório: client_event_id QRCode obrigatório: preparo_bio Offline-first

Objetivo deste fluxo

Registrar no ERP que a Preparação Eko´s Bio foi realizada pelo aplicativo usando um QRCode específico do tipo preparo_bio, atrelado a um pedido/kit. O registro fica vinculado ao cliente dono do QRCode, à participação G10, ao pedido, ao qrcode_id e ao aparelho que executou o procedimento.

Caso o QRCode pertença a outro cliente, o ERP não bloqueia o registro. O evento é salvo com validacao_qrcode=cliente_diferente e com uma mensagem em alerta_qrcode, permitindo análise posterior de possível divergência/fraude.

A identificação do aparelho é feita pelo header X-DEVICE-TOKEN. A API usa esse token para descobrir o device_id, id_cliente e account_type.

Como funciona no app (passo a passo)

  1. O usuário acessa o menu Preparação Eko´s Bio.
  2. O app solicita a leitura do QRCode do produto/preparo Eko´s Bio.
  3. O app valida no banco local se o QRCode existe, está ativo e possui tipo_conteudo=preparo_bio.
  4. O app identifica o qrcode_id sincronizado para aquele QRCode.
  5. Após concluir o procedimento, o app gera um client_event_id único.
  6. O app captura data, hora, latitude e longitude.
  7. O app salva o evento localmente em fila/outbox com status pendente.
  8. Se houver internet, o app envia o evento para o ERP usando X-APP-KEY e X-DEVICE-TOKEN.
  9. Se a API retornar success=true, o app marca o evento como sincronizado.
  10. Se a API retornar already_registered=true, o app também deve considerar como sincronizado.
  11. Se houver erro de conexão ou erro temporário, o app mantém o evento na fila e reenvia depois usando o mesmo client_event_id.

Endpoint

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

Headers obrigatórios

X-APP-KEY: <APP_KEY_FIXA_DO_APP>
X-DEVICE-TOKEN: <DEVICE_TOKEN_DO_APARELHO>
  • X-APP-KEY: chave fixa do aplicativo.
  • X-DEVICE-TOKEN: token permanente do aparelho pareado.

Body

Enviar no body, seguindo o padrão do router:

action=apiG10
f=preparo_ekos_bio
client_event_id=<UUID_OU_ID_UNICO_DO_APP>
qrcode_id=<ID_DO_QRCODE_SINCRONIZADO>
data=YYYY-MM-DD
hora=HH:MM:SS
latitude=<LAT>
longitude=<LON>
observacao=<OPCIONAL>

Campos enviados pelo app

Campo Obrigatório Exemplo Descrição
action Sim apiG10 Identifica o controller/ação do router.
f Sim preparo_ekos_bio Função/case responsável por registrar a preparação.
client_event_id Sim 550e8400-e29b-41d4-a716-446655440000 ID único gerado pelo app. Deve ser reutilizado em todos os reenvios do mesmo evento. A API usa este campo para evitar duplicidade.
qrcode_id Sim 11 ID do QRCode sincronizado offline. Deve existir no cache local do app, estar ativo e possuir tipo_conteudo=preparo_bio. No ERP, esse QRCode fica vinculado ao pedido em qr_codes.nome_tabela=pedidos e qr_codes.id_tabela=<número do pedido>.
qrcode_id Sim 11 ID do QRCode sincronizado offline. Deve ser do tipo preparo_bio, vinculado a nome_tabela=pedidos e ao número do pedido em id_tabela.
data Sim 2026-04-24 Data em que o procedimento foi realizado. Formato recomendado: YYYY-MM-DD.
hora Sim 14:32:10 Hora em que o procedimento foi realizado. Formato recomendado: HH:MM:SS.
latitude Sim -20.9487000 Latitude capturada pelo GPS do aparelho no momento do procedimento.
longitude Sim -48.4790000 Longitude capturada pelo GPS do aparelho no momento do procedimento.
observacao Não Procedimento concluído sem intercorrências. Campo livre para observações do app, quando houver.
O aparelho, cliente e tipo de usuário são identificados pelo X-DEVICE-TOKEN.

Respostas esperadas da API

Sucesso (HTTP 200)

Quando a preparação for registrada com sucesso:

{
  "success": true,
  "msg": "Preparação Eko´s Bio registrada com sucesso.",
  "data": {
    "id_preparo_bio": 123,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "qrcode_id": 11,
    "id_pedido": 1509,
    "cliente_id": 123,
    "cliente_id_device": 123,
    "id_g10": 10,
    "device_id": 8,
    "device_name": "Tablet do Trator",
    "account_type": "produtor_funcionario",
    "validacao_qrcode": "ok",
    "alerta_qrcode": null
  }
}

Ao receber esta resposta, o app deve considerar o evento sincronizado com sucesso e remover o item da fila/outbox local.

Sucesso com alerta de divergência (HTTP 200)

Se o QRCode for válido e do tipo preparo_bio, mas pertencer a outro cliente, a API não bloqueia o registro. O evento é salvo com alerta para auditoria posterior: 

{
  "success": true,
  "msg": "Preparação Eko´s Bio registrada com sucesso.",
  "data": {
    "id_preparo_bio": 124,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440001",
    "qrcode_id": 11,
    "id_pedido": 1509,
    "cliente_id": 200,
    "cliente_id_device": 123,
    "id_g10": 10,
    "device_id": 8,
    "device_name": "Tablet do Trator",
    "account_type": "produtor",
    "validacao_qrcode": "cliente_diferente",
    "alerta_qrcode": "ALERTA: QRCode de preparo bio pertence ao cliente #200, mas foi registrado por aparelho vinculado ao cliente #123."
  }
}

Reenvio idempotente (HTTP 200)

Se o app reenviar o mesmo evento com o mesmo client_event_id, o servidor não deve duplicar o registro: 

{
  "success": true,
  "msg": "Preparação Eko´s Bio já registrada.",
  "data": {
    "id_preparo_bio": 123,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "cliente_id": 45,
    "device_id": 8,
    "account_type": "produtor_funcionario",
    "already_registered": true
  }
}

Ao receber already_registered=true, o app também deve considerar o evento concluído e remover da fila local.

Erro (HTTP diferente de 200)

Em caso de erro, a API retorna success=false:

{
  "success": false,
  "error": "g10_participacao_not_found",
  "msg": "Cliente não possui participação no G10.",
  "data": {}
}
  • 401: token do aparelho ausente, inválido, expirado ou revogado.
  • 403: APP_KEY inválida.
  • 400: campos obrigatórios ausentes ou inválidos.
  • 409: cliente não possui participação G10 válida.
  • 500: erro interno ou falha no banco.
Regra prática: success=true ou already_registered=true = remover da fila local

Registro no banco de dados

O endpoint grava os dados na tabela g10_preparo_bio. 

SELECT
    id,
    client_event_id,
    qrcode_id,
    id_cliente,
    id_cliente_device,
    id_g10,
    device_id,
    account_type,
    data_preparo,
    hora_preparo,
    latitude,
    longitude,
    validacao_qrcode,
    alerta_qrcode,
    status,
    observacao,
    criado_em,
    atualizado_em,
    atualizado_por
FROM g10_preparo_bio;

Campos principais

Campo Descrição
client_event_id ID único gerado pelo app para garantir idempotência.
qrcode_id ID do QRCode usado no preparo. Permite cruzar com qr_codes, pedido, cliente e produto.
id_cliente Cliente dono do QRCode/pedido.
id_cliente_device Cliente vinculado ao aparelho que realizou o registro.
validacao_qrcode Resultado da validação do QRCode. Valores esperados: ok ou cliente_diferente.
alerta_qrcode Mensagem de auditoria quando o QRCode pertence a outro cliente.
id_g10 Participação G10 vinculada ao cliente.
device_id ID do token/aparelho que registrou o procedimento.
account_type Perfil do aparelho: produtor, produtor_funcionario ou colaborador.
data_preparo / hora_preparo Data e hora informadas pelo app.
latitude / longitude Geolocalização do aparelho no momento da preparação.
status Status do registro. Padrão: 1 ativo.
observacao Observação opcional enviada pelo app.

Modo de operação do app (offline-first)

  • O evento deve ser salvo primeiro no banco local do app.
  • O app deve gerar e manter o mesmo client_event_id para o mesmo procedimento.
  • O app deve manter uma fila/outbox de eventos pendentes de envio.
  • Se a conexão falhar, o app deve tentar reenviar posteriormente.
  • O app só deve remover o evento da fila após resposta positiva da API.
  • success=true significa sincronizado.
  • already_registered=true também significa sincronizado.

Exemplo de chamada (cURL)

curl -i -X POST "https://agroecologia.grupoekos.com.br/router/action.php" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -H "X-APP-KEY: APP_KEY_FIXA_DO_APP" \
  -H "X-DEVICE-TOKEN: dev_xxxxxxxxxxxxxxxxx" \
  --data "action=apiG10&f=preparo_ekos_bio&client_event_id=550e8400-e29b-41d4-a716-446655440000&qrcode_id=11&data=2026-04-24&hora=14:32:10&latitude=-20.9487000&longitude=-48.4790000&observacao=Procedimento concluido"

Checklist para o app

  • Criar botão/menu Preparação Eko´s Bio.
  • Exigir que o app esteja pareado com DEVICE_TOKEN.
  • Gerar client_event_id único para cada procedimento.
  • Capturar data e hora do procedimento.
  • Capturar latitude e longitude.
  • Salvar evento localmente antes de enviar.
  • Enviar headers X-APP-KEY e X-DEVICE-TOKEN.
  • Enviar body com action=apiG10 e f=preparo_ekos_bio.
  • Remover da fila local quando success=true.
  • Remover da fila local quando already_registered=true.
  • Manter na fila quando houver erro de conexão ou erro temporário.