Saltar a contenido

Invoices y pagos

Disponible para: Owner, Accounting, Project Manager (solo vista)

Los Invoices se crean cuando un Job alcanza el estado Completed / Needs Invoice. Representan el documento de facturación formal enviado al cliente y registran los pagos recibidos contra el monto total adeudado.

Un Invoice por Job

Cada Job puede tener exactamente un Invoice.

Si intenta crear un segundo Invoice para un Job, la API lo rechazará. Si un Invoice debe corregirse, debe editarse — no reemplazarse.

Campos del Invoice

Field Description
invoice_number Generado automáticamente al crear. Formato: INV-YYYYMMDD-HHMMSS (ej. INV-20240415-143022). Único por inquilino.
invoice_date Fecha en que se emitió el Invoice. Por defecto la fecha de creación.
due_date Fecha de vencimiento del pago. Manual o calculada según términos del inquilino.
subtotal Monto base antes de impuestos. Suele igualar el precio del Bid.
tax_rate Tomado de CompanySettings al crear el Invoice. Guardado en el Invoice para exactitud histórica.
tax_amount Calculado: subtotal × tax_rate.
total_amount Calculado: subtotal + tax_amount.
amount_paid Total acumulado de todos los pagos registrados contra este Invoice.
balance_due Calculado: total_amount − amount_paid.
status Estado actual del Invoice. Vea la máquina de estados abajo.

La aplicabilidad del impuesto se define en el Bid de origen (campo taxable). Si taxable es falso, tax_rate se guarda como 0 y no se calcula impuesto.

Cálculo de impuestos

Las tasas se configuran a nivel de inquilino en CompanySettings.tax_rate.

Al crear un Invoice:

  1. El sistema lee CompanySettings.tax_rate del inquilino actual.
  2. La tasa se copia al Invoice**** en el momento de la creación.
  3. Los cambios futuros a CompanySettings.tax_rate no afectan Invoices existentes.

Así se preserva la historia fiscal — la tasa aplicada queda fijada al crear el Invoice.

Máquina de estados

Status Description Who Can Set
Invoice Submitted Invoice creado y enviado al cliente. Accounting, Owner
Partially Paid Uno o más pagos registrados; sigue habiendo saldo. Sistema (automático al pagar)
Paid Saldo total pagado. balance_due es cero. Sistema (automático al pagar)
Workflow Complete Invoice resuelto y flujo del Job cerrado. Sistema (automático al pasar a Paid) 
Invoice Submitted → Partially Paid (on first partial payment)
                 → Paid (if full payment recorded in one entry)
Partially Paid   → Paid (on final payment)
Paid             → Workflow Complete (system-set automatically)

Las transiciones después de Invoice Submitted las impulsa el sistema según los totales de pago. No establece manualmente Paid ni Workflow Complete.

Seguimiento de pagos

Un solo Invoice puede tener varios pagos registrados (pagos parciales totalmente admitidos).

Campos del pago

Field Description
amount Monto en dólares de este pago.
payment_date Fecha en que se recibió el pago.
payment_method Forma de pago (ej. cheque, ACH, transferencia, tarjeta). Texto libre.
notes Notas opcionales del pago (ej. número de cheque, ID de referencia).

Cómo funcionan los pagos

  1. Accounting u Owner registra un pago contra un Invoice.
  2. amount_paid del Invoice se actualiza a la suma de todos los pagos.
  3. Se recalcula balance_due.
  4. Si balance_due llega a cero, el estado del Invoice pasa automáticamente a Paid y luego Workflow Complete.
  5. Todos los registros de pago se conservan — los pagos no se eliminan ni editan una vez registrados.

Registre pagos parciales conforme lleguen. El sistema llevará el avance hacia el saldo total.

Vista de lista de Invoices

La lista de Invoices muestra las columnas:

Bid ID | Job ID | Status | Client | PO Number | Invoice Date | Invoice # | PM | Subtotal | Tax | Total | Balance Due | Due Date

Las fechas de vencimiento tienen código de color según estado:

  • Verde — pagado o Workflow Complete
  • Amarillo — vence pronto (dentro del umbral configurado)
  • Rojo — vencido

Acceso por rol

Action Owner Accounting PM Supervisor Badge Worker
Create invoice Yes Yes No No No
Edit invoice Yes Yes No No No
Record payment Yes Yes No No No
View invoice Yes Yes Yes No No
View payment history Yes Yes Yes No No

Las ediciones de Invoice quedan en el ActivityLog con tipo de acción invoice_edit. El registro captura un diff JSON de los campos modificados.