Qué construir en tu ERP, POS o SaaS

Para que tus clientes facturen electrónicamente desde tu producto necesitas cuatro piezas. Esta guía describe cada una; los detalles de cada llamada están en el resto de la sección Partners.

Pieza	Para qué
1. Datos	Relacionar cada cliente con su Cuenta fiscal y cada venta con su e-CF.
2. Asistente de activación	Llevar a cada cliente desde sus datos fiscales hasta producción.
3. Emisión	Convertir cada venta en un e-CF sin frenar la caja.
4. Procesos de backend	Recibir eventos, conciliar estados y renovar certificados y claves.

Regla de oro

Tu cliente nunca ve ZarelaFact: todo ocurre dentro de tu producto. La clave X-PARTNER-KEY vive solo en tu backend; el navegador solo recibe tokens temporales para subir el certificado.

1. Datos que guardas

Dónde	Qué guardar	Por qué
Por cliente	externalTenantId (tu ID), fiscalAccountId, RNC	Todas las llamadas usan el fiscalAccountId; los webhooks traen ambos IDs.
Por cliente	caseId, officialSetRef y la Idempotency-Key de cada run	Retomar la certificación sin crear duplicados.
Por cliente	Estado de certificación y de producción	Mostrar el avance y bloquear la emisión hasta que eCF esté active.
Por cliente y tipo de e-CF	Rangos de eNCF autorizados por la DGII, su FechaVencimientoSecuencia y el siguiente número	Tu producto asigna los eNCF; ZarelaFact no los reserva.
Por venta	eNCF, el JSON enviado tal cual, documentId, correlationId, status, trackId	Reintentar sin duplicar y conciliar el estado.
Por evento	Zarela-Event-Id con restricción única	Aplicar cada webhook una sola vez.
Secret manager	X-PARTNER-KEY y el secreto de firma del webhook	Nunca en el código ni en el navegador.

2. Asistente "Activar facturación electrónica"

Ofrece a cada cliente un asistente con estos pasos. Puede abandonarlo y retomarlo: guarda en qué paso va.

Atajo: incrusta la pantalla de pasos de ZarelaFact

Después del paso 1 (datos fiscales), puedes mostrar en un iframe la misma pantalla de certificación del dashboard, en lugar de construir los pasos 2 en adelante: tu backend pide un enlace con POST /fiscal-accounts/{id}/certification-sessions. Ver Incrustar los pasos en tu ERP.

Paso	Qué ve tu cliente	Qué hace tu backend
1. Datos fiscales	Formulario con RNC, razón social, nombre comercial, correo, teléfono, dirección, provincia y municipio. Si el RNC no aparece o no está ACTIVO en el padrón de la DGII, el mensaje de error.	PUT /fiscal-accounts/by-external-id/{tuId} (422 RNC_NOT_IN_DGII_REGISTRY / RNC_NOT_ACTIVE_IN_DGII)
2. Certificado digital	Selector del .p12/.pfx y su contraseña; después, el vencimiento del certificado.	POST .../certificate-upload-sessions y entrega uploadUrl + uploadToken a la UI. Luego GET .../certificate.
3. Postulación DGII	Los datos a copiar en el portal DGII con botón "Copiar", el enlace al portal y un botón para subir el XML que genera la DGII y descargarlo firmado.	GET .../dgii-registration y POST .../certification-xml-signatures
4. Pruebas	Un botón para subir el set de pruebas que la DGII le entregó (Excel) y luego el avance de las pruebas de datos (paso 2 de la DGII). Cuando la DGII las acepta, un botón por cada Factura de Consumo menor a RD$250,000 que baja su XML íntegro (e-CF) suelto, para subirlo en Facturas de consumo < 250Mil del portal de la DGII (su resumen RFCE ya lo envió ZarelaFact). Después, el Excel de aprobaciones comerciales que el contribuyente descarga en CerteCF, Enviar aprobaciones comerciales (paso 3) y el estado de cada una. Por último, Enviar la simulación (paso 4), su avance y otra vez un botón por factura de consumo de la simulación.	POST .../certification-test-sets con el archivo, POST .../certification-cases con el testSetRef, POST .../attestations (dgii_postulation_submitted) y POST .../runs. Al pasar el run, un botón por cada entrada de downloads.consumerInvoiceFiles (GET a su url). Luego, POST .../commercial-approvals con el Excel (workbookBase64) y su avance con GET. Con nextAction: run_simulation_tests, otro POST .../runs envía la simulación.
5. Representaciones impresas	Un botón Descargar PDFs con la representación impresa de cada comprobante de la simulación, para subirlos a la DGII, y "Ya los subí".	GET a downloads.printedPdfs del caso (ZIP en base64; si exceedsDgiiLimit, avisa que pasa de 10 MB) y POST .../attestations (printed_representations_uploaded).
6. URLs de producción	Las URLs de eCF con botón "Copiar" y "Ya las registré".	GET .../dgii-registration y POST .../attestations (production_urls_submitted).
7. Declaración jurada	El firmador del paso 3 para la declaración jurada y "Ya la presenté".	POST .../certification-xml-signatures (sworn_declaration) y POST .../attestations (sworn_declaration_submitted).
8. Roles en la OFV	"Ya los configuré", cuando la DGII lo habilite.	POST .../attestations (ofv_roles_configured).
9. Activación	"Facturación electrónica activa" en cuanto se registra la última tarea.	Nada: al registrar la quinta atestación el caso pasa a approved y producción se activa sola; espera production.state_changed con active.

