Endpoints / Proformas
Reemplazar proforma
Reemplaza completamente el contenido editable de una proforma emitida en una sola operación atómica, incluyendo cliente, método de pago, montos y detalle de items.
/proformas/:idCaso de Uso
Se usa cuando la aplicación necesita guardar la edición completa de una proforma desde el formulario de edición, enviando el estado final del detalle. Al usarlo, el usuario obtiene la proforma actualizada con su nuevo contenido y el PDF regenerado.
Autenticación
Requiere token JWT en el header `Authorization: Bearer <token>`. Permite acceso a usuarios con rol jefe o empleado. La empresa y el usuario autenticado deben estar activos.
Parámetros de ruta
idstringobligatorioIdentificador de la proforma a reemplazar.
Body
prfmaclnteidstringobligatorioIdentificador del cliente receptor; debe existir y estar activo.
prfmampidstringobligatorioIdentificador del método de pago; debe existir y estar activo.
prfmasubtotalnumberobligatorioSubtotal de la proforma; debe ser mayor o igual a cero y coincidir con la suma de los totales de los items.
prfmadescuentonumberobligatorioDescuento total aplicado; debe ser mayor o igual a cero.
prfmatotalnumberobligatorioTotal de la proforma; debe ser igual a subtotal - descuento y no puede ser negativo.
dprfmaproductosarrayobligatorioArreglo completo del detalle final; representa el estado final de los items. Cada item contiene: dprfmaid (opcional), dprfmaesinventariable (boolean), dprfmacodigo (string, condicional), dprfmadescripcion (string), dprfmacantidad (number > 0), dprfmapreciounitario (number > 0), dprfmapreciototal (number > 0).
Reglas de negocio
Solo un usuario con rol jefe o empleado puede reemplazar proformas.
Solo permite reemplazar proformas de la empresa del usuario autenticado.
La empresa del usuario autenticado debe estar activa.
El usuario autenticado debe estar activo.
Solo una proforma en estado emitida puede editarse.
El body representa el detalle completo final; no es una lista parcial de cambios.
Una línea con dprfmaid enviado se actualiza; sin dprfmaid se inserta como nueva.
Una línea existente que no aparece en el arreglo se elimina.
No se permiten dprfmaid duplicados en el arreglo.
Todo dprfmaid enviado debe pertenecer a la proforma indicada.
El cliente y el método de pago deben existir y estar activos.
No se permiten códigos de producto inventariable duplicados entre los items.
Todo item inventariable requiere dprfmacodigo, que debe corresponder a un producto existente y activo.
El backend no recalcula los totales; valida la consistencia de los montos.
Esta operación no descuenta stock ni afecta el inventario.
Al completar el reemplazo se regenera el PDF con el contenido actualizado.
Errores esperados
No se envió un token JWT válido o el token no contiene información válida del usuario.
No se envió el parámetro id en la ruta.
prfmaid en el body fue enviado vacío.
prfmaclnteid fue enviado vacío o no es un texto.
prfmampid fue enviado vacío o no es un texto.
Uno de los campos numéricos no es un número ni texto numérico.
Uno de los campos numéricos fue enviado vacío.
prfmasubtotal tiene un valor negativo.
prfmadescuento tiene un valor negativo.
prfmatotal tiene un valor negativo.
dprfmaproductos no es un arreglo o está vacío.
dprfmaesinventariable en un item no es un valor booleano.
dprfmacantidad de un item es menor o igual a 0.
dprfmapreciounitario de un item es menor o igual a 0.
dprfmadescripcion de un item fue enviado vacío.
dprfmapreciototal de un item es menor o igual a 0.
dprfmacodigo de un item no es un texto válido.
Un item tiene dprfmaesinventariable: true pero dprfmacodigo está vacío.
Un item no inventariable tiene dprfmacodigo enviado pero vacío.
No existe una proforma con el id indicado dentro de la empresa del usuario autenticado.
La proforma no está en estado emitida; las proformas pagadas o anuladas no pueden editarse.
La suma de dprfmapreciototal de todos los items no coincide con prfmasubtotal.
prfmatotal no es igual a prfmasubtotal - prfmadescuento.
prfmasubtotal - prfmadescuento da un valor negativo.
Uno o más dprfmaid enviados no pertenecen a la proforma indicada.
Hay dprfmaid repetidos en el arreglo de items.
Hay dos o más items inventariables con el mismo dprfmacodigo.
El dprfmacodigo de un item inventariable no corresponde a un producto existente.
El producto referenciado por dprfmacodigo no está en estado activo.
La empresa asociada al usuario autenticado no fue encontrada.
La empresa asociada al usuario autenticado está inactiva.
El usuario autenticado no fue encontrado dentro de su empresa.
El usuario autenticado no pertenece a la empresa indicada por su sesión.
El usuario autenticado está inactivo y no puede usar el sistema.
El usuario autenticado no tiene un rol permitido para reemplazar proformas.
Notas de uso
Este endpoint no recibe query params.
El body debe contener el estado final completo del detalle; no envíes solo cambios parciales.
Las líneas sin dprfmaid se insertan como nuevas; las líneas con dprfmaid se actualizan.
Las líneas existentes que no aparecen en el arreglo se eliminan.
Esta operación no descuenta stock; el descuento de inventario ocurre al pagar la proforma.
El PDF se regenera automáticamente al completar el reemplazo.