Mejores Practicas

Recomendaciones para una integracion robusta y confiable con Frande ECF.

1. Validar antes de enviar

Usa el parametro ?validate=true para verificar la estructura de tus documentos antes de enviarlos a la DGII. Esto te permite detectar errores sin consumir secuencias de eNCF.

curl -X POST https://ecf.frandeone.com/TesteCF/documentos-ecf?validate=true \
  -H "Authorization: Bearer ..." \
  -H "X-API-KEY: ecf_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ ... tu documento ... }'

2. Implementar reintentos con backoff exponencial

Los fallos temporales (timeout, 503, errores de red) son normales. Implementa reintentos con backoff exponencial:

async function sendWithRetry(document, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, { method: 'POST', ... });
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
      if (response.ok) return await response.json();
      if (response.status >= 400 && response.status < 500) {
        throw new Error('Error de cliente, no reintentar');
      }
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await sleep(delay);
    }
  }
}

3. Almacenar copia local

Guarda una copia de cada documento enviado y su respuesta en tu base de datos:

• JSON enviado: Para referencia y reenvio si es necesario
• eNCF asignado: El comprobante fiscal electronico
• trackId: Para consultas posteriores
• trackId DGII: Para rastreo en la DGII
• Codigo de seguridad: Para la representacion impresa
• XML firmado: Descargalo y almacenalo localmente

4. Consultar estados periodicamente

Los documentos pasan por varios estados antes de ser ACEPTADOS o RECHAZADOS. Implementa un proceso que consulte periodicamente:

1. Enviar documento → Estado: EN_COLA
2. Esperar 5 segundos → Consultar estado
3. Estado: RECIBIDO → Esperar 30 segundos
4. Consultar de nuevo → Estado: ACEPTADO ✓

Si RECHAZADO:
  → Leer mensaje de error
  → Corregir documento
  → Reenviar con nuevo eNCF

Tambien puedes configurar un webhook en Configuracion para recibir notificaciones automaticas cuando un documento cambie de estado.

5. Gestionar QR y codigos de seguridad

• El codigo de seguridad es unico por documento y se genera al firmar
• La URL del QR apunta a la pagina de verificacion de la DGII
• Ambos deben aparecer en la representacion impresa del documento
• Genera el QR como imagen usando cualquier libreria de QR codes con la URL proporcionada

6. Seguridad

• No expongas tu API Secret en codigo del lado del cliente (frontend/mobile)
• Rota tokens: Usa refresh tokens en lugar de credenciales directas
• HTTPS obligatorio: Todas las peticiones deben ser sobre HTTPS
• Guarda credenciales en variables de entorno, nunca en codigo fuente
• Usa el rate limiter: Si recibes 429, respeta el header Retry-After

7. Idempotencia

Si envias un documento con un eNCF que ya fue procesado, la API retorna 409 Conflict. Esto previene duplicados accidentales. Guarda el eNCF asignado localmente para evitar reenvios innecesarios.