Contrato de factura v1
Campos, numeración, totales, huella y ciclo de vida del documento de facturación v1 compartido por el escritorio y el backend.
La factura es el único documento con numeración fiscal. La emite el escritorio, la deduplica el backend y el móvil no la consume. Aquí están sus campos, su numeración y lo que no se puede hacer con un documento emitido.
Alcance del contrato
- Versión
1(INVOICE_CONTRACT_VERSION) con esquema JSON en el escritorio. - Documento con numeración consecutiva por serie e identificación fiscal.
- No discrimina impuestos ni descuentos: el total es
Σ (precio unitario × cantidad), exactamente eltotalde la venta. - Fuera de alcance: timbrado, CFDI, ONAT o cualquier facturación electrónica certificada. El producto complementa esa obligación, no la sustituye.
- Todo documento impreso declara que no sustituye a la facturación electrónica cuando la regulación la exija.
Identidad del documento
| Campo | Tipo | Reglas |
|---|---|---|
contractVersion |
entero | 1 |
doctype |
string | Siempre invoice; es el discriminante de la base local |
id |
string | invoice:{serie}:{número con relleno}; también es el _id local |
documentType |
enum | invoice o credit_note |
series |
string | 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 |
entero | 1–12; por defecto 8 |
displayNumber |
string | {serie}-{número con relleno} |
numberSource |
enum | local o server_block; en v1 siempre local |
issuedAt |
ISO 8601 | Momento de emisión en UTC |
status |
enum | issued o voided |
originalInvoiceId |
string o null |
Obligatorio en una nota de crédito; null en una factura |
saleId |
string | Venta de origen; obligatorio |
currency |
string | ISO o código del negocio (CUP) |
hash |
string | SHA-256 de la emisión (ver más abajo) |
Series y numeración
La serie es la unidad de numeración y se deriva del negocio y del POS:
<prefijo negocio>-<código POS>, por ejemplo BODEGAC-CAPIRO. Dos cajas nunca
comparten serie y por eso pueden numerar sin conexión sin coordinarse.
Reglas:
- Un número no se reutiliza nunca. Si la emisión falla y deja un hueco, el hueco se documenta; el número no se recicla.
- Una venta no se factura dos veces. La emisión es idempotente: si ya hay factura para esa venta, devuelve la existente.
- El número no se renumera al sincronizar. El backend rechaza el duplicado
(business_id, series, number)consync_invoice_number_conflict. - El documento es inmutable y no se borra. Anular y emitir una nota de crédito son estados y documentos nuevos; reimprimir lee el snapshot.
Emisor y receptor
issuer es el snapshot fiscal del negocio al emitir: name obligatorio y
taxId, address, phone, email y regime opcionales. customer es el
snapshot del receptor o null para consumidor final; si existe, name es
obligatorio y contactId, taxId, idCard, address y phone opcionales.
Ambos son copias congeladas: una factura ya emitida conserva los datos que
tenían el negocio y el cliente en ese momento.
Líneas y totales
"lines": [
{
"productId": "prod_123", // string, obligatorio
"productTitle": "Arroz 1 kg", // string, obligatorio
"quantity": 3, // número > 0
"unitPrice": 260, // número >= 0
"lineTotal": 780, // = roundMoney(quantity * unitPrice)
"unitSymbol": "unid" // string | null
}
],
"totals": {
"total": 780, // = Σ lineTotal, redondeado a 2 decimales
"signedTotal": 780, // total, o -total en una nota de crédito
"totalInWords": "SETECIENTOS OCHENTA PESOS CON 00/100",
"lineCount": 1,
"quantityTotal": 3
}- Sin impuestos ni descuentos:
total = Σ lineTotal. No existensubtotal,taxTotalnidiscount; si se añaden será de forma aditiva, subiendocontractVersion. totalInWordsse forma como<LETRAS> <MONEDA> CON <CC>/100.signedTotalpermite sumar el libro de ventas sin ambigüedad: una nota de crédito resta.
Pago
payment copia el desglose: method, breakdown,
amountReceived, changeAmount y creditBalance.
Huella (hash)
hash es el SHA-256 hexadecimal de la serialización canónica del payload de
emisión: identidad del documento, saleId, issuedAt, issuer, customer,
currency, lines, totals, payment y createdBy.
Queda fuera todo lo que es estado: status, voidedAt, voidedBy,
voidReason, reprintCount, _rev, _id y marcas de sincronización. Por eso
anular o reimprimir no cambian el hash, pero cambiar el total, una línea 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) |
Una reimpresión se marca como COPIA sin número nuevo.
Relación con ventas y compras
- Cada factura nace de una venta (
saleId) y sutotals.totalcoincide con el de esa venta: la factura referencia, no sustituye al registro de venta. - Compras y gastos no generan factura en este contrato.
- El escritorio la empuja con
entity_type = invoicesy el backend la sirve en el pull; el móvil declara no aplicarla porque no emite ni reimprime.
Ejemplo completo
{
"contractVersion": 1,
"doctype": "invoice",
"id": "invoice:BODEGAC-CAPIRO:00000001",
"documentType": "invoice",
"series": "BODEGAC-CAPIRO",
"number": 1,
"numberPadding": 8,
"displayNumber": "BODEGAC-CAPIRO-00000001",
"numberSource": "local",
"issuedAt": "2026-09-28T16:20:00.000Z",
"status": "issued",
"originalInvoiceId": null,
"saleId": "sale:1790614001068:9t2bkzop",
"issuer": {
"name": "Bodega El Capiro",
"taxId": "12345678901",
"address": "Calle 12 #45, Camaguey",
"phone": "+53 5555 0000",
"email": null,
"regime": "TCP"
},
"customer": {
"contactId": "contact:1790062595621:cnzugfvn",
"name": "Esperanzejo",
"taxId": null,
"idCard": "12345678901",
"address": null,
"phone": "55443322"
},
"currency": "CUP",
"lines": [
{
"productId": "prod_arroz",
"productTitle": "Arroz especial 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
},
"payment": {
"method": "cash",
"breakdown": [{ "method": "cash", "amount": 780, "amountReceived": 1000, "change": 220 }],
"amountReceived": 1000,
"changeAmount": 220,
"creditBalance": null
},
"hash": "9f2c…",
"reprintCount": 0,
"createdAt": "2026-09-28T16:20:00.000Z",
"createdBy": { "name": "Dueno", "role": "owner" }
}Validaciones y errores
El validador devuelve una lista de problemas; estas son las comprobaciones:
| Comprobación | Mensaje esperado |
|---|---|
contractVersion distinto de 1 |
Versión de contrato no soportada |
doctype o documentType fuera de rango |
Documento inválido |
series fuera del patrón |
Serie inválida |
number no entero o menor que 1 |
Número inválido |
numberPadding fuera de 1–12 |
Relleno inválido |
id o displayNumber que no derivan de serie y número |
Documento incoherente |
Nota de crédito sin originalInvoiceId, o factura con uno |
Referencia inválida |
issuedAt no parseable, currency o issuer.name vacíos |
Campo obligatorio ausente |
En el servidor, la unicidad de (business_id, series, number) cierra el
círculo: un número repetido se rechaza con sync_invoice_number_conflict
(retryable: false) y el cliente muestra la causa en lugar de renumerar.
Impuestos y descuentos
Que v1 no los discrimine es una decisión de alcance, no un olvido. Si necesitas
desglose fiscal, la factura v1 no lo cubre: hace falta una versión aditiva del
contrato. No añadas taxTotal ni subtotal.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte