Ajustes del contribuyente

NovaFE trae un conjunto de ajustes por contribuyente (por cada RNC) que cambian cómo se emite, se envía y se avisa. Todos tienen un valor por defecto razonable: no necesitas tocar ninguno para empezar.

Los puede cambiar quien tenga el rol admin_tenant sobre el contribuyente, incluidos los owner y admin de su organización. Los cambios quedan en un historial con la persona que los hizo.

Dónde se cambian

• Dashboard: en la pantalla de configuración del contribuyente, agrupados por tema. Cada ajuste muestra su valor efectivo y de dónde viene.
• API: con una API key de rol admin_tenant.

GET    /api/v1/settings               Lista los ajustes con su valor efectivo
PUT    /api/v1/settings/{key}         Establece el valor
DELETE /api/v1/settings/{key}         Vuelve al valor predeterminado
GET    /api/v1/settings/{key}/history Historial de cambios

PUT /api/v1/settings/submission.wait_for_result
{ "value": "false" }

El valor siempre viaja como texto: true o false para los booleanos, números sin separador, duraciones como 30s, 5m o 2h, y listas separadas por comas (31,32,33). Un valor inválido responde 400 con el motivo, y una clave que no existe responde 404.

Cómo se decide el valor efectivo

Un ajuste puede venir de cuatro lugares. Rige el más cercano a ti, salvo que tu organización lo bloquee:

tu contribuyente  →  tu organización  →  la plataforma  →  el valor por defecto

En GET /settings, el campo resolvedFrom te dice de cuál viene el valor efectivo (tenant, organization, platform o default).

Tu organización solo puede intervenir en los ajustes marcados como heredables (inheritable: true). Para ellos hay tres comportamientos:

Comportamiento	Qué significa
Se hereda	Si tu contribuyente no fija un valor, rige el de la organización. Si lo fija, rige el tuyo.
Bloqueado (locked: true)	La organización fijó el valor y no puedes cambiarlo. Intentarlo responde 409 con el código Setting.LockedByOrganization.
Combinado con el más restrictivo	Rige el valor más estricto entre el tuyo y el de la organización. Tú puedes endurecer un límite, pero no aflojar el de tu organización.

Por ejemplo, con emission.monthly_limit si tu organización fija 5000 y tú fijas 8000, rige 5000. Si tú fijas 3000, rige 3000.

Envío a la DGII

Clave	Qué hace	Por defecto	Organización
submission.wait_for_result	Si POST /ecf espera el resultado de la DGII antes de responder. Apagado, responde de inmediato con el comprobante firmado y el resultado llega por webhook. Solo se puede apagar, nunca encender lo que otro nivel apagó.	true	Hereda, el más restrictivo manda
submission.auto_retry_rejections	Si NovaFE reenvía solo un comprobante rechazado por una falla pasajera de la DGII cuando el e-NCF quedó libre. Apagado, queda rejected de inmediato.	true	Hereda y puede bloquear
submission.rejection_retry_max	Máximo de reenvíos automáticos tras ese tipo de rechazo. 0 usa el tope de la plataforma, y nunca puede superarlo.	0	Hereda y puede bloquear, el menor manda

Esperar o no esperar el resultado

Con la espera activada, POST /ecf aguarda hasta unos 8 segundos el resultado de la DGII y, si llega, lo incluye en la respuesta. Con la espera desactivada, siempre responde status: "signed" con dgii: null y te enteras del resultado por webhook o consultando el comprobante. Si tu sistema emite muchos comprobantes en paralelo, el modo sin espera evita mantener peticiones abiertas. NovaFE también puede desactivar la espera para toda la plataforma ante un incidente de la DGII: en ese caso rige aunque tu contribuyente la tenga activada. Más detalle en Endpoints y semántica.

Control de emisión

