Manejo de Errores y Tolerancias Fiscales

Etribux cuenta con un motor de validación previa que intercepta errores antes de firmar o transmitir documentos a la DGII. Esto evita el desperdicio de secuencias de e-NCF y previene rechazos irreversibles en producción.

---

Códigos de Error de la API de Etribux

Cuando una solicitud no cumple con los estándares técnicos o fiscales, la API responde con códigos HTTP estándar y un objeto JSON de error detallado:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "el monto gravado declarado supera la tolerancia permitida respecto al cálculo",
    "details": [
      {
        "field": "totals.taxed_amount",
        "issue": "tolerancia excedida: declarado 1000.00, calculado 1200.00 (tolerancia permitida ±0.50)"
      }
    ]
  }
}

Código HTTP	Código API (code)	Causa Típica	Solución
400	BAD_REQUEST	JSON mal formado o sintaxis inválida	Validar que el cuerpo de la petición sea un JSON bien estructurado.
401	UNAUTHORIZED	Token API ausente, inválido o expirado	Verificar la cabecera Authorization: Bearer <API_KEY>.
403	FORBIDDEN	Intento de emitir en un ambiente no asignado	Verificar si la API Key corresponde a testecf, certecf o ecf.
409	IDEMPOTENCY_CONFLICT	Reenvío de external_id con payload diferente	Utilizar un nuevo external_id o mantener el mismo payload para reintentos seguros.
422	VALIDATION_FAILED	Error en reglas de negocio o cálculos fiscales	Revisar el detalle del mensaje tributario y corregir los importes.
422	SEQUENCE_EXHAUSTED	e-NCF ya utilizado previamente	Asignar un nuevo número de secuencia correlativa no emitido.

---

Catálogo de Rechazos Comunes de la DGII

La siguiente tabla resume los códigos de error más frecuentes emitidos por los servidores de la DGII y cómo Etribux los previene:

Código DGII	Mensaje Oficial DGII	Diagnóstico	Prevención en Etribux
140	Monto total no coincide con la suma de las líneas	Discrepancia en la suma de montos gravados, exentos e ITBIS.	Etribux exige la ecuación de cierre exacta de tres términos: Total = Round(Gravado + Exento + ITBIS).
141	Monto de ITBIS no coincide con el cálculo del porcentaje	El ITBIS de alguna línea o del total discrepa de la tasa (18% o 16%).	Etribux valida cada subtotal contra la suma de ítems con la Tolerancia Global DGII §12.
142	RNC del comprador no válido	El RNC no existe en el padrón o está suspendido.	En pre-validación (validate=true), Etribux verifica la estructura y existencia del RNC.
144	e-NCF fuera de rango o vencido	La secuencia no pertenece a los rangos autorizados a la empresa.	Tu ERP debe mantener sincronizados los rangos aprobados por la DGII.
150	Documento modificado inexistente	En notas de crédito (34) o débito (33), el modified_ncf no existe.	Verificar que el comprobante referenciado haya sido previamente aceptado por la DGII.
151	Nota de crédito fuera del plazo de 30 días	Se intentó generar crédito fiscal de ITBIS tras más de 30 días del e-CF original.	Etribux advierte que la nota de crédito no generará crédito fiscal de ITBIS.

---

Regla de Tolerancia Global (Informe Técnico DGII §12)

En sistemas con facturación de múltiples líneas y redondeos individuales por ítem, pueden surgir discrepancias de centavos entre la suma de redondeos de líneas y el cálculo global sobre el total.

La DGII establece una tolerancia máxima permitida basada en la cantidad de líneas (N) del comprobante:

Tolerancia = min(1.00, 0.01 * N)

• Para comprobantes de 1 a 99 líneas: La tolerancia es de hasta $0.01 \times N centavos (ej. 10 líneas permiten hasta ±0.10 DOP de variación).
• Para comprobantes de 100 o más líneas: La tolerancia máxima se fija en 1.00 DOP.

Ecuación de Cierre Fiscal Obligatoria

Independientemente de la tolerancia en líneas individuales, el documento final debe cumplir estrictamente con la ley de cierre de tres términos:

MontoTotal = Round(MontoGravadoTotal + MontoExento + TotalITBIS)

(Las retenciones de ITBIS o ISR no afectan el MontoTotal comercial del comprobante).