Facturas

Administra facturas de cuentas por cobrar.

Facturas de cuentas por cobrar emitidas a clientes.

Dependencia: Requiere cargar Clientes primero.

Endpoint

POST /full-csv-integration/upload-invoices

Campo de Formulario: invoicesFile

Campos Requeridos

Campo	Tipo	Descripción	Validaciones
`erp_customer_id`	String	ID del cliente en ERP	No puede estar vacío. Debe existir en Clientes — ver la advertencia más abajo
`erp_invoice_id`	String	ID de la factura en ERP	No puede estar vacío
`currency`	String	Código de moneda	ej., `COP`, `USD`, `EUR`. No puede estar vacío y debe ser de 3 letras: uno más largo pasa la validación pero hace fallar el procesamiento
`original_amount`	Float	Monto original de la factura	Número decimal, mayor o igual a 0
`pending_amount`	Float	Monto pendiente	Número decimal
`status`	String	Estado de la factura	`OPEN` (Abierta) o `CLOSED` (Cerrada). Escríbalo en mayúsculas: en minúsculas la respuesta confirma la carga, pero después falla el procesamiento del archivo completo
`issue_date`	Date	Fecha de emisión de la factura	Si trae valor debe ser `YYYY-MM-DD`; otros formatos se rechazan. Una celda vacía se acepta y la fecha queda vacía
`due_date`	Date	Fecha de vencimiento del pago	Si trae valor debe ser `YYYY-MM-DD`; otros formatos se rechazan. Una celda vacía se acepta y la fecha queda vacía

Campos Opcionales

Campo	Tipo	Descripción	Validaciones	Por Defecto
`advance_amount`	Float	Pago anticipado aplicado	Número decimal. Si se omite o va vacío se guarda como `0.00`	`0.00`
`allow_collection`	Boolean	Permitir cobro	Solo `1` o `0`. El valor por defecto aplica únicamente si omite la columna; una celda vacía guarda `0`, tanto al crear como al actualizar	`1`
`invoice_type`	Enum	Condición comercial de la factura	`CREDIT` o `CASH`. Se ignoran mayúsculas, minúsculas y espacios externos. Cualquier otro valor no vacío rechaza la carga	`CREDIT` al crear; vacío u omitido conserva el valor al actualizar
`invoice_url`	String	URL al documento de la factura	-	null
`cost_center_1_erp_id`	String	ID del centro de costo 1	Debe proporcionar el `_pct` correspondiente	null
`cost_center_1_pct`	Float	Porcentaje del centro de costo 1	Número entre 0 y 100. Solo se registran los valores mayores a 0	null
`cost_center_2_erp_id`	String	ID del centro de costo 2	Debe proporcionar el `_pct` correspondiente	null
`cost_center_2_pct`	Float	Porcentaje del centro de costo 2	Número entre 0 y 100. Solo se registran los valores mayores a 0	null
`cost_center_3_erp_id`	String	ID del centro de costo 3	Debe proporcionar el `_pct` correspondiente	null
`cost_center_3_pct`	Float	Porcentaje del centro de costo 3	Número entre 0 y 100. Solo se registran los valores mayores a 0	null
`cost_center_4_erp_id`	String	ID del centro de costo 4	Debe proporcionar el `_pct` correspondiente	null
`cost_center_4_pct`	Float	Porcentaje del centro de costo 4	Número entre 0 y 100. Solo se registran los valores mayores a 0	null
`cost_center_5_erp_id`	String	ID del centro de costo 5	Debe proporcionar el `_pct` correspondiente	null
`cost_center_5_pct`	Float	Porcentaje del centro de costo 5	Número entre 0 y 100. Solo se registran los valores mayores a 0	null

Distribución por centros de costo

Se aceptan hasta 5 pares de centros de costo. Para cada par i:

Si envías cost_center_i_erp_id o cost_center_i_pct, debes enviar ambas columnas; de lo contrario la carga falla.
Cada porcentaje debe estar entre 0 y 100; fuera de ese rango la carga se rechaza. La suma por factura no se valida: no es necesario que dé 100.
Solo las filas con un porcentaje mayor a 0 generan una distribución.
cost_center_i_erp_id se guarda tal cual — no se verifica que exista en Centros de Costo.
Las distribuciones se reemplazan por factura, pero solo si la factura trae al menos un par con porcentaje mayor a 0. Una factura que no trae centros de costo conserva la distribución que ya tenía: envía juntos todos los centros de costo de una factura.

Tipo de factura y métricas

CREDIT indica una venta con plazo de pago; no significa nota crédito ni método de pago.
CASH puede seguir con estado OPEN, saldo pendiente y gestión de cobranza. En ese caso la respuesta trae una advertencia (CASH_WITH_PENDING_BALANCE), pero la fila se acepta.
Las métricas financieras del sistema —ventas, saldos, aging, DSO, rotación, efectividad de cobro, comportamiento, proyecciones y métricas ejecutivas derivadas— usan únicamente facturas CREDIT.
La cobranza operativa, los estados de cuenta y la atribución de campañas continúan incluyendo ambos tipos.
Cambiar el tipo de una factura existente reclasifica también su historial financiero.

Filas repetidas y filas descartadas

Si el mismo erp_invoice_id aparece en varias filas, se conserva la última.
Las filas cuyo erp_customer_id no exista en Clientes se descartan al procesar el archivo, y eso no se refleja en la respuesta, que ya confirmó la carga. Si ningún cliente del archivo existe, no se procesa nada.

Ejemplo CSV

erp_customer_id,erp_invoice_id,currency,original_amount,pending_amount,status,issue_date,due_date,advance_amount,allow_collection,invoice_type,cost_center_1_erp_id,cost_center_1_pct,cost_center_2_erp_id,cost_center_2_pct
CUST001,INV001,COP,1000000.00,500000.00,OPEN,2024-01-15,2024-02-15,0.00,1,CREDIT,CC001,60.0,CC002,40.0
CUST002,INV002,COP,500000.00,0.00,CLOSED,2024-01-20,2024-02-20,0.00,1,CASH,CC001,100.0,,