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
`pre_tax_amount`	Float	Subtotal de la factura antes de impuestos	Punto decimal, sin separadores de miles ni exponentes. Debe caber en `numeric(18,2)`; se redondea a dos decimales. Un valor inválido descarta esa factura de la carga, con una advertencia: si ya existía, conserva sus datos anteriores (las cuotas y pagos de esa misma carga sí se le aplican); si es nueva, no se crea. Vacío u omitido guarda `null` también al actualizar: borra el valor que la factura ya tenía. Ver Valor antes de impuestos	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.

Valor antes de impuestos

pre_tax_amount es el valor de toda la factura antes de impuestos: el subtotal que muestra el ERP, incluidos los ítems exentos o excluidos de IVA (no es la base gravable del IVA).

Fibek lo usa cuando el descuento por pronto pago, o un descuento acordado con el cliente, se calcula «Sobre el valor antes de IVA». Si la factura no lo trae, Fibek no propone ese descuento.
Si la factura ya tiene abonos o notas crédito, el descuento se calcula sobre la parte que corresponde al saldo: pre_tax_amount × pending_amount / original_amount.
No hace falta enviar Impuestos por factura para usarlo. Si Fibek tiene los impuestos de la factura (de esta carga o de una anterior), comprueba que pre_tax_amount + impuestos − retenciones ya restadas dé original_amount, con una diferencia de hasta $1, y el detalle de la factura avisa cuando no cuadra.
El base_amount de cada fila de impuestos es la base de ese impuesto; no reemplaza a pre_tax_amount.
Envía la columna en todas las cargas: una carga sin la columna, o con la celda vacía, borra el valor guardado.

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,pre_tax_amount,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,840336.13,CC001,60.0,CC002,40.0
CUST002,INV002,COP,500000.00,0.00,CLOSED,2024-01-20,2024-02-20,0.00,1,CASH,420168.07,CC001,100.0,,