Renglones de los comprobantes

Retenciones, descuentos y ajustes de cada comprobante, tal como los tiene el ERP (archivo opcional).

Renglones contables de cada comprobante que no son banco ni cartera: retenciones, descuentos, ajustes, anticipos y otros. Con ellos Fibek sabe cuánto debía llegar al banco por cada comprobante. Archivo voucher_breakdown.csv.

Archivo opcional: si no lo envías, Fibek conserva los renglones que ya tenía y los comprobantes nuevos quedan con renglones desconocidos (UNKNOWN). Ver Estados.

Dependencia: se procesa justo después de Comprobantes y solo dentro de la misma carga: cada erp_voucher_id debe ser un comprobante válido del archivo de comprobantes de esa carga, y cada erp_invoice_id que envíes, una factura válida del archivo de Facturas de esa carga. No basta con que ya existan en Fibek.

Endpoint

POST /manual-csv-integration/upload/voucher-breakdown

  • Campo de Formulario: file

Este archivo no tiene endpoint en /full-csv-integration. Se carga por la Integración Manual de la plataforma (Mi Compañía → Integraciones → Integración Manual), con la sesión iniciada y junto con el archivo de comprobantes de la misma carga (y el de facturas, si los renglones nombran facturas). El endpoint valida y sube el archivo; las referencias se revisan al procesar la carga completa.

Campos Requeridos

Las cuatro columnas deben estar en la cabecera siempre, aunque una declaración UNKNOWN las deje vacías.

CampoTipoDescripciónValidaciones
erp_voucher_idStringID del comprobante en ERPDebe ser un comprobante válido del archivo de comprobantes de esta carga. Se conserva como texto
kindStringTipo de renglónWITHHOLDING (retención), DISCOUNT (descuento), ADJUSTMENT (ajuste), ADVANCE (anticipo), OTHER (otro) o UNKNOWN (no se conocen los renglones). Se recortan espacios y se pasa a mayúsculas
signed_amountFloatImporte con signo: débito menos créditoPunto decimal, sin separadores de miles ni exponentes. Debe caber en numeric(18,2); se redondea a dos decimales. Debe ser distinto de 0 después de redondear; los negativos son válidos. Vacío en UNKNOWN
erp_line_refStringReferencia estable del renglón contableObligatoria salvo en UNKNOWN, donde va vacía. Se conserva como texto; identifica el renglón dentro del documento de origen

Campos Opcionales

CampoTipoDescripciónValidacionesPor Defecto
erp_source_document_idStringDocumento contable que agrupa los comprobantesDebe coincidir con el documento del comprobante: la columna opcional erp_source_document_id del archivo de comprobantes, o su propio erp_voucher_id si no la trae. Se acepta en UNKNOWNerp_voucher_id
erp_invoice_idStringFactura a la que corresponde el renglónSi lo envías, debe ser una factura válida del archivo de facturas de esta carga. Vacío en UNKNOWNnull
codeStringCódigo del renglónTexto libre, se pasa a mayúsculas. Vacío en UNKNOWNnull
nameStringNombre del renglón en el ERPVacío en UNKNOWNnull
account_codeStringCuenta contableSe conserva como texto. Vacío en UNKNOWNnull
base_amountFloatBase sobre la que se calculó el renglónPunto decimal, sin separadores de miles ni exponentes. Debe caber en numeric(18,2); se redondea a dos decimales. Vacío en UNKNOWNnull
rate_percentFloatTarifa del renglón, en por cientoSiempre en por ciento, con punto decimal: 19 es un IVA del 19 % y 2.5 una ReteFuente del 2,5 %. La ReteICA también va en por ciento, no en por mil: 9,66 por mil se escribe 0.966. Sin separadores de miles ni exponentes. Debe caber en numeric(7,4); se redondea a cuatro decimales. Vacío en UNKNOWNnull

Cómo se lee el signo

Lo que debía llegar al banco por un comprobante es:

banco = total_amount del comprobante − suma de signed_amount

total_amount es el del archivo de comprobantes, en bruto: lo que el comprobante aplicó a cartera, antes de restar retenciones, descuentos y los demás renglones de este archivo. No es lo que llegó al banco.

El signo es débito menos crédito, como en el ERP: un importe positivo reduce lo que debía llegar al banco y uno negativo lo aumenta.

Estados

Cada comprobante de la carga queda en uno de tres estados:

  • Con renglones (KNOWN): el comprobante queda con renglones propios (un renglón compartido cuenta solo para el primero; ver más abajo).
  • Sin renglones (NONE): el archivo se envió y no trae renglones para el comprobante. Enviar el archivo significa que conoces el dato, aunque solo tenga la cabecera.
  • Desconocido (UNKNOWN): el comprobante trae una declaración UNKNOWN, o el archivo no se envió y el comprobante es nuevo.

Para declarar que no conoces los renglones de un comprobante, envía una sola fila con kind = UNKNOWN y el resto de los datos del renglón vacíos (puedes mantener erp_source_document_id). No se crea un renglón: se retiran los anteriores de ese comprobante. Los demás comprobantes del mismo documento pueden traer sus propios renglones o declaraciones.

Filas repetidas y filas descartadas

  • Cada documento de origen se procesa completo y de una vez: los renglones que ya no vienen se retiran y los que reaparecen recuperan su identidad.
  • Un renglón se identifica por documento de origen y erp_line_ref. Las copias idénticas se cuentan una vez; si varios comprobantes del documento comparten el renglón, queda una sola copia en el primero y sin factura. Dos copias distintas del mismo renglón descartan el documento completo.
  • Una fila inválida descarta todo el documento de origen, que conserva lo que tenía, y la respuesta trae una advertencia. Los demás documentos siguen.
  • Faltan columnas obligatorias, hay columnas repetidas o filas con otra cantidad de columnas: el archivo completo se rechaza.

Ejemplo CSV

VCH001 y VCH002 son comprobantes de esta carga con documento DOC001 (columna erp_source_document_id del archivo de comprobantes), e INV001 es una factura de esta carga.

erp_voucher_id,kind,signed_amount,erp_line_ref,erp_source_document_id,erp_invoice_id,code,name,account_code,base_amount,rate_percent
VCH001,DISCOUNT,2000,001,DOC001,INV001,EARLY_PAYMENT,Pronto pago,530535,,
VCH001,ADJUSTMENT,-0.98,002,DOC001,,,,429581,,
VCH002,UNKNOWN,,,DOC001,,,,,,