Boas práticas e troubleshooting

const POLLING_INTERVAL = 30000; // 30 segundos

setInterval(async () => {
  try {
    const events = await fetchEvents();
    for (const event of events) {
      await processEvent(event);
      await acknowledgeEvent(event.eventId);
    }
  } catch (error) {
    logger.error('Polling failed', error);
  }
}, POLLING_INTERVAL);

async function processEvent(event) {
  // 1. Processar
  await updateOrderStatus(event.orderId, event.type);

  // 2. Acknowledge IMEDIATAMENTE
  await acknowledgeEvent(event.eventId);

  // Sem acknowledge = reprocessamento contínuo
}

const processedEventIds = new Set();

async function processEvent(event) {
  if (processedEventIds.has(event.eventId)) {
    logger.info(`Event ${event.eventId} already processed`);
    return; // Ignorar duplicata
  }

  // ... processar evento ...

  processedEventIds.add(event.eventId);
}

// Limpar Set periodicamente (ex: a cada 24h)
setInterval(() => {
  processedEventIds.clear();
}, 24 * 60 * 60 * 1000);

const TOKEN_BUFFER = 5 * 60 * 1000; // 5 minutos

async function ensureValidToken() {
  if (!token || isExpiringSoon(token)) {
    token = await refreshToken();
    token.refreshedAt = Date.now();
  }
  return token;
}

function isExpiringSoon(token) {
  const expiresIn = token.expiresAt - Date.now();
  return expiresIn < TOKEN_BUFFER;
}

async function requestWithRetry(fn, maxRetries = 5) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // Erros transientes: retry
      if (isTransient(error)) {
        if (attempt < maxRetries) {
          const delay = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s, 8s...
          const jitter = Math.random() * 1000; // Evita thundering herd
          await sleep(delay + jitter);
          continue;
        }
      }
      // Erros permanentes: falhar imediatamente
      throw error;
    }
  }
}

function isTransient(error) {
  // 5xx, timeouts, rate limiting
  return error.status >= 500 ||
         error.status === 429 ||
         error.code === 'ECONNREFUSED';
}

const logEntry = {
  timestamp: new Date().toISOString(),
  orderId: order.id,
  operation: 'requestDriver',
  status: 'success',
  duration: Date.now() - startTime,
  attempt: currentAttempt,
  error: error?.message,
  statusCode: response?.status,
};

logger.info('Shipping operation', logEntry);

// Validar orderId
function isValidUUID(uuid) {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid);
}

// Validar telefone
function isValidPhone(countryCode, areaCode, number) {
  return countryCode === '55' && // Brasil
         areaCode.length === 2 &&
         (number.length === 8 || number.length === 9);
}

// Validar CEP
function isValidCEP(cep) {
  return /^\d{8}$/.test(cep.replace('-', ''));
}

// Validar coordenadas
function isValidCoordinates(lat, lng) {
  return lat >= -90 && lat <= 90 &&
         lng >= -180 && lng <= 180;
}

// Validar quoteId antes de usar
function isValidQuote(quote) {
  return quote &&
         isValidUUID(quote.id) &&
         new Date(quote.expirationAt) > new Date();
}

1. Tempo médio de preparo (benchmarking)
   Ex: 12 minutos

2. Adicionar margem para picos
   Ex: +3 minutos

3. Converter para segundos
   (12 + 3) * 60 = 900 segundos

Semana 1: preparationTime = 900s (15 min)
  ↓ (Monitorar entregas)
  ↓
Se entregador chega muito cedo:
  → Aumentar para 1000s (16 min)

Se entregador chega muito tarde:
  → Diminuir para 800s (13 min)

Pedido criado
  ↓
REQUEST_DRIVER (202)
  ↓
Polling... aguardando sucesso
  ↓
REQUEST_DRIVER_SUCCESS
  ↓ (AGORA sim, consultar tracking)
  ↓
GET /tracking

// Após REQUEST_DRIVER_SUCCESS
setInterval(async () => {
  try {
    const tracking = await getTracking(orderId);
    updateUI(tracking);
  } catch (error) {
    if (error.status === 404) {
      logger.info('Tracking not yet available');
      // Entregador ainda sendo atribuído, retry depois
    }
  }
}, 30000); // 30 segundos

const tracking = await getTracking(orderId);

// Seguro: verifica null antes de usar
if (tracking.latitude && tracking.longitude) {
  updateMapMarker(tracking.latitude, tracking.longitude);
}

// Pode ser null
if (tracking.expectedDelivery) {
  updateETA(tracking.expectedDelivery);
}

// Pode ser negativo (atraso em coleta)
const pickupDelay = tracking.pickupEtaStart < 0
  ? `Atrasado ${Math.abs(tracking.pickupEtaStart)}s`
  : `Faltam ${tracking.pickupEtaStart}s`;

