Guía paso a paso

Esta ruta es para una plataforma que atiende varios contribuyentes. Tu cliente se queda en tu ERP/POS: allí carga su certificado, sigue su certificación y emite sus facturas. Tu backend usa una sola API y guarda dos identificadores por cliente: tu externalTenantId y el fiscalAccountId de ZarelaFact.

#	Paso	Detalle
1	Registra tu plataforma y crea una clave	Cómo funciona
—	Planifica lo que construirás en tu producto	Qué construir en tu ERP
2	Vincula a un contribuyente	Esta página
3	Deja que cargue su certificado	Carga del certificado
4	Ayúdale con la postulación DGII	Postulación
5	Crea el caso y ejecuta las pruebas	Certificación
6	Registra los pasos en la DGII: producción se activa sola	Activación y emisión
7	Emite y concilia	Activación y emisión
8	Recibe eventos	Webhooks

Alcance

El contrato Partner cubre la certificación CerteCF, la activación automática de eCF, la emisión y su conciliación, el XML y el PDF, la anulación (ANECF), los documentos recibidos y la aprobación comercial (ACECF).

1. Registra tu plataforma y crea una clave

En el registro elige ERP / POS Partner, identifica a tu empresa con su RNC y elige pago por uso o un plan.
Confirma tu correo con el enlace que te enviamos y entra al dashboard; el acceso es inmediato.
En Desarrolladores → Credenciales, pulsa Crear credencial. Su valor se muestra una sola vez: guárdalo en el gestor de secretos de tu backend.

En los ejemplos, BASE_URL ya incluye /partner/v1 y las variables viven solo en tu backend:

BASE_URL='https://api.zarelafact.com/partner/v1'
PARTNER_KEY='<clave-del-secret-manager>'
EXTERNAL_TENANT_ID='<id-estable-de-tu-cliente>'

2. Vincula a un contribuyente

Una llamada por cliente; repítela si perdiste la respuesta. El RNC es el del contribuyente, no el de tu plataforma.

curl -sS -X PUT "$BASE_URL/fiscal-accounts/by-external-id/$EXTERNAL_TENANT_ID" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H 'Content-Type: application/json' \
  --data '{"rnc":"<RNC_DEL_CLIENTE>","legalName":"<RAZON_SOCIAL_DEL_CLIENTE>"}'

201 crea la Cuenta fiscal y 200 devuelve la existente. Guarda el fiscalAccountId junto a tu externalTenantId: todas las rutas siguientes lo usan.

ZarelaFact verifica el RNC en el padrón de contribuyentes de la DGII: si no aparece responde 422 RNC_NOT_IN_DGII_REGISTRY, y si no está ACTIVO, 422 RNC_NOT_ACTIVE_IN_DGII. Repetir la llamada con el RNC ya vinculado no se bloquea. El dígito verificador no es motivo de rechazo.

3. Deja que cargue su certificado

Tu backend pide una sesión temporal con el origen HTTPS exacto de tu UI:

curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/certificate-upload-sessions" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H 'Content-Type: application/json' \
  --data '{"browserOrigin":"https://erp.example.com"}'

Entrega uploadUrl y uploadToken a la UI de ese cliente. Su navegador envía el .p12 y su contraseña directamente a uploadUrl; tu backend nunca los recibe.

4. Ayúdale con la postulación DGII

Muestra en tu UI los datos que el contribuyente debe copiar en el portal DGII (software ZarelaFact, proveedor ZARELA GROUP SRL y URLs):

curl -sS "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/dgii-registration" \
  -H "X-PARTNER-KEY: $PARTNER_KEY"

DGII genera un XML de postulación que debe firmarse con su certificado. Tu backend lo firma con POST .../certification-xml-signatures y le devuelve el archivo para subirlo. Ver Postulación ante la DGII.

5. Crea el caso y ejecuta las pruebas

Cuando la DGII acepte la postulación, entregará al contribuyente su set de pruebas (un Excel). Súbelo y crea el caso con el testSetRef que recibes:

