Por qué construimos otra API de e-CF

Hay docenas de soluciones para facturación electrónica en República Dominicana. Antes de empezar nos hicimos la pregunta honesta: ¿el mundo necesita una más?

La respuesta vino de los clientes. Las empresas con las que trabajamos llegaron diciendo cosas como:

• “Mi proveedor cobra por documento, y mi volumen lo hace inviable.”
• “La API que usamos no nos deja firmar localmente; envían el XML sin firmar a su servidor.”
• “No tengo visibilidad sobre qué pasó cuando un comprobante falla.”
• “Cada vez que la DGII cambia algo, espero dos semanas a que mi proveedor actualice.”

Lo que faltaba no era una API más. Era una API diseñada para integradores, no para usuarios finales.

Hoy lanzamos públicamente ECF SSD API — la misma que ya está corriendo en producción para varios clientes en banca, retail y manufactura.

Principios de diseño

1. Tú firmas, no nosotros

La firma XAdES-BES se hace donde está tu certificado, no en nuestros servidores. Ofrecemos:

• SDK que firma localmente con tu certificado P12.
• Endpoint que recibe el XML ya firmado y solo se encarga del envío a DGII.

¿Por qué importa? Porque tu clave privada nunca debe salir de tu infraestructura. Si un proveedor de e-CF te pide subir tu certificado P12, cámbiate de proveedor.

2. Idempotencia real

Cada operación acepta un Idempotency-Key. Reintenta tres veces si quieres: solo vas a generar un e-CF.

POST /v1/comprobantes
Authorization: Bearer ssd_live_...
Idempotency-Key: 8f3d2c9a-7b1e-4a5f-9d2c-1e8b3f7a9c4d
Content-Type: application/xml

<ECF xmlns="...">...</ECF>

Implementado correctamente: si la primera llamada falla a mitad del camino (después del envío a DGII pero antes de devolverte la respuesta), tu reintento recupera el estado real, no duplica el envío.

3. Observabilidad de extremo a extremo

Cada e-CF tiene un tracking_id que sigue la transacción a través de:

• Tu envío a SSD.
• Nuestro envío a la DGII.
• El acuse (ACECF) de respuesta.
• Tu webhook de confirmación.

GET /v1/comprobantes/E310000000123/timeline

{
  "tracking_id": "trk_01HXY...",
  "events": [
    { "at": "2026-05-25T10:14:02Z", "type": "received", "duration_ms": 12 },
    { "at": "2026-05-25T10:14:02Z", "type": "signed_locally" },
    { "at": "2026-05-25T10:14:03Z", "type": "submitted_to_dgii", "duration_ms": 847 },
    { "at": "2026-05-25T10:14:04Z", "type": "acecf_received", "result": "ACEPTADO" },
    { "at": "2026-05-25T10:14:04Z", "type": "webhook_delivered", "endpoint": "https://..." }
  ]
}

4. Webhooks con reintentos exponenciales

Cuando llega un acuse de DGII, te notificamos. Si tu endpoint está caído, reintentamos por 24 horas con backoff exponencial. Cada webhook firmado con HMAC-SHA256 para que verifiques la autenticidad.

import { verifyWebhook } from '@ssd/ecf-sdk'

export async function POST(req: Request) {
  const signature = req.headers.get('x-ssd-signature')
  const body = await req.text()

  if (!verifyWebhook(body, signature, process.env.SSD_WEBHOOK_SECRET)) {
    return new Response('Invalid signature', { status: 401 })
  }

  const event = JSON.parse(body)
  // event.type === 'acecf.received'
  // event.data.tracking_id === 'trk_01HXY...'
}

5. Sandbox con paridad real

Nuestro ambiente sandbox apunta a TesteCF de la DGII, no a un mock interno. Cuando emites un e-CF de prueba, pasa por el mismo ciclo que producción — solo que contra el ambiente de pruebas oficial. Si funciona en sandbox, va a funcionar en producción.

Arquitectura por dentro

┌─────────────────┐    XML+P12     ┌──────────────────┐
│ Tu aplicación   │ ──────────────▶ │ SSD SDK          │
│ (ERP, POS, etc.)│                │ (firma local)    │
└─────────────────┘                └────────┬─────────┘
                                            │ XML firmado
                                            ▼
                                  ┌──────────────────┐
                                  │ SSD Edge Worker  │
                                  │ (Cloudflare)     │
                                  └────────┬─────────┘
                                           │ HTTPS
                                           ▼
                                  ┌──────────────────┐
                                  │ DGII Endpoint    │
                                  │ (Producción o    │
                                  │  TesteCF)        │
                                  └──────────────────┘

• Edge runtime (Cloudflare Workers): la API vive en 300+ ciudades. Tu llamada va al nodo más cercano, no a un servidor central. Latencia promedio a DGII: <45ms.
• D1 + R2: guardamos el rastreo y los XML firmados (los originales, no las claves). Retención configurable según tus requisitos de cumplimiento.
• Cero estado en RAM: cada request es independiente. Si una región se cae, la siguiente toma el tráfico sin pérdida.

Lo que cubre hoy

Tipo de comprobante	Soportado
31 — Factura de Crédito Fiscal Electrónica	✅
32 — Factura de Consumo Electrónica	✅
33 — Nota de Débito Electrónica	✅
34 — Nota de Crédito Electrónica	✅
41 — Compras Electrónica	✅
43 — Gastos Menores Electrónica	✅
44 — Regímenes Especiales	✅
45 — Gubernamental Electrónica	✅
46 — Exportaciones Electrónica	✅
47 — Pagos al Exterior Electrónica	✅
RFCE — Resumen de Comprobantes Emitidos	✅
ARECF — Aprobación Comercial	✅

Precio: por uso, sin sorpresas

Cobramos por comprobante enviado con éxito a DGII. No por intento. No por consulta. No por documento de prueba. Más detalle en la página del producto.

Lo que viene

• SDKs oficiales: ya está disponible TypeScript/Node. C#/.NET, Python y PHP cierran en el próximo trimestre.
• Integración Odoo: módulo nativo, sin middleware adicional.
• Reporte 606 / 607: anexos contables generados desde tu histórico de e-CF.
• Multi-tenant: para casas de software que quieren ofrecer e-CF a sus clientes sin construir desde cero.

Si quieres credenciales de sandbox, escríbenos. Te respondemos en horas, no en semanas.

— El equipo de SSD