1. Taxa de sucesso por endpoint
   - Alerta: < 95%
   - Intervalo: 1 hora

2. Latência P95
   - Alerta: > 5 segundos
   - Intervalo: 5 minutos

3. Taxa de erro por tipo
   - Alerta: HighDemand > 20%
   - Intervalo: 15 minutos

4. Polling falhas consecutivas
   - Alerta: > 3 falhas seguidas
   - Intervalo: tempo real

5. Taxa de timeout
   - Alerta: > 5%
   - Intervalo: 1 hora

1. Falta de renovação de token
   → Todas requisições falharão com 401

2. Polling parado
   → Eventos não serão processados

3. Taxa de erro > 10% por 30 min
   → Problema sistêmico em andamento

4. Atraso de evento > 5 min
   → Possível gargalo no sistema

// CORRETO
const response = await requestDriver(orderId, quoteId);
logger.info('Alocação solicitada, aguardando confirmação...');

// Depois, monitorar eventos
// Só confirmar quando receber REQUEST_DRIVER_SUCCESS

async function cancelOrder(orderId) {
  const idempotencyKey = `cancel-${orderId}-${Date.now()}`;

  return fetch(`/orders/${orderId}/cancel`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      reason: 'Cliente solicitou',
      cancellationCode: 817
    })
  });
}

// Monitorar evento para obter código
function handleEvent(event) {
  if (event.type === 'DELIVERY_DROP_CODE_REQUESTED') {
    const code = event.metadata.CODE;

    // Notificar cliente via SMS/email/app
    sendCodeToCustomer(customer.phone, code);

    // Instruir entregador a solicitar código
    updateDeliveryInstructions(orderId,
      `Solicitar código ${code} antes de entregar`);
  }
}

const safeDelivery = await getSafeDeliveryScore(orderId);

switch(safeDelivery.score) {
  case 'LOW':
    // Requerer validação adicional
    sendVerificationToCustomer(orderId);
    addAlert(`Entrega de risco baixo: ${orderId}`);
    break;

  case 'MODERATE':
    // Monitorar normalmente
    logger.info(`Moderate risk: ${orderId}`);
    break;

  case 'HIGH':
  case 'VERY_HIGH':
    // Processamento padrão
    break;
}

Pedidos na plataforma:
  [ ] GET /deliveryAvailabilities funciona
  [ ] POST /requestDriver retorna 202
  [ ] Eventos são recebidos
  [ ] GET /tracking funciona após sucesso
  [ ] Cancelamento funciona

Pedidos fora da plataforma:
  [ ] GET /merchants/{merchantId}/deliveryAvailabilities funciona
  [ ] POST /merchants/{merchantId}/orders retorna 202 + trackingUrl
  [ ] Código de confirmação é recebido
  [ ] Alterações de endereço funcionam
  [ ] Safe Delivery Score funciona

Erros:
  [ ] HighDemand é tratado com retry
  [ ] 404 em tracking é ignorado antes de sucesso
  [ ] Rate limiting é respeitado
  [ ] Tokens expirados são renovados

Monitoramento:
  [ ] Logs estruturados em todos pontos
  [ ] Alertas configurados
  [ ] Dashboard visível
  [ ] Métricas sendo coletadas

Tentativa 1: 1s
Tentativa 2: 2s
Tentativa 3: 4s
Tentativa 4: 8s
Tentativa 5: 16s

Formato válido: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Exemplo: 57cd1046-2e06-446f-a2dd-18a518212c3c

1. Solicitar entregador (202)
2. Aguardar evento REQUEST_DRIVER_SUCCESS (polling)
3. Depois disso, tracking fica disponível

1. Polling a cada 30s?       ✓
2. Reconhecimento de events? ✓
3. Deduplicação por ID?      ✓
4. Logs de cada evento?      ✓

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 1693...

GET /deliveryAvailabilities
  ↓ (valida cobertura + pega quoteId)
  ↓
POST /requestDriver (com quoteId)

async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (isTransient(error) && attempt < maxRetries) {
        const delay = Math.pow(2, attempt - 1) * 1000;
        await sleep(delay);
      } else {
        throw error;
      }
    }
  }
}

function isTransient(error) {
  return error.status >= 500 || error.status === 429;
}

- Taxa de sucesso por endpoint
- Latência P95 (95º percentil)
- Erros por tipo
- Tempo de polling a processamento
- Taxa de timeout

timestamp: 2023-08-17T20:10:00Z
orderId: 57cd1046-2e06-446f-a2dd-18a518212c3c
operation: requestDriver
status: success
duration: 150ms