6) Coleta das Análises

O ERP gera um QRCode do tipo coleta_analise e envia junto com o recipiente. No app, o usuário clica em Iniciar coleta e escaneia o QRCode do recipiente. O aplicativo deve operar em modo offline-first: ao ler o QRCode, deve primeiro registrar o evento localmente, gerar um client_event_id único, salvar o item na fila de sincronização e então tentar enviar para o ERP. Quando a API responder com success=true, o app deve marcar o item como sincronizado e removê-lo da fila local.

Auth: X-APP-KEY + X-DEVICE-TOKEN Formato: JSON ou multipart/form-data Evento: coleta_analise Obrigatório: client_event_id

Observação sobre formato: Sem fotos, o app pode enviar a requisição em JSON ou form-urlencoded, conforme o padrão do router. Quando houver foto_1 e/ou foto_2, o envio deve ser feito em multipart/form-data.

Fluxo resumido

  1. ERP cria um pedido de serviço (análise) e gera um QRCode coleta_analise apontando para pedidos.
  2. App abre “Iniciar coleta” e escaneia o QRCode do recipiente.
  3. App gera um client_event_id único para este evento, salva localmente os dados da coleta e registra o item na fila/outbox com status pendente de envio.
  4. App tenta sincronizar com a API enviando data, hora, latitude, longitude, qrcode e client_event_id e até 2 fotos da coleta (foto_1 e foto_2)..
  5. API valida autenticação, valida o QRCode, identifica o pedido, processa a coleta e controla a idempotência pelo client_event_id.
  6. Se a API responder success=true, o app deve marcar o evento como sincronizado e removê-lo da fila local. Se a API responder erro, o evento deve permanecer salvo localmente para novo envio posterior usando o mesmo client_event_id.

Endpoint: Procedimento da coleta

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

Headers

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

Body

action=apiG10
f=coleta_analise
client_event_id=<UUID>
qrcode=<CONTEUDO_DO_QR>
data=YYYY-MM-DD
hora=HH:MM:SS
latitude=<LAT>
longitude=<LON>
foto_1=(ARQUIVO_OU_BASE64)
foto_2=(ARQUIVO_OU_BASE64)

Respostas esperadas da API

Sucesso (HTTP 200)

{
  "success": true,
  "msg": "Coleta de análise registrada com sucesso.",
  "data": {
    "qrcode": "CA_...",
    "cliente_id": 123,
    "device_id": 999,
    "account_type": "produtor",
    "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
    "codigo_referencia": "SE1001",
    "descricao_referencia": "ANÁLISE DE SOLO"
  }
}

Reenvio idempotente (HTTP 200)

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

Erro (HTTP != 200)

{
  "success": false,
  "error": "invalid_qrcode",
  "msg": "QR Code da coleta inválido ou não encontrado.",
  "data": {}
}
Observação: client_event_id é obrigatório (offline/outbox/idempotência)
Observação: a idempotência desta rota é controlada pelo client_event_id. O app deve reutilizar o mesmo client_event_id em todos os reenvios do mesmo evento.

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

  • O app deve sempre trabalhar em offline-first, mesmo quando houver internet disponível.
  • Ao escanear o QRCode, o app deve primeiro salvar o evento em banco local no aparelho.
  • No mesmo momento, deve gerar um client_event_id único e associá-lo ao evento local.
  • O evento deve entrar em uma fila/outbox de sincronização para envio ao ERP.
  • Se o envio falhar por timeout, queda de internet ou erro transitório, o evento deve permanecer salvo localmente e continuar pendente de sincronização.
  • Em cada novo envio do mesmo evento, o app deve reutilizar exatamente o mesmo client_event_id.
  • Quando a API responder success=true, o app deve marcar o evento como sincronizado e removê-lo da fila local.
  • Quando a API responder success=true com already_registered=true, o app também deve considerar o evento como concluído, removendo-o da fila local.
  • Somente respostas com success=false devem manter o evento pendente para novo envio, conforme a política de retry do aplicativo.

Como a API identifica a análise

A API consulta o pedido (pedidos) e busca o item de serviço de análise em pedidos_itens.id_produto_referencia, relacionando com produtos_referencia e produtos.

  • produtos.id_categoria deve ser 5 (Serviços)
  • produtos.id_subcategoria deve ser 5 (Análises)
  • Campos retornados ao app: produtos_referencia.codigo_referencia e produtos_referencia.descricao_referencia.
Ex.: SE1001 = ANÁLISE DE SOLO | SE1000 = ANÁLISE DE FOLHA

Regras das fotos - atualizado 23/04/26.

Quando houver fotos da coleta, elas também devem ser salvas localmente no aparelho antes de qualquer tentativa de envio. Essas fotos devem permanecer vinculadas ao mesmo client_event_id do evento de coleta. Se a sincronização falhar, o evento e suas fotos devem continuar pendentes para novo envio posterior.

  • Tamanho máximo recomendado: 5 MB por foto
  • Nos reenvios do mesmo evento, o app deve reutilizar o mesmo client_event_id e reenviar novamente as fotos vinculadas àquele evento, quando existirem.