Nuvem FE Facturación electrónica

Conecte su sistema con Nuvem FE

Su sistema de ventas manda los datos de la venta. Nuvem hace la factura electrónica, la lleva a la DGII y le devuelve el resultado.

  1. 1. Su sistemamanda la venta
  2. 2. Nuvemhace y firma la factura
  3. 3. La DGIIla revisa
  4. 4. Ustedrecibe el número, el QR y el PDF

Empezar ahora

Empiece en 4 pasos

Los pasos 1 a 3 no necesitan programador. Se hacen con botones, dentro de Nuvem FE.

  1. 1

    Abra la empresa demo

    Es una empresa de práctica: nada se envía a la DGII. En Nuvem FE entre a Empresa, baje hasta Demo y pulse Crear demo: ya emisor.

  2. 2

    Cree un token

    Es la clave con la que su sistema entra a Nuvem. Entre a Conectar su sistema, escriba un nombre y pulse Crear token.

  3. 3

    Haga una factura de prueba

    En esa misma página pulse Crear una factura de prueba. Si ve «Listo» y puede abrir el PDF, ya funciona.

  4. 4

    Conecte su sistema de verdad

    Pásele esta página a quien maneja su sistema. Cuando la conexión funcione con la demo, abra su empresa real, cree otro token y cámbielo.

    Para usar su empresa real, debe ser emisor electrónico, tener sus secuencias en Nuvem y facturar en Nuvem, sin ADM Cloud ni QuickBooks conectados.

Con el token de su empresa real, cada factura es real ante la DGII y cuenta en su plan.

Para el programador: hacer una factura

Es un solo pedido. Su sistema manda esto a POST https://ecf.nuvem.com.do/api/v1/ecf:

{
  "tipo": "31",
  "comprador": { "rnc": "101010101", "nombre": "Cliente Ejemplo SRL" },
  "lineas": [
    { "descripcion": "Servicio de mantenimiento", "cantidad": 1, "precio": 15000 }
  ]
}
DatoQué poner
tipo31 crédito fiscal, 32 consumo, 44 régimen especial, 45 gubernamental, 46 exportación.
compradorNombre y RNC o cédula. En consumo, el nombre puede ser Consumidor final y el RNC se deja fuera si la factura es de menos de RD$250,000.
lineasLo que se vendió: descripcion, cantidad y precio.

El número de la factura lo pone Nuvem. Con el pedido van dos encabezados:

EncabezadoQué poner
AuthorizationBearer seguido de su token.
Idempotency-KeyUn código distinto para cada venta, como venta-10482. Use el número de venta de su sistema.

Ejemplo listo para copiar

const respuesta = await fetch("https://ecf.nuvem.com.do/api/v1/ecf", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.NUVEM_TOKEN,
    "Idempotency-Key": "venta-" + venta.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tipo: "31",
    comprador: { rnc: "101010101", nombre: "Cliente Ejemplo SRL" },
    lineas: [{ descripcion: "Servicio de mantenimiento", cantidad: 1, precio: 15000 }],
  }),
});
const factura = await respuesta.json();
console.log(factura.encf, factura.estado);

Lo que responde Nuvem

{
  "encf": "E310000000123",
  "estado": "aceptada",
  "monto_total": "17700.00",
  "itbis": "2700.00",
  "codigo_seguridad": "Ab12Cd",
  "qr_url": "https://ecf.dgii.gov.do/ecf/consultatimbre?...",
  "enlaces": {
    "pdf": "/api/v1/ecf/E310000000123/pdf",
    "xml": "/api/v1/ecf/E310000000123/xml"
  }
}

Guarde el encf (número de la factura), el codigo_seguridad y el qr_url: la factura que le entrega al cliente debe llevarlos. El PDF ya viene armado con todo eso.

Cómo saber qué pasó

Mire el campo estado:

EstadoQué significaQué hacer
aceptadaLa DGII la aprobó.Entregue la factura.
aceptada_condicionalLa DGII la aprobó con observaciones.Lea mensaje y corrija lo que diga.
en_procesoLa DGII todavía no contesta.Pregunte otra vez cada 30 a 60 segundos con GET /api/v1/ecf/{encf}.
rechazadaLa DGII no la aprobó. El motivo va en mensaje.Corrija y mándela como una venta nueva, con otro Idempotency-Key.

