5) Recebimento — Kit de aplicação

Será gerado um QR Code aleatório no ERP (AGROECOLOGIA), impresso e colado na caixa do kit de aplicação. Quando o kit chegar ao produtor, o recebimento deve ser informado pelo app — pode ser feito tanto por produtor quanto por colaborador, desde que o app esteja instalado e pareado. O aplicativo deve operar em modo offline-first: ao ler o QRCode, deve registrar o evento localmente, gerar um client_event_id único, salvar na fila/outbox e então tentar sincronizar com o ERP.

Menu liberado: produtor + colaborador Endpoint: router/action.php Auth: X-APP-KEY + X-DEVICE-TOKEN Formato: JSON (via router) Obrigatório: client_event_id

Objetivo deste fluxo

Registrar o recebimento do Kit de Aplicação no ERP a partir do app, usando o QR Code colado na caixa. O app envia QR do kit + data/hora + geolocalização + client_event_id e a API valida com base no DEVICE_TOKEN (identifica o cliente automaticamente). A idempotência é controlada pelo client_event_id.

Como funciona no app (passo a passo)

  1. O usuário entra no menu Entrega → Kit de Aplicação (disponível para produtor e colaborador).
  2. O app exibe: “Escaneie o QRCode do kit de aplicação”.
  3. Ao ler o QRCode, o app deve gerar um client_event_id único para este evento.
  4. O app deve salvar localmente os dados do recebimento e registrar o item na fila/outbox com status pendente de sincronização.
  5. Se houver internet, o app tenta sincronizar imediatamente enviando X-APP-KEY, X-DEVICE-TOKEN, conteúdo do QRCode, data/hora, geolocalização e client_event_id.
  6. Se a API responder HTTP 200 com success=true, o app deve marcar o evento como sincronizado e removê-lo da fila local.
  7. Se a API responder HTTP 200 com already_registered=true, o app também deve considerar o evento concluído e removê-lo da fila local.
  8. Se a API responder erro ou houver falha de conexão, o app deve manter o evento salvo localmente para novo envio posterior, reutilizando 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 embutida no app (camada extra contra chamadas externas).
  • X-DEVICE-TOKEN: token do dispositivo pareado. A API usa isso para identificar o cliente e validar o acesso.

Body (via router)

Enviar no body (form-url-encoded ou JSON, conforme padrão do router), com:

action=apiG10
f=receber_kit_aplicacao
client_event_id=<UUID>
qrcode=<CONTEUDO_DO_QR>
data=YYYY-MM-DD
hora=HH:MM:SS
latitude=<LAT>
longitude=<LON>

Campos que devem ser enviados

Campo Obrigatório Exemplo Descrição
qrcode Sim KIT_3f9a2c... (conteúdo lido) Conteúdo do QRCode colado na caixa do kit (string lida pelo scanner).
data Sim 2026-03-11 Data do recebimento informada pelo app (recomendado ISO: YYYY-MM-DD).
hora Sim 14:32:10 Hora do recebimento informada pelo app (HH:MM:SS).
latitude Sim -20.9487 Latitude capturada no momento do recebimento (GPS do aparelho).
longitude Sim -48.4790 Longitude capturada no momento do recebimento (GPS do aparelho).
client_event_id Sim 550e8400-e29b-41d4-a716-446655440000 ID único gerado pelo app (UUID). O mesmo ID deve ser reutilizado em todos os reenvios do mesmo evento.
Observação: além do body, a autenticação depende dos headers X-APP-KEY e X-DEVICE-TOKEN.

Respostas esperadas da API

Sucesso (HTTP 200)

Quando a validação estiver ok e o recebimento for registrado, a API retorna:

{
  "success": true,
  "msg": "Recebimento do kit registrado com sucesso.",
  "data": {
    "qrcode": "KIT_...",
    "cliente_id": 123,
    "device_id": 999,
    "account_type": "produtor",
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Ao receber esta resposta, o app deve considerar o evento sincronizado com sucesso, marcar o item como enviado e removê-lo da fila local.

Reenvio idempotente (HTTP 200)

Se o app reenviar o mesmo evento (mesmo client_event_id), o servidor não duplica o registro e retorna: 

{
  "success": true,
  "msg": "Evento já registrado (idempotente).",
  "data": {
    "already_registered": true,
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Ao receber esta resposta, o app também deve considerar o evento concluído, marcando o item como enviado e removendo-o da fila local.

Erro (HTTP != 200)

Em caso de erro, a API retorna success=false com um error curto e um msg amigável: 

{
  "success": false,
  "error": "invalid_qrcode",
  "msg": "QR Code do kit inválido ou não encontrado.",
  "data": {}
}
  • Se for erro de autenticação (401/403): orientar o usuário a reparear ou contatar suporte.
  • Se for erro de QRCode (404/409): orientar tentar novamente e conferir o QRCode.
  • Se for erro inesperado (500): orientar contatar o suporte.
Regra prática: success=true ou already_registered=true = remover da fila local

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

  • O app deve sempre trabalhar em offline-first, mesmo quando houver internet disponível.
  • O evento deve nascer primeiro no banco local do aparelho, antes da tentativa de envio.
  • O app deve manter uma fila/outbox dos eventos pendentes de sincronização.
  • O ERP usa o client_event_id para idempotência: se esse ID já existir no servidor, o evento já foi processado com sucesso.
  • O mesmo client_event_id deve ser reutilizado em todas as tentativas do mesmo recebimento.
  • Somente após resposta positiva da API o item deve sair do banco local/fila de sincronização.

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=receber_kit_aplicacao&client_event_id=550e8400-e29b-41d4-a716-446655440000&qrcode=KIT_ABC123&data=2026-03-11&hora=14:32:10&latitude=-20.9487&longitude=-48.4790"