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.
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
}totales la suma delineTotal, redondeada a dos decimales. No existensubtotal,taxTotalnidiscounten v1.signedTotalpermite que el libro de ventas sume sin ambigüedad: una nota de crédito resta.totalInWordsse 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
printInvoiceEnabledse 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: generael-vendedor-<vista>-<fecha>.csvcon 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
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte