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. Su sistemamanda la venta
- 2. Nuvemhace y firma la factura
- 3. La DGIIla revisa
- 4. Ustedrecibe el número, el QR y el PDF
Empiece en 4 pasos
Los pasos 1 a 3 no necesitan programador. Se hacen con botones, dentro de Nuvem FE.
- 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
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
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
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 }
]
}| Dato | Qué poner |
|---|---|
tipo | 31 crédito fiscal, 32 consumo, 44 régimen especial, 45 gubernamental, 46 exportación. |
comprador | Nombre 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. |
lineas | Lo que se vendió: descripcion, cantidad y precio. |
El número de la factura lo pone Nuvem. Con el pedido van dos encabezados:
| Encabezado | Qué poner |
|---|---|
Authorization | Bearer seguido de su token. |
Idempotency-Key | Un 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);import os, requests
respuesta = requests.post(
"https://ecf.nuvem.com.do/api/v1/ecf",
headers={
"Authorization": "Bearer " + os.environ["NUVEM_TOKEN"],
"Idempotency-Key": f"venta-{venta_id}",
},
json={
"tipo": "31",
"comprador": {"rnc": "101010101", "nombre": "Cliente Ejemplo SRL"},
"lineas": [{"descripcion": "Servicio de mantenimiento", "cantidad": 1, "precio": 15000}],
},
)
factura = respuesta.json()
print(factura["encf"], factura["estado"])$datos = [
"tipo" => "31",
"comprador" => ["rnc" => "101010101", "nombre" => "Cliente Ejemplo SRL"],
"lineas" => [["descripcion" => "Servicio de mantenimiento", "cantidad" => 1, "precio" => 15000]],
];
$c = curl_init("https://ecf.nuvem.com.do/api/v1/ecf");
curl_setopt_array($c, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("NUVEM_TOKEN"),
"Idempotency-Key: venta-" . $ventaId,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($datos),
]);
$factura = json_decode(curl_exec($c), true);
echo $factura["encf"] . " " . $factura["estado"];curl -X POST https://ecf.nuvem.com.do/api/v1/ecf \
-H "Authorization: Bearer $NUVEM_TOKEN" \
-H "Idempotency-Key: venta-10482" \
-H "Content-Type: application/json" \
-d '{"tipo":"31","comprador":{"rnc":"101010101","nombre":"Cliente Ejemplo SRL"},"lineas":[{"descripcion":"Servicio de mantenimiento","cantidad":1,"precio":15000}]}'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:
| Estado | Qué significa | Qué hacer |
|---|---|---|
aceptada | La DGII la aprobó. | Entregue la factura. |
aceptada_condicional | La DGII la aprobó con observaciones. | Lea mensaje y corrija lo que diga. |
en_proceso | La DGII todavía no contesta. | Pregunte otra vez cada 30 a 60 segundos con GET /api/v1/ecf/{encf}. |
rechazada | La 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
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
Un
Idempotency-Keypor ventaSi 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
El precio va sin ITBIS
Nuvem suma el ITBIS. Si no dice nada, usa 18%. Para otra tasa, agregue
"itbis": 16,0o"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 dice | Quiere decir | Qué hacer |
|---|---|---|
TOKEN_INVALIDO | El token está mal copiado o se revocó. | Cópielo otra vez o cree uno nuevo. |
VALIDACION | Falta un dato o está mal. No se envió nada a la DGII. | Corrija lo que diga mensaje y repita. |
CUOTA_AGOTADA | Se acabaron las facturas de su plan. | Cambie de plan en Nuvem FE. |
SECUENCIAS | Faltan números autorizados o vencieron. | Revise Secuencias en Nuvem FE. |
ERP_CONECTADO | Esa 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_CURSO | Esa venta se está enviando. | Espere unos segundos y repita con el mismo código. |
ERROR_INTERNO | Nuvem 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.
| Ruta | Qué hace |
|---|---|
POST /ecf | Hace 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 /ecf | Lista: desde y hasta (AAAA-MM-DD), tipo, limite (hasta 100) y pagina. Responde datos, pagina, limite y total. |
GET /ecf/{encf}/xml | El XML firmado. |
GET /ecf/{encf}/pdf | El PDF con el QR. Solo de facturas aceptadas. |
GET /empresa | RNC, razón social, ambiente, si puede emitir, y las secuencias con lo que queda y su vencimiento. |
Todos los datos de una factura
| Campo | Obligatorio | Detalle |
|---|---|---|
tipo | Sí | 31, 32, 33, 34, 44, 45 o 46. |
comprador.nombre | Sí | Razón social o nombre. |
comprador.rnc | Según el tipo | Obligatorio en E31, E33, E44 y E45, en E34 sobre una E31, y en E32 de RD$250,000 o más. |
lineas | Sí | De 1 a 50 líneas, con descripcion, cantidad y precio sin ITBIS. |
lineas[].itbis | No | 18, 16, 0 o "exento". Si no se envía, 18. |
moneda | No | Por ejemplo USD. Si no se envía, pesos. |
tasa_cambio | Con otra moneda | Tasa a pesos, por ejemplo 58.75. La respuesta da monto_total e itbis en pesos. |
ncf_modificado, codigo_modificacion, razon_modificacion | En E33 y E34 | Nuvem toma la fecha del e-CF original. |
Todos los códigos de respuesta
| HTTP | Código | Cuándo |
|---|---|---|
| 200 | — | Consulta correcta, o repetición de un pedido (encabezado Idempotent-Replay: true). |
| 201 | — | Factura aceptada. |
| 202 | — | Factura en proceso. |
| 400 | IDEMPOTENCY_KEY, JSON_INVALIDO | Falta la llave (8 a 64 letras, números, - o _) o el cuerpo no es JSON. |
| 401 | TOKEN_INVALIDO | Token ausente, errado o revocado. |
| 402 | CUOTA_AGOTADA | Se acabó el plan. |
| 404 | NO_ENCONTRADO | Esa factura o esa ruta no existen. |
| 405 | METODO | Método no permitido. |
| 409 | ERP_CONECTADO, EMPRESA_NO_LISTA, EMPRESA_INCOMPLETA, SECUENCIAS | La empresa no puede emitir hasta resolverlo. |
| 409 | EN_CURSO, IDEMPOTENCY_CONFLICTO | Se está enviando, o esa llave ya se usó con otros datos. |
| 409 | NO_DISPONIBLE | Ese XML o PDF no existe. |
| 413 | CUERPO_GRANDE | El cuerpo pasa de 256 KB. |
| 422 | VALIDACION, ORIGINAL_NO_ENCONTRADO | Datos inválidos. No se envió nada a la DGII. |
| 422 | — | Con estado: "rechazada": la DGII la rechazó y la llave ya se usó. |
| 429 | LIMITE, DEMASIADOS_INTENTOS | Espere lo que diga Retry-After. |
| 500 | ERROR_INTERNO | Repita 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.
| Plan | Facturas por minuto | Consultas por minuto |
|---|---|---|
| Gratis e Inicio | 30 | 120 |
| Pro | 60 | 240 |
| Pro+ | 120 | 480 |
| Empresa | 300 | 1200 |
| Partner / API | 600 | 2400 |
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.
| Evento | Cuándo |
|---|---|
ecf.aceptado | La DGII lo aceptó. |
ecf.aceptado_condicional | Lo aceptó con observaciones. |
ecf.rechazado | Lo rechazó. El motivo va en ecf.mensaje. |
prueba | Lo 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.