• En el paso 3, si el cliente marca "Ya envié la postulación" antes de que exista el caso, guarda la confirmación y regístrala como atestación al crear el caso.
• Para mostrar el avance usa el checklist del caso; cada atestación tiene su campo (ver Atestaciones). nextAction dice qué paso sigue (upload_printed_representations, submit_production_urls, submit_sworn_declaration, configure_ofv_roles).
• Muestra las descargas de los pasos 4 y 5 solo cuando el caso trae downloads (la DGII aceptó el run); downloads.consumerSummaries es null si el set no tiene resúmenes. Ver Mostrar los pasos siguientes en tu ERP.
• En el paso 4, si el set no se puede procesar, muestra el error.message y los details (por ejemplo, columnas que no se reconocieron) y deja que el cliente suba el archivo de nuevo.

¿Todavía no tienes el asistente?

Mientras lo construyes, tu equipo puede hacer estos mismos pasos por cada cliente desde el dashboard de ZarelaFact: Certificación desde el dashboard. Lo que hagas ahí se refleja en la API y en tus webhooks.

3. Emisión dentro de tu flujo de ventas

1. Antes de vender: comprueba que la Cuenta fiscal tenga producción active (guárdalo desde el webhook). Si no, no ofrezcas e-CF para ese cliente.
2. Asigna el eNCF del rango de ese cliente y tipo, y guárdalo con la venta antes de llamar a la API.
3. Arma el JSON DGII/XSD con el emisor completo (RNC del cliente) y envíalo dentro de document a POST .../production/documents. Prueba en el sandbox del cliente (POST .../testecf/documents, el ambiente de pruebas de la DGII, fuera de tu plan) o con ?validate=true si solo quieres validar. La emisión corre la misma validación: si responde 422, el documento no quedó registrado y puedes corregirlo y reenviarlo con el mismo eNCF.
4. No frenes la caja: la respuesta 202 significa "encolado". Consulta el documento hasta que traiga printing (unos segundos: aparece cuando la DGII responde con el TrackID o, en una factura de consumo menor a RD$250,000, con la respuesta del resumen RFCE) e imprime la factura con su código de seguridad y su QR; ver Representación impresa. Actualiza el estado ante la DGII cuando llegue document.state_changed.
5. Ante un timeout, reenvía el mismo JSON con el mismo eNCF. Nunca asignes otro eNCF para "destrabar" una venta.
6. Si la DGII lo rechaza, marca la venta, muestra al usuario los dgiiMessages y corrige con el procedimiento fiscal que corresponda (por ejemplo, un nuevo comprobante). No reenvíes el mismo eNCF.

4. Procesos de backend

Proceso	Cuándo corre	Qué hace
Receptor de webhooks	Siempre	Verifica la firma, deduplica por Zarela-Event-Id, ubica al cliente por externalTenantId y fiscalAccountId y actualiza tus estados. Ver Webhooks.
Cola de emisión	Con cada venta	Envía, reintenta con backoff y respeta Retry-After ante 429.
Conciliación	Cada 5–15 minutos	Consulta status/batch (hasta 100 por llamada) para los documentos que aún no tienen estado final.
Renovación del certificado	Al recibir certificate.expiring	Pide al cliente su certificado nuevo con certificate-rotation-requests.
Documentos recibidos	Al recibir document.received	Registra la compra en tu ERP y, si el cliente la acepta o rechaza, envía la aprobación comercial. Ver Activación y emisión.
Rotación de claves	Antes de expiresAt	Crea la clave nueva en el portal, despliégala y luego revoca la anterior.

Otras operaciones por cliente

• PDF y XML: GET .../production/documents/{documentId}/pdf y /xml para enviárselos a tu cliente o archivarlos.
• Anulación (ANECF): anula los eNCF que el cliente no usará.
• Recibidos y aprobación comercial (ACECF): lista lo que sus proveedores le enviaron y responde por él.

Todo se explica en Activación y emisión.

Antes de abrirlo a tus clientes

• La clave Partner y el secreto del webhook están en tu secret manager, no en el navegador ni en el POS.
• Probaste con dos Cuentas fiscales distintas: cada certificado queda en su cuenta y no puedes consultar la ajena.
• Tu receptor rechaza firmas inválidas, acepta dos firmas durante una rotación y no aplica dos veces el mismo evento.
• Un timeout en la emisión se reintenta con el mismo eNCF y no crea otra venta.
• La emisión queda bloqueada mientras la producción del cliente no esté active.