Clave	Qué hace	Por defecto	Organización
emission.paused	Pausa la emisión de comprobantes nuevos: POST /ecf responde 409. Lo ya firmado se sigue enviando y las consultas funcionan.	false	Hereda y bloquea, basta con que uno la active
emission.paused_reason	Texto que recibe quien intente emitir mientras está pausada.	vacío	Hereda
emission.paused_until	Fecha y hora (por ejemplo 2026-10-05T14:00:00Z) en que la pausa termina sola. Vacío: dura hasta que la quites.	vacío	Hereda
emission.allowed_types	Tipos de comprobante que se aceptan en POST /ecf. Cualquier otro responde 403.	los diez	Hereda y bloquea, rige la intersección
emission.monthly_limit	Tope de comprobantes de Producción por mes. Al llegar se rechazan los nuevos hasta el mes siguiente. 0 es sin tope.	0	Hereda y bloquea, rige el menor distinto de 0
emission.max_per_minute	Máximo de emisiones por minuto del contribuyente. El exceso recibe 429 con Retry-After. 0 es sin tope.	0	Hereda y bloquea, rige el menor distinto de 0
ecf.duplicate_detection_mode	Detección de duplicados por huella (comprador con RNC o cédula, tipo, monto y fecha): off, observar (avisa por webhook) o bloquear (responde 409).	off	Hereda y puede bloquear
ecf.duplicate_detection_window	Ventana en que dos comprobantes iguales se consideran duplicados, entre 30 segundos y 1 hora.	5m	Hereda y puede bloquear

Numeración y secuencias

Clave	Qué hace	Por defecto	Organización
sequences.mode	managed: NovaFE asigna el e-NCF desde tus rangos registrados. external: tu sistema asigna el e-NCF y lo envía en cada emisión, junto con su fecha de vencimiento.	managed	No
sequences.low_stock_fraction	Fracción del rango restante a partir de la cual una secuencia se considera con stock bajo, entre 0.01 y 1.	0.20	Hereda

Al volver de external a managed, registra un rango nuevo que empiece después del último número que usaste.

Seguridad

Clave	Qué hace	Por defecto	Organización
security.api_key_max_age_days	Vigencia máxima, en días, de las API keys nuevas (hasta 730). Con un tope, cada key debe nacer con fecha de vencimiento. 0 es sin tope. No afecta a las keys que ya existen.	0	Hereda y bloquea, rige el menor distinto de 0

Avisos y alertas

Clave	Qué hace	Por defecto	Organización
notifications.certificate_expiry_thresholds_days	Días antes del vencimiento del certificado en que se avisa, separados por coma.	90,30,15,7	Hereda
notifications.sequence_expiry_thresholds_days	Días antes del vencimiento de una secuencia en que se avisa.	30,7	Hereda
alerts.rejection_rate_threshold_pct	Se avisa cuando el porcentaje de rechazos de la última hora llega a este valor. Necesita al menos 5 comprobantes en esa hora. 0 es sin alerta.	0	Hereda
alerts.no_emission_hours	Se avisa cuando pasan estas horas laborales sin emitir. No avisa fuera del horario laboral ni con la emisión pausada. 0 es sin alerta.	0	Hereda
alerts.business_hours	Horario laboral que usa la alerta anterior, en hora de Santo Domingo. Formato L-V 08:00-18:00.	L-V 08:00-18:00	Hereda

Recepción B2B

Estos ajustes son solo del contribuyente: cada uno decide cómo recibe, así que la organización no los fija. Más detalle en Recepción B2B.

Clave	Qué hace	Por defecto
inbound.require_bearer_auth	Exige que los emisores que te envían e-CF se autentiquen con el esquema opcional de semilla y certificado. Un emisor que no lo implemente no podrá enviarte.	false
inbound.auto_commercial_approval	manual: una persona decide cada e-CF recibido. auto_trusted: se aceptan solos los de tus emisores de confianza, hasta el monto máximo. Nunca se rechaza nada de forma automática.	manual
inbound.trusted_issuers	RNC (9 dígitos) o cédula (11 dígitos) de los emisores de confianza, separados por coma y sin guiones.	vacío
inbound.auto_approve_max_amount	Monto máximo en RD$ de un e-CF para aprobarse solo. 0: no se aprueba nada automáticamente.	0

Representación impresa

Clave	Qué hace	Por defecto	Organización
representation.default_layout	Formato por defecto cuando la descarga no indica ?layout: letter (Carta) o pos (80 mm).	letter	Hereda y puede bloquear
representation.show_logo	Si la representación impresa lleva tu logotipo, cuando lo tienes cargado.	true	Hereda y puede bloquear
representation.footer_text	Texto adicional al pie, hasta 240 caracteres. Se suma al pie legal, no lo reemplaza.	vacío	Hereda y puede bloquear
representation.accent_color	Color de acento del rótulo y del monto total, como #1D4ED8. Un color muy claro para leerse sobre blanco se ignora al imprimir.	vacío	Hereda y puede bloquear

Lo que no está en esta lista

Algunas reglas de la plataforma no son ajustes tuyos ni de tu organización, por ejemplo los tiempos de reintento hacia la DGII o la entrega de webhooks. Las administra NovaFE. Si necesitas cambiar alguna, escríbenos.