Varios clientes (Partners)
Esta sección es para empresas de software (ERP, POS, CRM o SaaS) que emiten e-CF para varios negocios.
- Cada cliente tiene su propia Cuenta fiscal, con su RNC, su certificado, su certificación y sus documentos. Ningún cliente ve ni firma documentos de otro.
- Tu backend usa una sola clave (
X-PARTNER-KEY) para todos tus clientes. No guardas usuarios, contraseñas ni API keys por cliente. - Tu cliente nunca sale de tu producto: sube su certificado desde tu pantalla, sigue su certificación ahí y emite desde tu sistema.
- Entras al mismo dashboard que una cuenta directa. En Todos los clientes ves el resumen y los documentos de todos tus clientes; al elegir uno ves su detalle, lo certificas y, con su autorización, cargas su certificado. Tus claves, webhooks y consumo están en la sección Partner del menú.
Las cuentas
| Concepto | Qué es | Cómo lo identificas |
|---|---|---|
| Partner | Tu empresa de software. Una sola cuenta. | Tu clave X-PARTNER-KEY. |
| Cliente (tenant) | Un cliente dentro de tu plataforma. | Tu propio externalTenantId, estable (normalmente su UUID en tu sistema). |
| Cuenta fiscal | El RNC de ese cliente, con su certificado, su certificación y su emisión, aislados de los demás. | El fiscalAccountId que devuelve ZarelaFact. |
Puedes tener tantas Cuentas fiscales como clientes. Conocer un UUID o un RNC nunca da acceso a la cuenta de otro Partner.
Quién hace qué
| Etapa | Tu cliente, en tu producto | Tu backend, con la API | ZarelaFact |
|---|---|---|---|
| Alta | Completa sus datos fiscales. | Crea su Cuenta fiscal. | Reserva el RNC para ti. |
| Certificado | Sube su .p12 y la contraseña (o te autoriza a cargarlo tú desde el dashboard). | Pide una sesión de carga temporal. | Recibe el archivo directo del navegador y lo valida. |
| Certificación | Hace los pasos en el portal de la DGII y te entrega el set de pruebas. | Le muestra los datos, firma sus XML, sube el set, ejecuta las pruebas y registra sus pasos. | Envía las pruebas a CerteCF y registra la aprobación con la evidencia. |
| Producción | Empieza a facturar. | Espera el webhook production.state_changed. | La activa sola al completarse la certificación. |
| Emisión | Vende como siempre. | Envía cada e-CF y concilia su estado. | Firma, envía a la DGII y guarda 10 años. |
Qué construir en tu producto, pantalla por pantalla: Qué construir en tu ERP, POS o SaaS. El recorrido con cada llamada: Guía paso a paso. Si programas con un asistente de IA, copia el prompt para Partners.
Alta del Partner
- En el registro eliges ERP / POS Partner e indicas los datos y el RNC de tu empresa, no los de un cliente.
- Eliges el plan mensual según el volumen estimado de todos tus clientes (ver Planes y pagos). Es una solicitud; no genera cobros: lo pagas en tu portal cuando vayas a producción.
- Confirma tu correo con el enlace que te enviamos: hasta entonces no puedes entrar. Después entras de inmediato al dashboard, en Todos los clientes.
El dashboard
Es el mismo dashboard de una cuenta directa. Arriba, el selector Cliente cambia entre Todos los clientes y cada una de tus Cuentas fiscales.
| En el dashboard puedes | Quién |
|---|---|
| Ver el resumen y los documentos enviados y recibidos de todos tus clientes, con el cliente de cada uno | Cualquier miembro, incluido viewer |
| Elegir un cliente y ver su resumen, documentos, anulaciones, logs de la DGII, certificación y certificados | Cualquier miembro |
| Certificar a un cliente: firmar su postulación, subir su set de pruebas, crear el caso, ejecutar las pruebas y registrar sus pasos | Owner o developer |
Cargar el .p12 de un cliente, con su autorización | Owner o developer |
| En Desarrolladores → Credenciales: crear, rotar y revocar claves de la API | Owner o developer |
| En Desarrolladores → Webhooks: agregar, editar y eliminar endpoints y rotar su secreto; enviar pruebas, pausarlos, ver payloads y reenviar entregas | Owner o developer |
| En Partner → Cuentas fiscales y Consumo: ver tus clientes, su certificación, el consumo del mes y las entregas | Cualquier miembro |
Las Cuentas fiscales no se crean en el dashboard: las crea tu backend con la API. Emitir, anular y responder la aprobación comercial de un cliente también se hace con la API. Activar tu cuenta Partner no habilita la producción de ningún cliente: cada uno necesita su certificación y su activación.
Credenciales
| Credencial | Dónde vive | Para qué |
|---|---|---|
X-PARTNER-KEY | Solo en el backend de tu ERP. | Todas las rutas /partner/v1. |
Authorization: Upload <uploadToken> | En el navegador de tu cliente, para una sola carga. | Subir su .p12 directo a ZarelaFact. |
- Las claves que creas en el portal empiezan por
zrp_live_. El prefijo solo dice qué instalación de ZarelaFact emitió la clave, no a qué ambiente llega: no hay un portal aparte para pruebas, y Sandbox, TesteCF y producción se eligen por ruta. Ningún perfil limita el ambiente (documents:createemite igual en TesteCF y en producción), así que si una clave es solo para tu backend de desarrollo, bloquea en tu código las rutas/production/. - Las claves vencen en
expiresAt(máximo 366 días si las creas desde el portal) y se muestran una sola vez. Guárdalas en tu gestor de secretos. - Nunca las envíes al navegador, a una app móvil ni al POS del cliente.
- Por defecto una clave tiene todos los permisos (
full), como la clave secreta de Stripe. Si prefieres una clave por proceso de tu backend, elige Limitar permisos y un perfil: certificación y alta de clientes (onboarding), emitir y consultar documentos (runtime) owebhooks. - Para crearlas o cambiarlas en el portal necesitas el correo verificado y el rol owner o developer. Si el portal responde
429, espera lo que indiqueRetry-After.
Crea la clave nueva, instálala en tu backend, verifica que funciona y después revoca la anterior. El portal no deja revocar la última clave que funciona. ZarelaFact no puede recuperar una clave perdida: crea otra.
Carga del certificado
El .p12 lo sube el navegador de tu cliente directo a ZarelaFact. Tu backend nunca recibe el archivo ni su contraseña.
- Tu backend pide una sesión con
POST /fiscal-accounts/{id}/certificate-upload-sessionsy{"browserOrigin":"https://erp.example.com"}. - Entregas a tu pantalla solo
uploadUrlyuploadToken. - El navegador envía un
multipart/form-dataauploadUrlcon unfiley unpassphrase.
browserOrigin es el origen HTTPS exacto de tu pantalla, sin rutas, comodines ni parámetros, y debe salir de la configuración de tu backend, no del navegador. Si tienes varias marcas, tu backend elige el origen de cada cliente. No hace falta registrar dominios: el origen queda ligado a esa sesión.
La sesión sirve para una carga correcta. Una contraseña o un archivo equivocado no la gasta: admite cinco intentos y cada error trae details.attemptsRemaining. Si vence (15 minutos) o se agotan los intentos, pide otra. Para reemplazar un certificado usa certificate-rotation-requests, con el mismo contrato. ZarelaFact comprueba que la clave privada corresponda al certificado, exige RSA, rechaza certificados de autoridad certificadora, vencidos, sin el RNC, la cédula o el pasaporte del titular en el SN (422 CERTIFICATE_HOLDER_ID_MISSING) o cuyo uso de clave no permita firmar (422 CERTIFICATE_KEY_USAGE_INVALID), y lo instala en los ambientes de esa Cuenta fiscal.
El certificado puede ser el del contribuyente o el de la persona que lo representa ante la DGII, como exige la DGII. ZarelaFact lee la cédula o el RNC del titular en el campo serialNumber del certificado. Si el RNC de la Cuenta fiscal es una cédula (persona física), el certificado debe ser de esa persona: otro responde 409 CERTIFICATE_HOLDER_MISMATCH.
Desde el dashboard
Si el contribuyente te entrega su .p12 y te autoriza, cárgalo tú:
- Elige el cliente en el selector y abre Certificados.
- Sube el archivo y escribe su contraseña.
- Marca El contribuyente me autorizó a cargar su certificado en ZarelaFact y pulsa Subir y activar.
Se aplican las mismas reglas que en la carga desde tu pantalla, y la carga queda en la auditoría con tu usuario. Lo necesitan el rol owner o developer y el correo verificado. Aun así, la carga desde tu pantalla es la recomendada: con ella ni tú ni tu equipo tienen nunca el archivo ni la contraseña.
Lo que el Partner no puede hacer
Para proteger a tus clientes:
- Con la carga desde tu pantalla no recibes su certificado ni su contraseña: van del navegador del cliente a ZarelaFact. Si el cliente te los entrega para cargarlos desde el dashboard, necesitas su autorización y la carga queda auditada.
- No ves las cuentas de otros Partners, aunque conozcas su RNC o su identificador.
- No activas la producción a mano: se activa sola cuando el cliente completa la certificación, y la DGII sigue siendo el control fiscal.
- No cambias el RNC de una Cuenta fiscal en producción. Antes de producción sí: cambiar el RNC o liberar una cuenta.
- En el dashboard de un cliente lo certificas y cargas su certificado, pero no emites, anulas ni cambias sus datos: esos cambios responden
403 PARTNER_READ_ONLYy se hacen con la API.
Titularidad del RNC
Un RNC solo puede estar con un Partner a la vez. Vincularlo lo reserva. Lo demuestra un certificado con el RNC del contribuyente al instalarse; si es el certificado de su representante, lo demuestra la DGII al aceptar el primer e-CF firmado con él.
| Campo de la cuenta | Qué significa |
|---|---|
ownership.verified | true desde que se instaló un certificado con el RNC del contribuyente o la DGII aceptó el primer e-CF firmado. |
ownership.verifiedAt | Cuándo se verificó. |
ownership.claimExpiresAt | Hasta cuándo dura la reserva sin verificar (30 días por defecto). |
- La reserva no se extiende ni se pausa durante la certificación, y no se pierde sola: solo se libera si vence sin verificar y otro Partner vincula el mismo RNC. En ese caso la cuenta deja de existir para ti y su caso abierto se cierra.
- Con un certificado del representante (con su cédula en vez del RNC), la titularidad se verifica con el primer e-CF firmado que acepte la DGII. Eso ocurre en las pruebas de datos de la certificación, minutos después de enviarlas.
- Una cuenta verificada o con producción activa nunca se libera sola.
- Si el RNC ya está con otra plataforma o es cliente directo de ZarelaFact, recibes
409 RNC_NOT_AVAILABLE, sin revelar con quién está. Si de verdad es tu cliente, pídele que escriba a [email protected]: con su autorización se libera el vínculo anterior y deberá cargar su certificado otra vez.
Cambiar el RNC o liberar una cuenta
Mientras una Cuenta fiscal nunca haya estado en producción ni la haya solicitado, es tuya para corregirla:
- Cambiar el RNC (por ejemplo, se escribió mal o era una prueba): repite
PUT /fiscal-accounts/by-external-id/{externalTenantId}con el RNC nuevo y"replacesFiscalAccountId"con elfiscalAccountIdactual. Responde201con una Cuenta fiscal nueva para el mismoexternalTenantIdyreplacedFiscalAccountIdcon la anterior. Guarda elfiscalAccountIdnuevo: el anterior responde404. SinreplacesFiscalAccountId, otro RNC responde409 ACCOUNT_LINK_CONFLICT: así un RNC mal escrito en tu ERP no suelta la cuenta. - Liberar la cuenta (ya no la necesitas):
DELETE /fiscal-accounts/{id}. Deja de aparecer en tu listado y el RNC y elexternalTenantIdquedan libres.
En los dos casos la cuenta anterior se cierra: se cierra su certificación abierta y se revoca su certificado. Sus e-CF de prueba y la auditoría se conservan con ese RNC. La certificación es del RNC, así que el RNC nuevo empieza desde cargar su certificado.
Cada Partner ve solo lo que se creó desde que vinculó la cuenta: si un RNC estuvo antes con otra plataforma o en una cuenta liberada, ese historial no aparece en la API ni en el dashboard.
No se puede mientras haya algo en curso: 409 CERTIFICATION_IN_PROGRESS si la certificación tiene un envío en curso, espera a la DGII o está bloqueada, y 409 DOCUMENTS_IN_PROGRESS si hay e-CF en proceso. Una cuenta que ya pasó a producción, o la solicitó, responde 409 FISCAL_ACCOUNT_IN_PRODUCTION: sus cambios los hace soporte de ZarelaFact.
Ambientes
Cada Cuenta fiscal tiene sus tres ambientes desde que la vinculas:
| Ambiente | Uso en la API Partner | Plan |
|---|---|---|
| TesteCF | El ambiente de pruebas de la DGII para cada cliente: emite facturas de prueba con /fiscal-accounts/{id}/testecf/documents y prueba la recepción y la aprobación comercial con /fiscal-accounts/{id}/testecf/inbound-documents. No requiere certificación ni producción activa. | Gratis: no cuenta en tu plan. |
| CerteCF | Certificación de cada cliente ante la DGII. | Gratis. |
| eCF | Producción, solo después de la activación, con /fiscal-accounts/{id}/production/documents. | Cuenta en tu plan. |
TesteCF firma con el mismo certificado .p12 que cargaste para el cliente, así que primero carga su certificado. Es compartido por todos los contribuyentes: usa secuencias altas (por ejemplo E310009000001) para no chocar con eNCF que la DGII ya recibió. Muestra el ambiente en tu pantalla y no mezcles estados ni secuencias entre ambientes: un documento de TesteCF nunca aparece en producción.
Tu cuenta Partner también tiene un Sandbox propio, sin certificado ni Cuenta fiscal: pruebas el JSON de cualquiera de tus clientes y ves el veredicto que daría la DGII.
El recorrido completo
Cada etapa se explica en Certificación de cada cliente y en Activación y emisión.
Alcance actual
La API Partner cubre el ciclo completo de cada cliente: alta, certificado, certificación con su set de pruebas, activación de producción, emisión, XML y PDF, anulación (ANECF), documentos recibidos y aprobación comercial (ACECF). Todas las rutas están en Rutas y errores.
X-PARTNER-KEY no funciona en las rutas /{ambiente} de la cuenta directa: usa siempre las rutas /partner/v1.