Integración API: Mejores Prácticas

Integrar QuickDTE en tu sistema es sencillo, pero seguir las mejores prácticas garantiza una implementación robusta y escalable.

1. Idempotencia

¿Qué es?

La idempotencia garantiza que ejecutar la misma operación múltiples veces produce el mismo resultado. Esto es crítico para evitar DTEs duplicados.

Cómo Implementarla

Incluye un header X-Idempotency-Key en cada request:

const response = await fetch('https://api.quickdte.com/v1/dte/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Idempotency-Key': `order-${orderId}-${timestamp}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(dtePayload)
});

Tips:

• Usa IDs únicos de tu sistema (orderId, transactionId)
• Incluye timestamp para diferenciar reintentos legítimos
• Guarda la key usada para debugging

---

2. Manejo de Errores

Tipos de Error

| Código | Tipo | Acción | |--------|------|--------| | 400 | Validación | Corregir payload | | 401 | Autenticación | Renovar token | | 409 | Duplicado | Usar idempotency key | | 429 | Rate limit | Esperar, retry con backoff | | 500+ | Servidor | Retry con backoff |

Retry con Backoff Exponencial

async function processWithRetry(payload: DtePayload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await processDTE(payload);
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      if (!isRetryable(error)) throw error;
      
      const delay = Math.pow(2, attempt) * 1000;
      await sleep(delay);
    }
  }
}

---

3. Webhooks

Configuración

Registra tu endpoint en el dashboard de QuickDTE:

https://tu-sistema.com/webhooks/quickdte

Validar Firma

Siempre valida la firma HMAC del webhook:

import crypto from 'crypto';

function validateWebhook(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Eventos Disponibles

| Evento | Descripción | |--------|-------------| | dte.processed | DTE procesado exitosamente | | dte.rejected | DTE rechazado por MH | | dte.contingency | Entró en modo contingencia | | dte.recovered | Recuperado de contingencia |

---

4. Rate Limiting

Límites por Plan

| Plan | Requests/min | DTEs/día | |------|-------------|----------| | Starter | 60 | 1,000 | | Pro | 300 | 10,000 | | Enterprise | Ilimitado | Ilimitado |

Manejo de 429

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(parseInt(retryAfter || '60') * 1000);
  return retry();
}

---

5. Modo Contingencia

Detección

QuickDTE retorna status 202 Accepted cuando entra en contingencia:

if (response.status === 202) {
  // DTE encolado para transmisión posterior
  const { queueId } = await response.json();
  saveForLaterVerification(queueId);
}

Verificación Posterior

const status = await fetch(
  `https://api.quickdte.com/v1/dte/status/${queueId}`
);

Checklist de Integración

• [ ] Idempotency keys implementadas
• [ ] Retry con backoff exponencial
• [ ] Validación de webhooks
• [ ] Manejo de rate limiting
• [ ] Logs detallados de cada request
• [ ] Monitoreo de errores

---

¿Necesitas ayuda con tu integración? Contacta a nuestro equipo técnico.