Saltar al contenido
firmo
Docs / Importar desde Excel

Importar desde Excel

Emite en lote con la plantilla de Excel, un CSV o Google Sheets: vista previa validada, emisión y resultados (/v1/imports).

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/imports de 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

ColumnaObligatoriaQué va
referenciaSíTu identificador, único en el archivo. Firmo lo guarda como idExterno: una referencia ya emitida no se vuelve a emitir.
tipoSí31, 32, 33, 34, 41, 43, 44, 45, 46 o 47.
fecha_emisionNoAAAA-MM-DD, DD/MM/AAAA o fecha de Excel. Vacío = hoy (hora de RD). No puede ser futura.
rnc_compradorSegún el tipoRNC (9) o cédula (11), sin guiones. Obligatorio en 31, 41 y 45. En 46 y 47 acepta un identificador extranjero.
razon_social_compradorSegún el tipoObligatoria en 31 y 45.
correo_compradorNoCorreo del comprador.
tipo_pagoNocontado (por defecto), credito o gratuito.
fecha_limite_pagoSi es créditoObligatoria con tipo_pago credito (salvo en 32).
forma_pagoNoefectivo, transferencia, tarjeta, credito, bonos, permuta, nota_credito u otras. Se registra por el total.
encf_modificadoEn 33 y 34e-NCF de la factura que modificas.
fecha_modificadoEn 33 y 34Fecha de esa factura.
codigo_modificacionEn 33 y 341 a 5.
enviar_correoNosi o no (por defecto no).
total_esperadoNoSi lo llenas, Firmo verifica que el total calculado (con ITBIS) cuadre.

Hoja Detalle

ColumnaObligatoriaQué va
referenciaSíLa referencia de su factura.
descripcionSíHasta 80 caracteres.
cantidadSíMayor que 0.
precio_unitarioEste o precio_con_itbisPrecio por unidad SIN ITBIS (Firmo calcula el impuesto).
precio_con_itbisEste o precio_unitarioPrecio por unidad CON el ITBIS incluido (el precio final al cliente). Con esta columna, el descuento de la fila también va con ITBIS.
itbisNo18 (por defecto), 16, 0 o exento.
descuentoNoMonto de descuento de la línea.
tipoNobien (por defecto) o servicio. En CSV se llama tipo_item.
codigoNoTu código del producto.
Precio sin ITBIS o con ITBIS: cada fila de Detalle lleva 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.

Límites: 5 MB y 2,000 facturas por archivo. Para más, divide el archivo.

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).

texto
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;bien

API#

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.

bash
curl -X POST https://api.firmo.do/v1/imports \
  -H "Authorization: Bearer $FIRMO_API_KEY" \
  -F "archivo=@facturas-noviembre.xlsx"
json
{
  "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.

bash
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

  1. Abre una hoja nueva. Entra a sheets.new (o abre la hoja donde quieres facturar).
  2. Abre Apps Script. En el menú de la hoja, pulsa Extensiones → Apps Script. Se abre el editor en una pestaña nueva.
  3. Pega el código de Firmo. Verás un archivo llamado Código.gs con 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+V en Mac, Ctrl+V en Windows). Guarda con Cmd+S o Ctrl+S.
    Abrir Codigo.gsDescargar
  4. 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 <>), abre appsscript.json, borra todo su contenido y pega el nuestro. Guarda.
    Abrir appsscript.jsonDescargar
  5. 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.
  6. 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 con sk_live_ es de producción: las facturas son reales. Empieza siempre con la de pruebas.
  7. 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.

  8. 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.

  1. Con el script instalado y tu API key configurada, usa Firmo → Crear hoja Factura. Si ya existe la hoja, te pregunta antes de reemplazarla.
  2. 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.
  3. 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.
  4. 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.
  5. 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.