Mejores prácticas

Cosas que aprendimos certificando clientes reales — para que no te tropieces con lo mismo.

Idempotencia: no reintentes con datos nuevos

Si un POST /emitir falla por timeout o error de red y no estás seguro de si llegó a procesarse, no lo reintentes con un encf nuevo — usa GET /local/{encf} o GET /trackids con el eNCF que ibas a usar para confirmar si ya existe antes de reintentar. Enviar el mismo eNCF dos veces con datos distintos es lo que más rechazos genera.

Guarda el trackId, no solo el estado

La respuesta de /emitir te da un estado inmediato, pero DGII puede tardar en confirmar. Guarda el trackId en tu propia base — es lo único que te permite volver a consultar /resultado/{trackId} más tarde si el estado inicial fue "en proceso".

El monto decide si es e-CF completo o RFCE — no lo fuerces

Para tipo 32, si el monto es menor a RD$250,000, nuestra API lo envía como resumen (RFCE) automáticamente, tal como exige DGII. No intentes forzar el envío completo enviando un monto artificialmente alto — DGII valida el monto real contra el documento.

Formato de fecha: YYYY-MM-DD, siempre

Aunque DGII internamente usa DD-MM-AAAA en el XML, nuestra API acepta fecha_emision en formato ISO (YYYY-MM-DD) y hace la conversión por ti — no envíes fechas en otro formato, y no intentes replicar la conversión tú mismo.

Notas de crédito/débito: espera a que el original esté firme

Si necesitas emitir una nota de crédito o débito (tipo 33/34) inmediatamente después del e-CF que referencia, dale unos segundos — DGII a veces marca la secuencia del documento original como "no utilizada todavía" si la nota llega demasiado rápido. Si te rechaza con ese motivo específico, reintenta en 30 segundos, no cambies el encf_referenciado.

No repitas la lógica de firma tú mismo

No necesitas (ni deberías) firmar el XML por tu cuenta — nosotros lo hacemos con tu certificado ya cargado. Si tu integración genera XML propio por alguna razón, usa la herramienta Firmar XML del panel en vez de reimplementar XAdES/XMLDSig — es una fuente de errores sutiles muy difíciles de depurar (firma inválida que DGII rechaza sin explicar bien por qué).

Verifica el estado de los servicios de DGII antes de escribirnos

Si varios envíos seguidos fallan con error 502, consulta primero GET /servicios — si DGII mismo está caído (pasa, especialmente en horas pico), no es un problema de tu integración ni de la nuestra.

Ambiente de pruebas antes que producción

Nunca pruebes un flujo nuevo por primera vez contra el ambiente de producción de tu empresa ya certificada. Usa siempre el ambiente testecf para cambios de integración — el certificado y las secuencias son completamente independientes de producción.