Preguntas frecuentes

General

¿Quién es APPWORK SRL?

APPWORK SRL es la empresa sombrilla detrás de Digimart, certificada por la DGII como Proveedor de Servicios de Facturación Electrónica. Esta certificación nos autoriza a operar la infraestructura técnica de firma y envío de e-CFs en nombre de contribuyentes. Tu contrato comercial es con APPWORK SRL; los servicios técnicos se prestan sobre infraestructura de Digimart.

¿Necesito estar certificado por la DGII para usar esta API?

Sí — pero como Emisor Electrónico, no como Proveedor. Son dos certificaciones DGII diferentes:

Sin ser Emisor Electrónico certificado, DGII rechaza cualquier e-CF a nombre de tu RNC aunque el proveedor técnico (nosotros) esté correctamente certificado.

¿Cómo me certifico como Emisor Electrónico?

Es un proceso gratuito ante DGII. Desde Digimart te lo facilitamos con una guía paso a paso que te lleva por todo el flujo:

1. Ve a Configuración → DGII → Emisor Electrónico en Digimart.
2. Sigue la guía: generación de certificado, envío de carta de intención, pruebas en ambiente CerteCF, etc.
3. DGII te emite la resolución que te autoriza como Emisor Electrónico.
4. Sube tu certificado .p12 a Digimart.
5. Ya puedes usar la API en producción.

Si todavía no estás certificado puedes usar el ambiente testecf (pruebas) y certecf (certificación oficial DGII) GRATIS — son los ambientes que DGII usa para evaluarte durante el proceso.

¿Cuánto tarda la activación?

Típicamente menos de 5 minutos desde el panel de Digimart. Si nunca has configurado tu certificado .p12 con nosotros, agrega ~30 minutos de soporte para subirlo correctamente.

¿Tienen SLA?

Sí — 99.5% de uptime sobre los endpoints públicos. Excluyendo:

• Downtime planificado anunciado con 7 días de anticipación.
• Downtime de DGII (no controlamos).
• Causas mayores documentadas (catástrofes, ataques DDoS).

Si necesitas un SLA más estricto, contáctanos para un acuerdo enterprise.

Autenticación y seguridad

¿Por qué dos pasos (apiKey + JWT) en vez de uno solo?

Para limitar exposición del secret. Si tu key estática viajara en cada request, cada log, cada cache, cada herramienta de red la tendría. El JWT corto se rota cada hora, así un leak temporal se "ventila" solo.

¿Puedo tener varias keys al mismo tiempo?

Sí. Patrón típico: una por entorno (prod, staging, dev), o una por servicio (api-server, cron-worker, dashboard).

¿Qué pasa si reviso una key activa?

Las llamadas siguientes (incluyendo /login) fallan con 401 API key has been revoked o Invalid credentials. Los JWTs en vuelo expiran en máximo 30 segundos (cache invalidation del lado servidor).

¿Puedo usar la API desde el frontend del navegador?

No. El apiSecret debe vivir solo en tu backend. Desde el browser sería visible a cualquiera con devtools, e incluso si lo obfuscaras, los requests serían interceptables. Patrón correcto: tu backend hace /login, el frontend hace requests al TU backend, tu backend forwardea a la FE API.

Facturación

¿Pago una factura separada por el FE API o se agrega a mi suscripción?

Se agrega a tu factura mensual de Digimart. Una sola factura, una sola cobranza, líneas separadas para transparencia.

¿Por qué los precios están en USD si Azul cobra en DOP?

Para evitar que el costo te cambie con cada movimiento de la tasa de cambio. Tú piensas en términos estables (USD); la conversión a DOP ocurre una vez por mes al cierre del período usando la tasa del día.

¿Qué pasa si excedo mi presupuesto?

Nada automático. La API no limita emisiones por presupuesto. Si necesitas un freno duro, implementa tu propio checker contra GET /billing/current-period y deja de enviar cuando llegues al límite.

Para volúmenes altos podemos negociar un tope contractual mensual.

¿Devuelven dinero por emisiones rechazadas por DGII?

No procede — solo cobramos emisiones aceptadas. Las rechazadas tienen costo $0.00 desde el principio.

Aspectos técnicos

¿Por qué async? ¿No me responden con el resultado directo?

Porque DGII puede tomar 1-15 segundos en responder, y a veces más en horas pico. Hacer await sync en cada request causaría:

• Timeouts en tu lado cuando DGII está lento.
• Conexiones abiertas mucho tiempo (caro).
• Cascadas de timeouts en sistemas downstream.

El patrón async (POST → 202 → polling) es estándar para integraciones con sistemas regulatorios.

¿Puedo emitir e-CFs sin manejar yo el XML?

Sí. Usa format: "digimart" y mándanos un JSON estructurado. Convertimos a XML por ti.

¿Y si tengo el XML ya generado por otra herramienta?

Mándanoslo con format: "xml". Lo firmamos (re-firmamos si la firma no está actualizada) y enviamos.

¿Qué tipos de e-CF soportan?

Todos los tipos del endpoint estándar de recepción DGII, vía el campo TipoeCF dentro del XML/JSON. El endpoint POST /invoices es el mismo para todos:

• 31 Factura de Crédito Fiscal — B2B con derecho a crédito ITBIS
• 32 Factura de Consumo — B2C, consumidor final
• 33 Nota de Débito Electrónica — aumento sobre e-CF previo
• 34 Nota de Crédito Electrónica — devolución / descuento
• 41 Compras — gastos informales a no-emisores
• 43 Gastos Menores — operaciones de bajo monto
• 44 Régimen Especial
• 45 Gubernamental — operaciones con el Estado
• 46 Comprobante Pago Exterior
• 47 Régimen Especial Pago Exterior

El endpoint se llama /invoices por convención internacional (Stripe, etc.) pero internamente maneja todos los tipos por igual — lo que define el tipo es el TipoeCF del header del documento, no la URL.

¿Y la aprobación comercial (ACECF / ANECF)?

✅ Cubierta. Manda el documento al mismo POST /invoices con root <ACECF> o <ANECF> — el worker detecta el tipo y rutea al endpoint DGII de aprobación comercial automáticamente. Sirve tanto para aprobaciones de e-CFs como de notas (débito/crédito).

¿Y el Resumen de Facturas de Consumo (RFCE)?

✅ Cubierto. Mismo POST /invoices con root <RFCE>. El worker detecta el tipo y lo rutea al host de CF (fc.dgii.gov.do) automáticamente. Una sola integración del lado del cliente para los TRES flujos.

¿Y la aprobación comercial (Flujo C)?

En roadmap. Por ahora cubrimos el Flujo A (emisor → DGII). Si necesitas Flujo C urgente, escríbenos.

¿Cuánto duran las llamadas típicas?

La emisión a DGII (que ocurre async después de tu POST) toma adicionalmente 1-3 segundos.

¿Hay rate limits?

Por ahora no impuestos en hardcoded. Recomendamos no exceder ~10 req/s por tenant para evitar saturar la cola interna. Si necesitas más, contáctanos para configurar un quote dedicado.

Operacional

¿Cómo me entero cuando DGII tiene problemas?

Suscríbete a nuestro status page (próximamente: status.appworkcloud.com). Por ahora, las incidencias mayores se notifican por correo al contacto técnico registrado en tu setup.

¿Tienen webhooks para notificación de cambio de estado?

No por ahora. Usa polling con GET /invoices/:id. Si los necesitas, escríbenos — tenemos diseño preliminar.

¿Versionan la API?

Sí. El prefijo /api/v1/fe/ es la versión actual. Si lanzamos breaking changes, será /api/v2/fe/ y v1 quedará disponible mínimo 12 meses.

¿Qué pasa con un envío si el procesamiento async falla 8 veces?

Va al Dead Letter Queue interno. Un operador investiga. Tú recibes el estado error al consultar GET /invoices/:id — el envío no se cobra porque no llegó a estado Aceptado.

Si quieres reintentarlo, envía la misma factura con un nuevo clientRequestId (no el mismo — ese ya quedó marcado como permanent error).

Roadmap

• Webhooks de cambio de estado.
• Soporte para Resumen de Facturas de Consumo (RFC).
• Aprobación comercial (Flujo C).
• SDK oficial en JavaScript/TypeScript y Python.
• Status page público.
• OpenAPI/Swagger spec downloadable.
• Sandbox compartido con datos de demo.

¿Algo que necesitas urgente? Escríbenos a hola@digimart.cloud.