# Set de pruebas de ese contribuyente (Excel o JSON en base64)
curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/certification-test-sets" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H 'Content-Type: application/json' \
  --data "{\"fileName\":\"set-dgii.xlsx\",\"contentBase64\":\"$(base64 < set-dgii.xlsx | tr -d '\n')\"}"

# Caso CerteCF
curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/certification-cases" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H 'Content-Type: application/json' \
  --data '{"officialSetRef":"<TEST_SET_REF>"}'

# Ejecución del set (guarda la Idempotency-Key antes de llamar)
curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/certification-cases/$CASE_ID/runs" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H "Idempotency-Key: $RUN_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' --data '{}'

Registra cada paso que el usuario completa en DGII con POST .../attestations, empezando por dgii_postulation_submitted. Cuando la DGII acepta el run, el caso trae downloads: el XML íntegro (e-CF) de cada Factura de Consumo menor a RD$250,000, que el usuario sube en Facturas de consumo < 250Mil de la DGII, y los PDF impresos del paso siguiente.

Después, el caso trae nextAction: send_commercial_approvals (paso 3 de la DGII). El usuario descarga en CerteCF el Excel de aprobaciones comerciales, lo sube en tu ERP y pulsa «Continuar». Tu backend lo envía a ZarelaFact, que firma cada fila y la envía; su avance está en GET de la misma ruta:

ACECF_XLSX_BASE64=$(base64 < aprobaciones-comerciales.xlsx | tr -d '\n')
curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/certification-cases/$CASE_ID/commercial-approvals" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H "Idempotency-Key: $ACECF_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' --data "{\"workbookBase64\":\"$ACECF_XLSX_BASE64\"}"

Ver Certificación de cada contribuyente.

6. Producción se activa sola

Cuando el run deja su evidencia y registras la quinta atestación (los roles en la OFV), el caso pasa a approved y la producción del cliente se activa sola: recibes production.state_changed con state: "active" y GET /fiscal-accounts/{id}/production lo confirma. Si el certificado venció antes, carga uno nuevo y repite la activación con POST .../production-activation-requests (ver Activación y emisión).

7. Emite y concilia

Tu ERP asigna el eNCF y envía el JSON DGII/XSD dentro de document. Antes de producción, prueba en el sandbox del cliente: POST .../testecf/documents envía la factura al ambiente de pruebas de la DGII con su certificado, sin activación ni plan, y no cuenta en tu plan (usa secuencias altas, por ejemplo E310009000001). Ya en producción, emite sin ?validate=true:

curl -sS -X POST "$BASE_URL/fiscal-accounts/$FISCAL_ACCOUNT_ID/production/documents" \
  -H "X-PARTNER-KEY: $PARTNER_KEY" -H 'Content-Type: application/json' \
  --data '{"document":{"ECF":{"...":"JSON DGII/XSD completo"}}}'

202 significa encolado, no aceptado. Guarda result.documentId y concilia con POST .../production/documents/status/batch. Unos segundos después, cuando la DGII responde, esa consulta trae printing con el código de seguridad y el QR para imprimir la factura, y si la DGII rechaza el documento, dgiiMessages con el motivo. Ante un timeout reenvía el mismo JSON con el mismo eNCF.

8. Recibe eventos

Crea tu webhook desde el dashboard (Desarrolladores → Webhooks → Agregar endpoint) o con POST /webhook-endpoints. Guarda el secreto de firma, que se muestra una sola vez, y pulsa Enviar evento de prueba. Tu receptor valida la firma y deduplica por Zarela-Event-Id. Ver Webhooks Partner.

Antes de abrirlo a tus clientes

Prueba con al menos dos Cuentas fiscales: cada certificado y RNC queda en su cuenta, no puedes consultar la cuenta ajena y CerteCF no habilita eCF por sí solo.

1. Registra tu plataforma y crea una clave​

2. Vincula a un contribuyente​

3. Deja que cargue su certificado​

4. Ayúdale con la postulación DGII​

5. Crea el caso y ejecuta las pruebas​

6. Producción se activa sola​

7. Emite y concilia​

8. Recibe eventos​