Endpoints / Proformas
Crear proforma
Registra una nueva proforma en estado emitida para la empresa del usuario autenticado, con detalle completo de items, y genera su documento PDF inicial.
/proformasCaso de Uso
Se usa cuando la aplicación necesita emitir una nueva proforma desde el punto de venta con los productos o servicios seleccionados, los datos del cliente, sucursal, caja y método de pago. Al usarlo, el usuario obtiene la estructura completa de la proforma creada, incluyendo el identificador generado, los datos del emisor y receptor, y el documento PDF.
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
Este endpoint no recibe parámetros de ruta.
Body
prfmasuidstringobligatorioIdentificador de la sucursal emisora; debe existir y estar activa.
prfmacjidstringobligatorioIdentificador de la caja emisora; debe existir, pertenecer a la sucursal y estar activa.
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.
prfmadescuentonumber opcionalDescuento total aplicado a la proforma; debe ser mayor o igual a cero. Si no se envía, se asume 0.
prfmatotalnumberobligatorioTotal de la proforma; debe ser igual a subtotal - descuento y no puede ser negativo.
dprfmaproductosarrayobligatorioArreglo no vacío de items de la proforma. Cada item contiene: dprfmaesinventariable (boolean), dprfmacodigo (string, condicional), dprfmadescripcion (string), dprfmacantidad (number > 0), dprfmapreciounitario (number > 0), dprfmapreciototal (number > 0).
Reglas de negocio
La proforma siempre se crea en estado emitida.
Solo un usuario con rol jefe o empleado puede crear proformas.
La empresa del usuario autenticado debe estar activa.
El usuario autenticado debe estar activo.
La sucursal debe existir y estar activa dentro de la empresa.
La caja debe existir, estar activa y pertenecer a la sucursal indicada.
El cliente debe existir y estar activo dentro de la empresa.
El método de pago debe existir y estar activo dentro de la empresa.
Debe existir una secuencia configurada para la combinación empresa + sucursal.
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 enviados por el frontend.
La suma de dprfmapreciototal de todos los items debe coincidir con prfmasubtotal.
prfmasubtotal - prfmadescuento debe coincidir con prfmatotal.
Se genera un documento PDF automáticamente al crear la proforma.
prfmaidentificador se genera como {códigoEmpresa}-{identificadorSucursal}-{identificadorCaja}-{secuencia}.
Errores esperados
No se envió un token JWT válido o el token no contiene información válida del usuario.
prfmasuid fue enviado vacío.
prfmacjid fue enviado vacío.
prfmaclnteid fue enviado vacío.
prfmampid fue enviado vacío.
prfmasubtotal, prfmatotal o un campo numérico de item fue enviado vacío.
Uno de los campos numéricos no es un número válido.
prfmasubtotal tiene un valor negativo.
prfmadescuento tiene un valor negativo.
prfmatotal tiene un valor negativo.
dprfmaproductos fue enviado vacío o no es un arreglo.
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.
Un item tiene dprfmaesinventariable: true pero dprfmacodigo está vacío.
Un item no inventariable tiene dprfmacodigo enviado pero vacío.
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 crear proformas.
prfmasuid no corresponde a una sucursal existente en la empresa.
La sucursal indicada no está en estado activo.
prfmacjid no corresponde a una caja existente en la empresa.
La caja indicada no está asociada a la sucursal enviada.
La caja indicada no está en estado activo.
prfmaclnteid no corresponde a un cliente existente en la empresa.
El cliente indicado no está en estado activo.
prfmampid no corresponde a un método de pago existente en la empresa.
El método de pago indicado no está en estado activo.
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 suma de dprfmapreciototal de todos los items no coincide con prfmasubtotal.
prfmatotal no es igual a prfmasubtotal - prfmadescuento.
prfmasubtotal - prfmadescuento da un valor negativo.
No hay una secuencia configurada para la combinación de empresa y sucursal.
Ocurrió un error interno al guardar la cabecera de la proforma.
Ocurrió un error interno al guardar un item de la proforma.
Notas de uso
Este endpoint no recibe parámetros de ruta ni query params.
El backend no recalcula los importes; el frontend debe enviar un payload consistente.
La respuesta incluye el documento PDF generado automáticamente en proforma.documento.
prfmaidentificador se genera automáticamente con el formato {códigoEmpresa}-{identificadorSucursal}-{identificadorCaja}-{secuencia}.