Facturación

BillingManager es el manager del SDK responsable de todos los documentos relacionados con facturación: pagos, facturas (invoices), cajas registradoras (cash registers) y transacciones. Trabaja sobre la base de datos local (PouchDB) y, como todo documento del SDK, se replica hacia CouchDB cuando hay conectividad.

Extiende BaseManager<PaymentDocument>, por lo que su entidad por defecto es el documento de tipo payment. Los demás tipos (invoice, cash_register, transaction) se gestionan con métodos dedicados dentro del mismo manager.

Tipos de documento

BillingManager administra cuatro tipos de documento. Todos comparten el bloque metadata.syncStatus (pending | synced | error) y se aíslan por companyId (multi-tenant).

`payment`

Es el documento principal: registra un pago aplicado a un pedido. Campos relevantes (PaymentDocument):

orderId, amount, total, currency
method_id, method_code y status (estado del pago)
Descuentos: discount_percentage, discount_amount, discount_agreement (convenio en texto libre, por ejemplo Sodexo, Amipass, Edenred)
Propina: tip_amount, tip_percentage, tip_base_amount, tip_mode (post_discount | pre_discount)
Cliente: customerName (requerido), customerEmail, customerPhone
Asociaciones: cashFlowId, cashRegisterId, transactionId, waiterId
Datos de tarjeta: cardLastFourDigits, cardBrand (mastercard | visa | other), transactionReference
orderItems: ítems del pedido cubiertos por el pago

Los valores posibles de status (PaymentStatus) son: pending, processing, paid, completed, failed, refunded. Los valores de method_code (PaymentMethod) son: cash, card, transfer, mobile. Ver Métodos de pago.

`invoice`

Documento fiscal con número de folio. Campos relevantes (InvoiceDocument):

invoiceNumber, orderId, amount, tax, total, currency
Cliente: customerName, customerEmail, customerPhone, customerAddress (objeto con street, city, state, country, postalCode)
notes

`cash_register`

Representa una caja física del restaurante. Su number secuencial aparece en boletas y comprobantes. Una caja por compañía se marca isDefault: true (la usan las áreas sin caja asignada). Ver CashRegisterDocument para el esquema completo (incluye status, currentBalance, area_ids, cash_flow_id).

`transaction`

Movimiento contable de una caja (TransactionDocument): cashRegisterId, amount, currency y transactionType (deposit | withdrawal | sale | refund), con description opcional.

Emisión de documentos

Los métodos create* componen el documento, fijan version: 1 y metadata.syncStatus: 'pending', y delegan la persistencia en la base de datos local. La replicación al servidor ocurre después, de forma asíncrona.

const billing = core.getBillingManager();

// Emitir un pago
const payment = await billing.createPayment({
  orderId: 'order_123',
  amount: 9800,
  total: 9800,
  currency: 'CLP',
  method_id: 'pm_cash',
  method_code: 'cash',
  status: 'paid',
  orderItems: [],
  customerName: 'Consumidor final',
});

// Emitir una factura
const invoice = await billing.createInvoice({
  invoiceNumber: 'F-000123',
  orderId: 'order_123',
  amount: 8235,
  tax: 1565,
  total: 9800,
  currency: 'CLP',
  customerName: 'Empresa SpA',
});

Métodos principales

Todas las operaciones de actualización incrementan version. Los update* y delete* lanzan PaymentValidationError con un código específico (PAYMENT_NOT_FOUND, INVOICE_NOT_FOUND, CASH_REGISTER_NOT_FOUND, TRANSACTION_NOT_FOUND) si el documento no existe.

Pagos

Método	Descripción
`getAllPayments()`	Todos los pagos
`getPaymentById(id)`	Un pago por `_id` (o `null`)
`createPayment(data)`	Emite un pago
`updatePayment(id, data)`	Actualiza campos de un pago
`updatePaymentStatus(id, status)`	Cambia solo el `status` y `updatedAt`
`deletePayment(id)`	Elimina un pago
`getPaymentsByStatus(status)`	Filtra por `PaymentStatus`
`getPaymentsByMethod(method)`	Filtra por `method_code`
`getPaymentsByOrderId(orderId)`	Pagos de un pedido
`getPaymentsByCashFlow(cashFlowId)`	Pagos de un período de caja
`searchPayments(query)`	Busca por `orderId` o `customerName` (normalizado)

Facturas

Método	Descripción
`getAllInvoices()`	Todas las facturas
`getInvoiceById(id)`	Una factura por `_id`
`createInvoice(data)`	Emite una factura
`updateInvoice(id, data)`	Actualiza una factura
`deleteInvoice(id)`	Elimina una factura (requiere `_rev`)
`searchInvoices(query)`	Busca por `invoiceNumber` o `customerName`

Cajas registradoras

Método	Descripción
`getAllCashRegisters()`	Todas las cajas
`getCashRegisterById(id)`	Una caja por `_id`
`createCashRegister(data)`	`@deprecated` — usar `CashRegisterManager.create()`
`updateCashRegister(id, data)`	Actualiza una caja
`deleteCashRegister(id)`	Elimina una caja (requiere `_rev`)

Transacciones

Método	Descripción
`getAllTransactions()`	Todas las transacciones
`getTransactionById(id)`	Una transacción por `_id`
`createTransaction(data)`	Crea una transacción
`updateTransaction(id, data)`	Actualiza una transacción
`deleteTransaction(id)`	Elimina una transacción (requiere `_rev`)
`getTransactionsByCashRegister(cashRegisterId)`	Transacciones de una caja
`getTransactionsByDateRange(startDate, endDate)`	Filtra por rango de `createdAt`

Búsqueda

searchPayments y searchInvoices cargan todos los documentos del tipo correspondiente y filtran en memoria usando normalizeSearch (insensible a acentos y mayúsculas). Para volúmenes grandes considera filtrar antes con los métodos getPaymentsBy*.

Relacionado

Finanzas — panorama del área financiera
Métodos de pago — method_code y configuración