Disponible
Emite cientos de e-CF a la vez desde una hoja de cálculo, sin programar. Firmo lee todo el archivo, lo valida con las mismas reglas de POST /v1/ecf y te muestra los errores por hoja, fila y columna. No emite nada hasta que lo confirmas. Tres formas de usarlo:
- Portal: Facturas → Importar desde Excel.
- API: las rutas
/v1/importsde esta página. - Google Sheets: la misma plantilla con un botón Emitir (ver más abajo).
La plantilla#
Descarga firmo-plantilla-facturas.xlsx (o con GET /v1/imports/template). Tiene tres hojas: Facturas (una fila por factura), Detalle (una fila por ítem, unida por la referencia) e Instrucciones (un ejemplo con datos ficticios). Las columnas tipo, itbis y tipo_pago tienen listas desplegables.
Hoja Facturas
| Columna | Obligatoria | Qué va |
|---|---|---|
referencia | Sí | Tu identificador, único en el archivo. Firmo lo guarda como idExterno: una referencia ya emitida no se vuelve a emitir. |
tipo | Sí | 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47. |
fecha_emision | No | AAAA-MM-DD, DD/MM/AAAA o fecha de Excel. Vacío = hoy (hora de RD). No puede ser futura. |
rnc_comprador | Según el tipo | RNC (9) o cédula (11), sin guiones. Obligatorio en 31, 41 y 45. En 46 y 47 acepta un identificador extranjero. |
razon_social_comprador | Según el tipo | Obligatoria en 31 y 45. |
correo_comprador | No | Correo del comprador. |
tipo_pago | No | contado (por defecto), credito o gratuito. |
fecha_limite_pago | Si es crédito | Obligatoria con tipo_pago credito (salvo en 32). |
forma_pago | No | efectivo, transferencia, tarjeta, credito, bonos, permuta, nota_credito u otras. Se registra por el total. |
encf_modificado | En 33 y 34 | e-NCF de la factura que modificas. |
fecha_modificado | En 33 y 34 | Fecha de esa factura. |
codigo_modificacion | En 33 y 34 | 1 a 5. |
enviar_correo | No | si o no (por defecto no). |
total_esperado | No | Si lo llenas, Firmo verifica que el total calculado (con ITBIS) cuadre. |
Hoja Detalle
| Columna | Obligatoria | Qué va |
|---|---|---|
referencia | Sí | La referencia de su factura. |
descripcion | Sí | Hasta 80 caracteres. |
cantidad | Sí | Mayor que 0. |
precio_unitario | Este o precio_con_itbis | Precio por unidad SIN ITBIS (Firmo calcula el impuesto). |
precio_con_itbis | Este o precio_unitario | Precio por unidad CON el ITBIS incluido (el precio final al cliente). Con esta columna, el descuento de la fila también va con ITBIS. |
itbis | No | 18 (por defecto), 16, 0 o exento. |
descuento | No | Monto de descuento de la línea. |
tipo | No | bien (por defecto) o servicio. En CSV se llama tipo_item. |
codigo | No | Tu código del producto. |
precio_unitario (sin ITBIS) o precio_con_itbis (el precio final, con el ITBIS incluido), nunca las dos ni ninguna; puedes mezclarlas fila por fila. Con precio_con_itbis, Firmo separa el ITBIS de la tasa de la fila (el exento y el 0% no cambian) y el descuento de esa fila también se entiende con ITBIS. El e-CF siempre sale con precios sin ITBIS, así que Firmo elige el precio de 2 decimales que deje la línea más cerca de lo que escribiste: cerca de 1 de cada 6 totales no se puede formar exacto y queda 1 centavo por debajo (RD$100.00 con ITBIS sale RD$99.99). Si necesitas el total al centavo, usa precio_unitario. Los archivos de antes, sin la columna nueva, siguen funcionando igual.Además de las reglas de la DGII, Firmo revisa: referencias repetidas, ítems sin factura, facturas sin ítems, RNC de 9 u 11 dígitos, fechas reales y que el total cuadre.
Formato de factura (Excel)#
Si prefieres llenar una factura como la ves impresa (tus datos arriba, el cliente, las líneas y los totales), descarga firmo-factura.xlsx (o con GET /v1/imports/template?format=invoice). Úsalo para una factura con su detalle; la plantilla de arriba es para muchas facturas en lote. Al subir el archivo (portal o POST /v1/imports) Firmo detecta el formato solo y sigue el mismo flujo: vista previa, errores, emitir y resultados.
- Una factura por hoja. La hoja Factura trae: Referencia, Fecha, Tipo de comprobante (31, 32, 44 o 45), Condición (Contado o Crédito), Vence y Forma de pago; el bloque Facturar a (RNC o cédula, nombre o razón social, correo, teléfono y dirección); 25 líneas (descripción, código, Bien/Servicio, cantidad, precio unitario, ITBIS 18%, 16%, 0% o Exento, y descuento); y los totales con fórmulas. Los precios van sin ITBIS, salvo que elijas Sí en Precios incluyen ITBIS (la celda debajo de Forma de pago; por defecto No): con Sí, los precios y los descuentos de la hoja son precios finales y Firmo separa el ITBIS. Los datos de tu empresa arriba a la izquierda son solo visuales: Firmo usa los de tu cuenta.
- Varias facturas en un archivo: duplica la hoja (clic derecho en la pestaña → Mover o copiar → Crear una copia) y cambia la referencia y los datos de cada copia. Cada hoja es una factura. Las hojas sin llenar se ignoran.
- Cómo la lee Firmo: por los nombres definidos
FIRMO_F_*de la plantilla (también las copias que crea Excel con alcance de hoja) y, si faltan —por ejemplo, copiaste y pegaste el contenido en una hoja nueva—, por los rótulos («FACTURA», «FACTURAR A», «Referencia», «Descripción»…). No borres ni cambies esos rótulos. - Referencia obligatoria: viene prellenada con
FAC-0001. Debe ser distinta en cada hoja; si ya se emitió una factura con esa referencia, Firmo no la vuelve a emitir.
Las reglas son las de la hoja Factura de Google Sheets: RNC de 9 u 11 dígitos; el crédito fiscal (31) necesita RNC y nombre; al menos una línea; cantidad y precio mayores que 0; fecha real y no futura; a crédito, Vence igual o posterior a la fecha; correo con formato válido. Los errores dicen la hoja, la línea y la columna, por ejemplo Factura (2) · fila 19 · Línea 3 · Cant.. El Excel de resultados trae una fila por hoja con su e-NCF, estado y PDF.
Formato CSV#
Una sola tabla, una fila por ítem: las columnas de la hoja Facturas y, en la misma fila, las del ítem (descripcion, cantidad, precio_unitario o precio_con_itbis, itbis, descuento, tipo_item y codigo). Repite la referencia en cada ítem; los datos de la factura se toman de su primera fila (en las siguientes déjalos vacíos o iguales). Separador coma, punto y coma o tabulador; UTF-8 (también acepta el CSV de Excel en Windows).
referencia;tipo;rnc_comprador;razon_social_comprador;tipo_pago;descripcion;cantidad;precio_unitario;itbis;tipo_item
FAC-0101;31;101010101;Ferretería El Martillo SRL;contado;Cemento gris 42.5 kg;10;600;18;bien
FAC-0101;;;;;Transporte a obra;1;2000;18;servicio
FAC-0102;32;;;contado;Libro de recetas;1;800;exento;bienAPI#
1. Subir y validar (vista previa)
POST/v1/imports
multipart/form-data con archivo (.xlsx o .csv). Responde 201 con la vista previa en estado validado o con_errores. Un archivo sin la estructura de la plantilla responde 400.
curl -X POST https://api.firmo.do/v1/imports \
-H "Authorization: Bearer $FIRMO_API_KEY" \
-F "archivo=@facturas-noviembre.xlsx"{
"id": "6f1c2a8e-3b7d-4f0a-9c51-2d8e7b4a1f30",
"estado": "con_errores",
"resumen": { "facturas": 120, "items": 348, "montoTotal": 1845230.5, "totalItbis": 281475.18 },
"errores": [],
"filas": [
{
"referencia": "FAC-0101", "tipo": 31, "comprador": "Ferretería El Martillo SRL",
"montoTotal": 9440, "totalItbis": 1440, "errores": [], "resultado": null
},
{
"referencia": "FAC-0102", "tipo": 31, "comprador": null, "montoTotal": 0, "totalItbis": 0,
"errores": [
{ "hoja": "Facturas", "fila": 3, "columna": "rnc_comprador", "mensaje": "El tipo 31 requiere el RNC o la cédula del comprador" },
{ "hoja": "Detalle", "fila": 5, "columna": "precio_unitario", "mensaje": "«mil» no es un número" }
],
"resultado": null
}
]
}2. Emitir
POST/v1/imports/{id}/emit
Solo si está validado (si tiene errores responde 409). Encola la emisión y responde 202 en emitiendo. Cada factura se emite con idExterno = referencia: una referencia que ya existe no se duplica y queda como ya_emitida con su e-NCF. Repetir la llamada no vuelve a emitir; usa Idempotency-Key.
curl -X POST https://api.firmo.do/v1/imports/6f1c2a8e-3b7d-4f0a-9c51-2d8e7b4a1f30/emit \
-H "Authorization: Bearer $FIRMO_API_KEY" \
-H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-a6c5-1f0e2d3c4b5a"3. Progreso y resultados
GET/v1/imports/{id}
progreso cuenta las facturas con resultado; cada filas[].resultado trae encf, estado (el del e-CF, o ya_emitida / no_emitida), mensaje y pdf. La importación pasa a completado cuando todas tienen su resultado final.
GET/v1/imports/{id}/results
Excel con tu hoja Facturas original (o el CSV) más las columnas encf, estado, mensaje y pdf. Antes de emitir, marca las filas con errores.
GET/v1/imports
Historial de importaciones (?limit=&cursor=), las más recientes primero.
Google Sheets: instalación paso a paso#
Con un pequeño script, tu hoja de Google Sheets tiene un menú Firmo para emitir e-CF sin salir de ella. Se instala una sola vez, en unos 5 minutos, y no necesitas saber programar: solo copiar y pegar. Necesitas una cuenta de Google y tu API key de Firmo (en el portal, Desarrolladores).
Instalar el script
- Abre una hoja nueva. Entra a sheets.new (o abre la hoja donde quieres facturar).
- Abre Apps Script. En el menú de la hoja, pulsa Extensiones → Apps Script. Se abre el editor en una pestaña nueva.
- Pega el código de Firmo. Verás un archivo llamado
Código.gscon unas líneas de ejemplo. Selecciona todo y bórralo. Luego pulsa el botón de abajo para copiar nuestro código y pégalo en ese archivo (Cmd+Ven Mac,Ctrl+Ven Windows). Guarda conCmd+SoCtrl+S. - Agrega los permisos del script. A la izquierda del editor pulsa el engranaje ⚙️ Configuración del proyecto y marca Mostrar el archivo de manifiesto «appsscript.json» en el editor. Vuelve al editor (el icono
<>), abreappsscript.json, borra todo su contenido y pega el nuestro. Guarda. - Vuelve a la hoja y recárgala (F5 o Cmd/Ctrl+R). En la barra de menús, junto a Ayuda, aparece Firmo. Puede tardar unos segundos.
- Pon tu API key. Pulsa Firmo → Configurar API key y pega tu llave (portal → Desarrolladores). Una llave que empieza con
sk_test_es de pruebas: el simulador responde como la DGII y no llega nada a ella. Una que empieza consk_live_es de producción: las facturas son reales. Empieza siempre con la de pruebas. - Da los permisos (solo la primera vez). Google te los pide al usar un comando de Firmo por primera vez. Elige tu cuenta y revisa que son tres cosas: ver y editar esta hoja (para leer tus facturas y escribir el e-NCF y el estado), conectarse a Firmo (para enviar la factura) y guardar los PDF en tu Drive (solo los archivos que el propio script crea, en la carpeta «Firmo · Facturas e-CF»).
Es normal que Google diga «Google no ha verificado esta app»: pasa con cualquier script que pegas tú mismo, y este corre únicamente dentro de tu hoja. Pulsa Configuración avanzada, luego Ir a … (no seguro) y por último Permitir. Después vuelve a pulsar el comando que habías elegido.
- Factura. Pulsa Firmo → Crear hoja Factura, llena los datos y pulsa Generar e-CF. Para hacer otra, pulsa Nueva factura. Los detalles están en la siguiente sección.
Problemas comunes
- No aparece el menú Firmo: recarga la hoja y espera unos segundos. Si sigue sin salir, vuelve a Apps Script y revisa que guardaste el código (el icono del disquete) y que no quedó texto del ejemplo antes o después.
- Error de API key: vuelve a Firmo → Configurar API key y pégala completa, sin espacios. Verifica que sea de la empresa correcta y que no esté revocada en Desarrolladores.
- Los botones de la hoja no responden: usa el menú Firmo (hace lo mismo). Los botones de una hoja copiada necesitan que los asignes de nuevo; el menú siempre funciona.
- El PDF no abre: ábrelo con la misma cuenta de Google con la que instalaste el script; el archivo está en tu Drive, en la carpeta «Firmo · Facturas e-CF».
Emitir por lotes (hojas Facturas y Detalle)
Si prefieres llenar muchas facturas y emitirlas juntas, usa la misma plantilla de Excel: firmo-plantilla-facturas.xlsx. Súbela a Google Drive, ábrela con Google Sheets y elige Archivo → Guardar como Hojas de cálculo de Google. Instala el script en esa hoja con los pasos de arriba. Luego selecciona una fila y usa Emitir fila seleccionada, o Emitir todas las pendientes. Con Actualizar estados consultas las que quedaron en proceso.
Después de emitir, el script descarga el PDF con tu API key y lo guarda en tu Google Drive, en la carpeta «Firmo · Facturas e-CF» (un archivo {e-NCF}.pdf por factura); el enlace de la hoja abre ese archivo. Por eso el script pide el permiso de Drive limitado a los archivos que él mismo crea.
Cada fila se envía a POST /v1/ecf?wait=true con Idempotency-Key e idExterno iguales a la referencia, y el script escribe encf, estado, mensaje y pdf. Si algo falla, pinta la fila de rojo con el motivo.
Hoja Factura (una factura a la vez)
Si facturas una por una y estás acostumbrado a la factura clásica de Excel, el mismo script arma una hoja con ese formato: tu empresa arriba a la izquierda, el cuadro de la factura a la derecha, «Facturar a», la tabla de líneas y los totales abajo.
- Con el script instalado y tu API key configurada, usa Firmo → Crear hoja Factura. Si ya existe la hoja, te pregunta antes de reemplazarla.
- Escribe los datos de tu empresa (solo son para que la hoja se vea bien al imprimir). Elige el tipo de comprobante, la condición (contado o crédito, con su fecha de vencimiento) y la forma de pago, y llena los datos del cliente y las líneas. Los precios van sin ITBIS (esta hoja no tiene la opción de precios con ITBIS); el monto y los totales se calculan solos como vista previa.
- Pulsa el botón Generar e-CF (o Firmo → Generar e-CF de la hoja Factura). Te muestra el cliente, el total y si tu llave es de pruebas o de producción, y espera tu confirmación. Si hay datos que corregir, te dice cuáles y no envía nada.
- El resultado aparece en la propia hoja: e-NCF, estado, mensaje y enlace al PDF (guardado en tu Drive), en verde si se aceptó y en rojo si hubo un error. Si escribiste el correo del cliente, Firmo le envía el PDF.
- Para hacer otra, pulsa Nueva factura: limpia el cliente, las líneas y las notas, sugiere la siguiente referencia (FAC-0001, FAC-0002…) y deja los datos de tu empresa.
Cada factura emitida desde esta hoja se guarda también en las hojas Facturas y Detalle (si no existen, el script las crea), así que tienes historial y Actualizar estados sigue funcionando. Esas dos hojas siguen siendo la forma de emitir muchas facturas de una vez. La hoja Factura usa la misma referencia como Idempotency-Key e idExterno, y no te deja repetir una referencia que ya está en Facturas.
Si necesitas más de 20 líneas, inserta filas dentro de la tabla. Para imprimir o guardar en PDF, usa Archivo → Imprimir en vertical, tamaño carta y «Ajustar al ancho».
Cuida tu API key
La llave se guarda en las propiedades de tu usuario de Google, nunca en la hoja. Aun así, no compartas con permiso de edición una hoja en la que uses una llave de producción (sk_live_). Haz las pruebas con sk_test_: el simulador responde como la DGII y nada llega a ella.