Saltar al contenido principal

Varios clientes (Partners)

Esta sección es para empresas de software (ERP, POS, CRM o SaaS) que emiten e-CF para varios negocios.

En resumen
  • 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​

ConceptoQué esCómo lo identificas
PartnerTu 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 fiscalEl 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é​

EtapaTu cliente, en tu productoTu backend, con la APIZarelaFact
AltaCompleta sus datos fiscales.Crea su Cuenta fiscal.Reserva el RNC para ti.
CertificadoSube 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ónHace 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ónEmpieza a facturar.Espera el webhook production.state_changed.La activa sola al completarse la certificación.
EmisiónVende 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​

  1. En el registro eliges ERP / POS Partner e indicas los datos y el RNC de tu empresa, no los de un cliente.
  2. 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.
  3. 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 puedesQuién
Ver el resumen y los documentos enviados y recibidos de todos tus clientes, con el cliente de cada unoCualquier miembro, incluido viewer
Elegir un cliente y ver su resumen, documentos, anulaciones, logs de la DGII, certificación y certificadosCualquier miembro
Certificar a un cliente: firmar su postulación, subir su set de pruebas, crear el caso, ejecutar las pruebas y registrar sus pasosOwner o developer
Cargar el .p12 de un cliente, con su autorizaciónOwner o developer
En Desarrolladores → Credenciales: crear, rotar y revocar claves de la APIOwner o developer
En Desarrolladores → Webhooks: agregar, editar y eliminar endpoints y rotar su secreto; enviar pruebas, pausarlos, ver payloads y reenviar entregasOwner o developer
En Partner → Cuentas fiscales y Consumo: ver tus clientes, su certificación, el consumo del mes y las entregasCualquier 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​

CredencialDónde vivePara qué
X-PARTNER-KEYSolo 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:create emite 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) o webhooks.
  • 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 indique Retry-After.
Renovar una clave sin cortar el tráfico

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.

  1. Tu backend pide una sesión con POST /fiscal-accounts/{id}/certificate-upload-sessions y {"browserOrigin":"https://erp.example.com"}.
  2. Entregas a tu pantalla solo uploadUrl y uploadToken.
  3. El navegador envía un multipart/form-data a uploadUrl con un file y un passphrase.

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ú:

  1. Elige el cliente en el selector y abre Certificados.
  2. Sube el archivo y escribe su contraseña.
  3. 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_ONLY y 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 cuentaQué significa
ownership.verifiedtrue desde que se instaló un certificado con el RNC del contribuyente o la DGII aceptó el primer e-CF firmado.
ownership.verifiedAtCuándo se verificó.
ownership.claimExpiresAtHasta 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 el fiscalAccountId actual. Responde 201 con una Cuenta fiscal nueva para el mismo externalTenantId y replacedFiscalAccountId con la anterior. Guarda el fiscalAccountId nuevo: el anterior responde 404. Sin replacesFiscalAccountId, otro RNC responde 409 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 el externalTenantId quedan 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:

AmbienteUso en la API PartnerPlan
TesteCFEl 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.
CerteCFCertificación de cada cliente ante la DGII.Gratis.
eCFProducció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.