Preguntas frecuentes
Respuestas cortas, agrupadas por tema. Cada una enlaza a la página con el detalle.
Empezar
¿Cómo empiezo?
Sigue Cómo empezar: crea tu cuenta, sube tu certificado .p12, crea tu API key, integra tu software y certifícate ante la DGII.
¿Qué necesito sí o sí?
Un certificado digital .p12 de la empresa que emite y un sistema capaz de hacer llamadas HTTP con JSON. Ver Sube tu certificado.
¿TesteCF necesita certificado? ¿Tienen uno de prueba?
Sí, TesteCF también necesita el .p12 real. No hay certificados de prueba y uno autogenerado no sirve.
¿Por qué TesteCF responde «ya utilizado» con un e-NCF que nunca usé?
TesteCF lo comparten todos los integradores de la DGII, y las secuencias bajas, como E310000000001, ya las usaron otros. Prueba con secuencias altas, por ejemplo E310009000001.
¿El certificado está incluido? ¿Cuánto dura?
No está incluido: lo compra la empresa a una entidad de certificación, que fija el precio y la vigencia. Sirve para los tres ambientes y te avisamos por correo desde 30 días antes de que venza. Ver Preguntas sobre el certificado.
¿Qué ruta de integración me corresponde?
Si emites solo para tu empresa, usa la cuenta directa. Si tu plataforma atiende a varios clientes, usa la API Partner.
Varios clientes (Partners)
¿Puedo manejar todos mis clientes con una sola integración?
Sí. Con una sola X-PARTNER-KEY creas la Cuenta fiscal de cada cliente, lo certificas y emites por él. Cada cliente queda aislado de los demás. Ver Varios clientes (Partners).
¿Mis clientes necesitan una cuenta en ZarelaFact?
No. Usan solo tu producto: no entran al portal de ZarelaFact ni manejan API keys.
¿Tengo que guardar credenciales por cada cliente?
No. Guardas tu clave Partner y, por cada cliente, su fiscalAccountId. No hay usuario, contraseña ni API key por cliente.
¿Cómo sube mi cliente su certificado?
Desde una pantalla de tu producto: tu backend pide una sesión de carga y el navegador del cliente envía el .p12 directo a ZarelaFact. Tú nunca recibes el archivo ni la contraseña. Si el cliente te lo entrega y te autoriza, también puedes cargarlo tú desde el dashboard. Ver Carga del certificado.
¿Puedo ver los documentos de un cliente?
Sí. Entras al mismo dashboard que una cuenta directa: en Todos los clientes ves los documentos de todos tus clientes y, al elegir uno, su resumen, documentos, logs de la DGII, certificación y certificados. Desde ahí también lo certificas.
¿Puedo certificar a mis clientes solo con la API?
Sí: vinculas la cuenta, el cliente sube su certificado, le muestras los datos de la postulación, firmas sus XML, ejecutas las pruebas y registras sus pasos en la DGII. El set de pruebas que la DGII entrega a cada cliente lo sube tu ERP por API, y al completarse la certificación la producción se activa sola. Si prefieres no programarlo, cada paso también se hace desde el dashboard. Ver Certificación de cada cliente.
¿Qué pasa si el RNC de mi cliente ya está con otro proveedor?
Recibes 409 RNC_NOT_AVAILABLE. Si de verdad es tu cliente, pídele que escriba a [email protected] para autorizar el cambio. Ver Titularidad del RNC.
Planes y pagos
¿Cuánto cuesta?
Registrarte, probar en TesteCF y certificarte en CerteCF es gratis. La cuenta directa incluye además 50 e-CF al mes gratis en producción; para más volumen hay planes de precio fijo al mes que pagas desde Empresa → Planes. Ver Planes y pagos.
¿Cómo pago?
Pagas con tarjeta desde Empresa → Planes en el portal (lo hace el propietario o un administrador). Se cobra el precio completo el día que pagas y se renueva ese mismo día cada mes; el cupo del plan se cuenta en ese periodo. Subir de plan aplica en el acto y cobra hoy la diferencia; bajar de plan se aplica al renovar. El plan A medida se solicita y ZarelaFact acuerda contigo las condiciones.
¿Dónde cambio la tarjeta, el plan o descargo mis facturas?
En Empresa → Plan y facturación → Gestionar plan, dentro del portal. Ahí cambias de plan, cancelas o reactivas, cambias la tarjeta y descargas tus facturas. Subir de plan, cancelar y reactivar se confirman en una página segura de Stripe y vuelves al portal con el resultado. Ver Gestionar plan.
¿Qué pasa si me paso del límite del mes?
Con un plan pagado sigues emitiendo con un margen sin costo: 30 % el primer periodo que te pasas, 20 % el segundo seguido, 10 % el tercero y 0 % después (vuelve al 30 % tras un periodo dentro del plan o al subir de plan). Te avisamos por correo, en el portal y en la respuesta de la API. Al agotar el margen, la emisión responde 429 PLAN_LIMIT_EXCEEDED hasta que subas de plan o se renueve tu periodo. Sin plan pagado, al pasar los 50 e-CF gratis responde 402 PAYMENT_REQUIRED hasta que pagues uno. No cobramos excedentes. Ver el margen de tolerancia.
¿Qué pasa si falla el cobro de mi plan?
Mantienes el plan durante 7 días de gracia y te avisamos por correo, también dos días antes de que termine. Cambia la tarjeta en Empresa → Gestionar plan y cobramos el pago pendiente en el acto. Si no se completa el pago, una cuenta directa vuelve al plan Gratis (50 e-CF al mes) y un Partner queda con la producción bloqueada (402). Las pruebas y la certificación nunca se bloquean.
¿Las consultas o las validaciones consumen mi plan?
No. Solo consumen los e-CF de producción que la DGII aceptó (accepted o accepted_conditional). Los que van en camino reservan un lugar mientras se resuelven y lo liberan si terminan rechazados o cancelados. Las consultas, las validaciones (validate=true) y las pruebas en TesteCF y CerteCF no cuentan.
Tengo varios clientes. ¿Cómo se cobra?
Como Partner, el cobro es para tu empresa y se calcula con el volumen sumado de todos tus clientes, sin plan Gratis. Ver Si tienes varios clientes.
Integración
¿Envío XML o JSON?
JSON, con la misma estructura y los mismos nombres de campo que el XML de la DGII. ZarelaFact lo convierte, lo firma y lo envía. Ver Formato JSON de e-CF.
¿Cómo me autentico? ¿Necesito un token?
No hay login ni token: envías tu API key en el header X-API-KEY. Ver Autenticación API.
¿Qué lenguaje necesito?
Cualquiera que haga solicitudes HTTP con JSON. Los ejemplos vienen en cURL, JavaScript, C# y PHP.
¿Puedo validar un documento sin emitirlo?
Sí, con ?validate=true. No se envía a la DGII ni registra el eNCF. Ver Validar sin emitir.
¿Qué significa dgiiPrediction?
Es el veredicto orientativo de ?validate=true. Dice si la DGII aceptaría tu documento, lo aceptaría como Aceptado condicional o lo rechazaría, y da el motivo de cada aviso o error. No cambia ok ni el código HTTP, y la DGII tiene la última palabra. Ver Validar sin emitir.
¿Puedo probar sin certificado?
Sí, con el Sandbox. No necesitas el .p12: ZarelaFact simula el veredicto que daría la DGII para tu JSON y te dice el motivo de cada aviso o error. No llega a la DGII ni tiene validez fiscal. TesteCF sí necesita el certificado, porque ahí la DGII responde de verdad.
¿Tengo que elegir entre el documento completo y el resumen RFCE?
No. En las facturas de consumo (32), ZarelaFact decide según el MontoTotal (umbral de RD$250,000). Tú siempre envías el documento completo.
¿Debo esperar a la DGII para completar la venta?
No. La API responde 202 al recibir el documento; eso no es la aceptación de la DGII. Imprime en cuanto el documento esté firmado y concilia el estado después.
¿Cómo evito duplicar una factura si la solicitud termina en timeout?
Repite exactamente el mismo JSON con el mismo eNCF: si coincide, recibes el documento original. Si ese eNCF llega con otros datos, la API responde 409 ENCF_PAYLOAD_MISMATCH. La excepción es un e-CF que la DGII rechazó con secuenciaUtilizada: false: con el mismo eNCF se reenvía, corregido o igual. Ver Errores y reintentos y Corregir y reenviar un rechazo.
¿Tienen webhooks?
Sí, y son opcionales: la consulta por lote siempre funciona. En la cuenta directa los creas en el portal (Desarrolladores → Webhooks), en TesteCF para probar y en eCF para producción; los Partners, en el mismo menú o con la API. Ver Webhooks.
¿Ustedes entregan el PDF o yo imprimo la factura?
Las dos cosas. La consulta trae el código de seguridad, la fecha de firma y la URL del QR para que imprimas en tu propio formato, como un ticket de 80 mm. También generamos un PDF tamaño carta que descargas desde el portal, y si lo activas le enviamos a tu comprador un correo con el enlace a ese PDF cuando la DGII acepta la factura. Ver Representación impresa.
¿Cómo sé por qué la DGII rechazó un documento?
La consulta trae dgiiMessages con los mensajes de la DGII. Muéstraselos a quien corrige la factura.
Mis documentos se quedan en signed. ¿Qué pasa?
Mira lastError en la consulta por lote. El caso más común es DGII_CERTIFICATE_NOT_DELEGATED: el titular del certificado no tiene el rol Firmante Autorizado en la Oficina Virtual de la DGII. ZarelaFact pausa los envíos y los reintenta cada 30 minutos; en cuanto delegas el rol, salen solos.
Mi cliente no es receptor electrónico. ¿Es un error?
No. ZarelaFact entrega el e-CF por su cuenta solo a los compradores que son receptores electrónicos en la DGII. Si tu cliente no lo es, entrégale la representación impresa como siempre. Ver Entrega al comprador.
¿Qué son los marcadores de los ejemplos?
Valores como {{RNC}} o {{FECHA_EMISION}} que ZarelaFact reemplaza con los datos de tu cuenta al recibir el documento. Los de tu cliente, como {{RNC_COMPRADOR}}, los reemplazas tú. Ver Marcadores.
Certificación DGII
¿Qué datos de proveedor pongo en la postulación?
Software EXTERNO llamado ZarelaFact, versión 1.0, proveedor ZARELA GROUP SRL (nombre comercial ZARELA GROUP), RNC 133-81616-4. Las URLs son la base del ambiente y la de autenticación va en blanco. Ver el paso 3 de la guía.
¿Qué parte de la certificación hace ZarelaFact?
El asistente firma tu postulación y tu declaración jurada, y envía los documentos de prueba de cada tipo. En la DGII, con el usuario de la Oficina Virtual de la empresa, se crea la postulación, se suben los PDF, se envía la declaración jurada y se asignan los roles. Ver Quién hace qué.
¿Qué roles delego en la Oficina Virtual y a quién?
Al titular del certificado, la persona cuya cédula aparece en él, desde la OFV de la empresa: Firmante (firma los e-CF), Solicitante (postulación y secuencias) y Aprobador Comercial (firma las aprobaciones comerciales). Administrador es opcional. Sin Firmante, la DGII responde «El RNC del certificado no está delegado…». Ver el paso 11.
La DGII dice «La postulación ya existe». ¿Qué hago?
Aceptaste el facturador gratuito de la DGII, que se ofrece en el buzón de la OFV. Cancélalo antes de postularte con ZarelaFact.
Vengo de otro proveedor o del facturador gratuito. ¿Me postulo otra vez?
Sí: cambiar de proveedor requiere una postulación nueva en la DGII. Para cambiar solo tus URLs no hace falta: se editan en OFV → Facturación Electrónica → Mantenimiento Directorio FE.
El paso 9 de la DGII lleva días sin avanzar. ¿Qué hago?
Es un error de la DGII: llama al 809-689-3444 y pide que reinicien ese paso. Ver más casos en Problemas frecuentes con la DGII.
¿Cada cliente se certifica por separado?
Sí. Cada RNC se certifica una vez ante la DGII.
¿Tener la función en ZarelaFact significa que ya estoy autorizado?
No. Cada RNC necesita completar su certificación y la confirmación de la DGII antes de emitir en producción.
Seguridad
¿Cómo se protegen los certificados?
Se guardan cifrados y su contraseña no vuelve a mostrarse después de la carga. Toda la comunicación usa HTTPS y las operaciones sensibles quedan auditadas.
¿Quién puede ver mis facturas?
Tu empresa, los receptores de tus facturas, la DGII cuando corresponde y, si emites a través de un Partner, ese Partner. Cada cuenta está aislada de las demás.
Si el equipo de soporte de ZarelaFact consulta los datos de tu cuenta (por ejemplo para revisar un problema), queda registrado y lo ves en el portal, en Empresa → Accesos de soporte de ZarelaFact: «ZarelaFact (soporte) consultó …» con la fecha y lo que se consultó.
¿Necesito guardar los XML?
No. ZarelaFact guarda los XML firmados y sus representaciones impresas durante 10 años, también cuando a la DGII solo se envió el resumen RFCE.
¿Es obligatoria la facturación electrónica?
La DGII la está haciendo obligatoria de forma gradual para todos los contribuyentes. Conviene empezar cuanto antes.