ElVendedorDocs

Facturación fiscal

Contrato de factura v1: campos, numeración por serie, totales sin impuestos, ciclo de vida del documento y configuración en el escritorio.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

La facturación fiscal se emite solo desde el escritorio, y el contrato de factura v1 es su fuente de verdad. Al terminar sabrás configurarla, explicar qué contiene el documento y qué no debes prometer.

Alcance del contrato v1

Documento con numeración consecutiva por serie e identificación fiscal. No discrimina impuestos ni descuentos: el total es Σ (precio unitario × cantidad), exactamente el total de la venta. Quedan fuera de alcance el timbrado, el CFDI, la ONAT o cualquier facturación electrónica certificada: el producto complementa, no sustituye.

Identidad del documento

Campo Regla
contractVersion / doctype 1 y invoice (discriminante de la base local).
id invoice:{serie}:{número con relleno}; es también el _id local.
documentType invoice o credit_note.
series 1–24 caracteres, ^[A-Z0-9](?:[A-Z0-9-]{0,22}[A-Z0-9])?$, en mayúsculas.
number Entero ≥ 1, consecutivo dentro de la serie.
numberPadding 1–12; por defecto 8.
displayNumber {serie}-{número con relleno}.
issuedAt / status ISO 8601 en UTC; issued o voided.
originalInvoiceId Obligatorio en una nota de crédito; null en una factura.
hash SHA-256 de la emisión (ver más abajo).

La numeración es local (numberSource: local). La serie se deriva del negocio y del punto de venta: <prefijo negocio>-<código POS>, por ejemplo BODEGAC-CAPIRO. Dos cajas nunca comparten serie y por eso pueden numerar sin conexión sin coordinarse. Límites: 24 para la serie, 6 para el prefijo, 8 para el código de POS y 500 líneas por documento.

Emisor, receptor y totales

issuer y customer son copias congeladas del momento de emitir: si el negocio cambia de dirección o el cliente de NIT, las facturas ya emitidas conservan lo que decían. El emisor exige name y admite taxId, address, phone, email y regime; el receptor lleva contactId, name, taxId, idCard, address y phone, o null para consumidor final.

"lines": [
  { "productId": "prod_123", "productTitle": "Arroz 1 kg",
    "quantity": 3, "unitPrice": 260, "lineTotal": 780, "unitSymbol": "unid" }
],
"totals": {
  "total": 780, "signedTotal": 780,
  "totalInWords": "SETECIENTOS OCHENTA PESOS CON 00/100",
  "lineCount": 1, "quantityTotal": 3
}
  • total es la suma de lineTotal, redondeada a dos decimales. No existen subtotal, taxTotal ni discount en v1.
  • signedTotal permite que el libro de ventas sume sin ambigüedad: una nota de crédito resta.
  • totalInWords se forma con <LETRAS> <MONEDA> CON <CC>/100, con los centavos a dos dígitos.

El hash cubre contractVersion, id, saleId, series, number, numberPadding, numberSource, documentType, originalInvoiceId, issuedAt, issuer, customer, currency, lines, totals, payment y createdBy. Quedan fuera status, los datos de anulación, reprintCount y las marcas de sincronización: anular y reimprimir no cambian la huella; cambiar el total o los datos del emisor sí.

Ciclo de vida

Operación Efecto ¿Cambia el hash?
Emitir Crea el documento y reserva el número. — (lo genera)
Reimprimir Suma reprintCount y marca COPIA. No
Anular status = voided con motivo, usuario y fecha. No
Nota de crédito Documento nuevo, con su propio número, que referencia al original. — (huella propia)

Un documento emitido no se edita ni se borra. Todo impreso o exportado lleva la leyenda LEGAL_NOTICE: «Documento de venta. No sustituye la facturación electrónica cuando la regulación la exija». El negocio puede añadir un pie propio (footer).

Relación con la venta del POS

createInvoiceFromSale es idempotente: si ya hay factura para esa venta, devuelve la existente en lugar de duplicarla. Un número no se reutiliza nunca; si un fallo entre la reserva y la emisión deja un hueco, se documenta y el número no se recicla. La factura conserva saleId y la venta guarda su invoiceNumber para el ticket y las devoluciones.

Al sincronizar, el backend rechaza un duplicado (business_id, series, number) con sync_invoice_number_conflict (retryable: false).

Configuración inicial

El escritorio lee las preferencias con getFiscalSettings() y las guarda con saveFiscalSettings(): razón social (fiscalName), identificación (fiscalTaxId), dirección y teléfono (fiscalAddress, fiscalPhone), correo (fiscalEmail), régimen (fiscalRegime), prefijo de serie (invoiceSeriesPrefix), relleno (invoiceNumberPadding) y pie (invoiceFooter).

Pendiente de validación

  • En el repositorio del escritorio esas funciones existen en pouchdb-store.js, pero ninguna vista las llama todavía: confirma en la versión que entregues qué pantalla las edita antes de decirle al cliente que «se configura en Ajustes».
  • No hay una vista de listado de facturas confirmada: la exportación CSV es por vista, así que verifica qué pantalla las expone antes de prometer un export fiscal.
  • La preferencia printInvoiceEnabled se guarda, pero no tiene consumidor en el repositorio: confirma si el cobro imprime automáticamente.
  • Los requisitos legales (timbrado, formato, plazos de conservación, autorización) los confirma el contador del cliente. El producto no los emite.

Exportación desde escritorio

  • La impresión del ticket incluye el número de factura cuando la venta lo tiene.
  • La exportación a CSV (exportRowsToCsv) está disponible por vista: genera el-vendedor-<vista>-<fecha>.csv con las columnas de esa pantalla.
  • No hay exportación PDF específica de facturas documentada: usa la impresión del documento o el export de la vista.

Errores frecuentes

Síntoma Causa Solución
«Número repetido» al sincronizar Misma serie y número en dos equipos. Corrige el número en el equipo; no reescribas la factura en el backend.
«issuer.name es obligatorio» Datos fiscales del negocio vacíos. Carga la razón social antes de emitir.
Serie rechazada Caracteres fuera del patrón o longitud > 24. Usa mayúsculas, números y guiones internos.
La factura no aparece en el móvil invoices es solo de escritorio y no se anuncia en su matriz. Es el comportamiento esperado.
Reimpresión con número nuevo Se emitió otra factura en lugar de reimprimir. Reimprime el documento existente: debe salir como COPIA.

Siguiente paso

↑↓ para navegar · Enter para abrir · Esc para cerrar