G10 Bio Produtor — Retirada de Produtos

Objetivo deste fluxo

Registrar que o produtor retirou uma embalagem de produto na associação ou em outro ponto de entrega. O aplicativo deve guardar o conteúdo lido, data, hora, localização e identificação do aparelho.

Não existe QR Code exclusivo de retirada gerado pelo ERP. O app lê diretamente o QR Code ou código de barras já presente na embalagem do produto.

Como funciona no aplicativo

O produtor acessa o menu Retirar Produtos.
O app abre a câmera para leitura do QR Code ou código de barras da embalagem.
Após a leitura, o app gera um client_event_id único.
O evento é salvo primeiro no SQLite com status pendente.
O app registra data, hora, latitude, longitude e nome do aparelho.
Havendo internet, o app tenta executar imediatamente a sincronização offline.
Sem internet ou em caso de falha, o evento permanece na fila local.
Nos reenvios, o app reutiliza o mesmo client_event_id.
O evento somente sai da fila após confirmação explícita do ERP.

Endpoint utilizado

A retirada de produtos não possui endpoint próprio. Ela é enviada pelo endpoint geral de sincronização offline do aplicativo produtor.

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

Headers obrigatórios

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

Identificação da rota

action=apiG10bio_produtor
f=sincronizacao_offline

O ERP identifica os eventos de retirada pelo campo eventos_retirada enviado na sincronização.

Estrutura do evento no SQLite

Campo	Obrigatório	Descrição
`client_event_id`	Sim	UUID único do evento. Deve permanecer igual em todos os reenvios.
`codigo_lido`	Sim	Conteúdo bruto obtido pela câmera.
`tipo_codigo`	Sim	Tipo identificado pelo leitor, por exemplo `qrcode` ou `codigo_barras`.
`data`	Sim	Data da retirada no formato YYYY-MM-DD.
`hora`	Sim	Hora da retirada no formato HH:MM:SS.
`latitude`	Sim	Latitude capturada no momento da leitura.
`longitude`	Sim	Longitude capturada no momento da leitura.
`device_name`	Sim	Nome ou modelo do aparelho que registrou a retirada.
`status_sincronizacao`	Local	Controle interno do SQLite, por exemplo `PENDENTE` ou `CONFIRMADO`.

Exemplo do evento de retirada

{
  "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
  "codigo_lido": "7891234567890",
  "tipo_codigo": "codigo_barras",
  "data": "2026-07-23",
  "hora": "08:30:00",
  "latitude": -21.864500,
  "longitude": -47.499700,
  "device_name": "Samsung Galaxy A15"
}

Envio dentro da sincronização offline

As retiradas pendentes devem ser agrupadas no array eventos_retirada.

{
  "action": "apiG10bio_produtor",
  "f": "sincronizacao_offline",
  "app_version": "1.0.0",
  "last_sync_at": "2026-07-23 08:00:00",
  "eventos_retirada": [
    {
      "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
      "codigo_lido": "7891234567890",
      "tipo_codigo": "codigo_barras",
      "data": "2026-07-23",
      "hora": "08:30:00",
      "latitude": -21.864500,
      "longitude": -47.499700,
      "device_name": "Samsung Galaxy A15"
    }
  ],
  "sessoes_aplicacao": [],
  "pontos_aplicacao": []
}

Outros tipos de eventos também devem possuir seus próprios arrays dentro da mesma sincronização. Isso permite que o ERP identifique e processe cada grupo separadamente.

Processamento esperado no ERP

Validar X-APP-KEY e X-DEVICE-TOKEN.
Identificar o produtor vinculado ao aparelho.
Localizar o vínculo ativo do produtor com o franqueado.
Percorrer o array eventos_retirada.
Validar os campos obrigatórios de cada item.
Verificar se o client_event_id já foi processado.
Se ainda não existir, registrar a retirada.
Se já existir, não duplicar o registro.
Retornar o client_event_id em eventos_confirmados.retiradas.

Confirmação esperada do ERP

{
  "success": true,
  "msg": "Sincronização realizada com sucesso.",
  "data": {
    "server_time": "2026-07-23 08:31:10",
    "eventos_confirmados": {
      "retiradas": [
        "550e8400-e29b-41d4-a716-446655440000"
      ],
      "sessoes_aplicacao": [],
      "pontos_aplicacao": []
    }
  }
}

O app deve remover da fila somente os eventos cujo client_event_id estiver presente em eventos_confirmados.retiradas.

Falhas e reenvio

Falha de internet: manter o evento pendente.
Timeout: manter o evento pendente.
Erro HTTP 500: manter o evento pendente.
Evento não confirmado na resposta: manter o evento pendente.
Reenviar sempre com o mesmo client_event_id.
Nunca gerar outro identificador para a mesma retirada.

Regras importantes

O evento deve nascer primeiro no SQLite.
O ERP é a fonte oficial dos dados.
O aplicativo não precisa baixar QR Codes antecipadamente.
O app não deve confiar em id_franqueado enviado localmente.
O vínculo atual deve ser identificado pelo ERP usando o produtor associado ao aparelho.
A leitura pode conter QR Code ou código de barras.
O conteúdo lido deve ser preservado sem alterações.
Somente eventos confirmados pelo ERP podem ser removidos da fila.

NÃO IMPLEMENTAR neste fluxo

Endpoint exclusivo para retirada de produtos.
QR Code aleatório gerado especificamente para a retirada.
Download antecipado de QR Codes.
Remoção da fila apenas porque a requisição retornou HTTP 200.
Alteração do client_event_id em tentativas posteriores.
Uso do controlador apiG10bio_franqueado.

Exemplo de chamada cURL

curl -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: SUA_APP_KEY" \
  -H "X-DEVICE-TOKEN: SEU_DEVICE_TOKEN" \
  --data-urlencode "action=apiG10bio_produtor" \
  --data-urlencode "f=sincronizacao_offline" \
  --data-urlencode "app_version=1.0.0" \
  --data-urlencode "last_sync_at=2026-07-23 08:00:00" \
  --data-urlencode 'eventos_retirada=[{"client_event_id":"550e8400-e29b-41d4-a716-446655440000","codigo_lido":"7891234567890","tipo_codigo":"codigo_barras","data":"2026-07-23","hora":"08:30:00","latitude":-21.864500,"longitude":-47.499700,"device_name":"Samsung Galaxy A15"}]' \
  --data-urlencode "sessoes_aplicacao=[]" \
  --data-urlencode "pontos_aplicacao=[]"