ElVendedorDocs

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.

Para implementadores6 min de lecturaActualizado el 16 de noviembre de 2026

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 el total de 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:

  1. 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.
  2. Una venta no se factura dos veces. La emisión es idempotente: si ya hay factura para esa venta, devuelve la existente.
  3. El número no se renumera al sincronizar. El backend rechaza el duplicado (business_id, series, number) con sync_invoice_number_conflict.
  4. 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 existen subtotal, taxTotal ni discount; si se añaden será de forma aditiva, subiendo contractVersion.
  • totalInWords se forma como <LETRAS> <MONEDA> CON <CC>/100.
  • signedTotal permite 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 su totals.total coincide 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 = invoices y 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.

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