Tres reglas para no tener problemas

  1. 1

    Cuide el token como una contraseña

    Guárdelo en el servidor. Nunca lo ponga en una página web ni en una app de celular. Si alguien lo ve, revóquelo y cree otro.

  2. 2

    Un Idempotency-Key por venta

    Si se cae el internet a mitad de un envío, repita el pedido con el mismo código. Nuvem no hace otra factura: le devuelve la que ya salió.

  3. 3

    El precio va sin ITBIS

    Nuvem suma el ITBIS. Si no dice nada, usa 18%. Para otra tasa, agregue "itbis": 16, 0 o "exento" en la línea.

Si algo sale mal

Cuando no se puede, Nuvem responde con un codigo y un mensaje que dice qué pasó:

Si diceQuiere decirQué hacer
TOKEN_INVALIDOEl token está mal copiado o se revocó.Cópielo otra vez o cree uno nuevo.
VALIDACIONFalta un dato o está mal. No se envió nada a la DGII.Corrija lo que diga mensaje y repita.
CUOTA_AGOTADASe acabaron las facturas de su plan.Cambie de plan en Nuvem FE.
SECUENCIASFaltan números autorizados o vencieron.Revise Secuencias en Nuvem FE.
ERP_CONECTADOEsa empresa factura desde ADM Cloud o QuickBooks.Siga usando el ERP, o permita la API en Conectar su sistema. Lo emitido por la API no pasa al ERP.
EN_CURSOEsa venta se está enviando.Espere unos segundos y repita con el mismo código.
ERROR_INTERNONuvem no pudo confirmar el resultado.Espere 10 minutos y repita con el mismo código.

Preguntas frecuentes

¿Qué es una API?

Es la forma en que dos sistemas se hablan sin que nadie esté pulsando botones. Aquí, su sistema de ventas le pide a Nuvem que haga una factura.

¿Necesito un programador?

Para probar, no. Para conectar su sistema, sí: alguien tiene que agregar ese pedido a su sistema. Pásele esta página.

¿Qué es un token?

Es una clave larga que empieza con nfe_. Identifica a su empresa. Nuvem la muestra una sola vez.

¿Qué diferencia hay entre e-CF y e-NCF?

El e-CF es la factura electrónica. El e-NCF es su número, por ejemplo E310000000123.

¿Cuesta más?

No. Lo que emita por aquí cuenta igual que lo que emita en la app, según su plan.

Tengo ADM Cloud o QuickBooks. ¿Necesito esto?

No. Esos sistemas ya se conectan con Nuvem FE desde la app. Esta guía es para sistemas propios, como un punto de venta o una tienda en línea.

¿Cómo anulo una factura?

Con una nota de crédito (tipo 34). La factura original debe estar aceptada en Nuvem:

{
  "tipo": "34",
  "ncf_modificado": "E310000000123",
  "codigo_modificacion": "1",
  "razon_modificacion": "Factura emitida por error",
  "comprador": { "rnc": "101010101", "nombre": "Cliente Ejemplo SRL" },
  "lineas": [
    { "descripcion": "Servicio de mantenimiento", "cantidad": 1, "precio": 15000 }
  ]
}

codigo_modificacion: 1 anulación total, 2 corrección de texto, 3 corrección de montos, 4 reemplazo de NCF. La nota de débito (tipo 33) lleva los mismos datos.

Referencia técnica

Para el programador. Si solo está probando, no necesita esta parte.

Todas las rutas

Dirección base: https://ecf.nuvem.com.do/api/v1. Se llama desde su servidor: la API no admite llamadas desde otra página web.

RutaQué hace
POST /ecfHace una factura o una nota.
GET /ecf/{encf}Devuelve una factura y su estado. Si sigue en_proceso, Nuvem le pregunta a la DGII.
GET /ecfLista: desde y hasta (AAAA-MM-DD), tipo, limite (hasta 100) y pagina. Responde datos, pagina, limite y total.
GET /ecf/{encf}/xmlEl XML firmado.
GET /ecf/{encf}/pdfEl PDF con el QR. Solo de facturas aceptadas.
GET /empresaRNC, razón social, ambiente, si puede emitir, y las secuencias con lo que queda y su vencimiento.
Todos los datos de una factura
CampoObligatorioDetalle
tipoSí31, 32, 33, 34, 44, 45 o 46.
comprador.nombreSíRazón social o nombre.
comprador.rncSegún el tipoObligatorio en E31, E33, E44 y E45, en E34 sobre una E31, y en E32 de RD$250,000 o más.
lineasSíDe 1 a 50 líneas, con descripcion, cantidad y precio sin ITBIS.
lineas[].itbisNo18, 16, 0 o "exento". Si no se envía, 18.
monedaNoPor ejemplo USD. Si no se envía, pesos.
tasa_cambioCon otra monedaTasa a pesos, por ejemplo 58.75. La respuesta da monto_total e itbis en pesos.
ncf_modificado, codigo_modificacion, razon_modificacionEn E33 y E34Nuvem toma la fecha del e-CF original.
Todos los códigos de respuesta
HTTPCódigoCuándo
200—Consulta correcta, o repetición de un pedido (encabezado Idempotent-Replay: true).
201—Factura aceptada.
202—Factura en proceso.
400IDEMPOTENCY_KEY, JSON_INVALIDOFalta la llave (8 a 64 letras, números, - o _) o el cuerpo no es JSON.
401TOKEN_INVALIDOToken ausente, errado o revocado.
402CUOTA_AGOTADASe acabó el plan.
404NO_ENCONTRADOEsa factura o esa ruta no existen.
405METODOMétodo no permitido.
409ERP_CONECTADO, EMPRESA_NO_LISTA, EMPRESA_INCOMPLETA, SECUENCIASLa empresa no puede emitir hasta resolverlo.
409EN_CURSO, IDEMPOTENCY_CONFLICTOSe está enviando, o esa llave ya se usó con otros datos.
409NO_DISPONIBLEEse XML o PDF no existe.
413CUERPO_GRANDEEl cuerpo pasa de 256 KB.
422VALIDACION, ORIGINAL_NO_ENCONTRADODatos inválidos. No se envió nada a la DGII.
422—Con estado: "rechazada": la DGII la rechazó y la llave ya se usó.
429LIMITE, DEMASIADOS_INTENTOSEspere lo que diga Retry-After.
500ERROR_INTERNORepita con la misma llave a los 10 minutos.
Límites

Son de velocidad, por minuto y por token. No hay límite diario. Cada factura cuenta en el cupo mensual de su plan como una hecha a mano.

PlanFacturas por minutoConsultas por minuto
Gratis e Inicio30120
Pro60240
Pro+120480
Empresa3001200
Partner / API6002400
Avisos automáticos

Nuvem hace POST a la dirección que guarde en Conectar su sistema cuando la DGII contesta un e-CF emitido por la API. Solo https. Responda cualquier 2xx en menos de 10 segundos.

EventoCuándo
ecf.aceptadoLa DGII lo aceptó.
ecf.aceptado_condicionalLo aceptó con observaciones.
ecf.rechazadoLo rechazó. El motivo va en ecf.mensaje.
pruebaLo envió usted con «Enviar aviso de prueba». ecf va vacío.
{
  "id": "av_6f1c…",
  "evento": "ecf.aceptado",
  "creado_en": "2026-11-05T20:00:00.000Z",
  "ambiente": "ecf",
  "ecf": { "encf": "E310000000123", "estado": "aceptada", "monto_total": "1180.00", "…": "igual que GET /ecf/{encf}" }
}

Con "ambiente": "demo" la factura es de la empresa demo y no es real.

Compruebe que viene de Nuvem. El encabezado X-Nuvem-Firma trae t=segundos,v1=firma. La firma es HMAC-SHA256, en hexadecimal, de segundos.cuerpo con su secreto. Use el cuerpo tal como llegó.

const crypto = require("crypto");

function avisoValido(cuerpo, encabezado, secreto) {
  const [t, v1] = encabezado.split(",").map((p) => p.split("=")[1]);
  const esperada = crypto.createHmac("sha256", secreto).update(t + "." + cuerpo).digest("hex");
  const reciente = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return reciente && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperada));
}

Reintentos. Si no responde 2xx, Nuvem reintenta a los 5, 15, 60, 240, 720, 1440 minutos. Un mismo aviso puede llegar dos veces: use id o X-Nuvem-Entrega para no procesarlo doble.

¿Se trabó? Escríbanos desde Soporte en Nuvem FE.