Quotation
Una cotización es la oferta comercial de una oportunidad: reúne un árbol de ítems con sus costos unitarios, los gastos generales, la utilidad, los descuentos y los impuestos, y avanza por un flujo de estados hasta cerrarse y convertirse en proyecto.
| Modelo | App\Models\Quotation |
| Tabla | quotations |
El objeto Quotation
Sección titulada «El objeto Quotation»Atributos
Sección titulada «Atributos»idintegerIdentificador de la cotización.
codestringCódigo de la cotización: mes y correlativo, nombre, cliente y versión. Lo genera el servidor.
versionintegerNúmero de versión. La cotización principal es 1.
namestringNombre de la cotización.
descriptionstringDescripción de la cotización.
datedateFecha de la cotización.
days_validityintegerDías de validez.
incoming_validity_datedateFecha en que la cotización entró en validez. Se fija al pasar a negociando y se borra al volver a cotizando o revisando.
igvnumberPorcentaje de IGV, tomado de los impuestos al crear la cotización.
rentnumberPorcentaje de renta, tomado de los impuestos.
detractionnumberPorcentaje de detracción.
include_igv_items_for_pdfbooleanIndica si los ítems del PDF incluyen el IGV.
customer_idintegerCliente. Sale de la oportunidad.
customer_business_unit_idintegerUnidad de negocio del cliente. Sale de la oportunidad.
customer_contact_idintegerContacto del cliente.
seller_idintegerVendedor.
project_manager_idintegerProject manager.
opportunity_idintegerOportunidad de la cotización.
budget_folder_idintegerCarpeta de presupuesto.
project_idintegerProyecto. Se asigna cuando la cotización se cierra.
reference_quotation_idintegerCotización principal de la que esta es una versión. Es nulo en la principal.
replace_quotation_idintegerCotización que reemplaza a esta.
coin_idintegerMoneda de la cotización.
coin_valuenumberValor de la moneda al momento de calcular la cotización.
limit_decimalsintegerCantidad de decimales con que se calculan los montos. Por defecto 4.
scopesarrayAlcances de la cotización, como lista JSON.
conditionsarrayCondiciones de la cotización, como lista JSON.
is_global_utilitybooleanIndica si la utilidad es global para todos los ítems.
is_global_utility_in_percentagebooleanIndica si la utilidad global se expresa en porcentaje.
is_global_discount_in_percentagebooleanIndica si el descuento global se expresa en porcentaje.
is_individual_utility_for_itemsbooleanIndica si cada ítem de costo unitario lleva su propia utilidad.
items_utility_individualbooleanIndica si la utilidad es individual por ítem.
utility_individual_for_cubooleanIndicador heredado de utilidad individual por costo unitario.
global_utility_percentagenumberPorcentaje de utilidad global.
total_global_utilitynumberMonto de la utilidad global.
global_discount_percentagenumberPorcentaje de descuento global.
total_global_discountnumberMonto del descuento global.
global_expenses_percentagenumberPorcentaje de gastos generales.
total_cost_materialsnumberCosto total de materiales.
total_cost_workforcesnumberCosto total de mano de obra.
total_cost_subcontractsnumberCosto total de subcontratos.
total_cost_equipment_toolsnumberCosto total de equipos y herramientas.
total_utility_materialsnumberUtilidad total de materiales.
total_utility_workforcesnumberUtilidad total de mano de obra.
total_utility_subcontractsnumberUtilidad total de subcontratos.
total_utility_equipment_toolsnumberUtilidad total de equipos y herramientas.
total_materialsnumberTotal de materiales (costo más utilidad).
total_workforcesnumberTotal de mano de obra.
total_subcontractsnumberTotal de subcontratos.
total_equipment_toolsnumberTotal de equipos y herramientas.
total_items_costnumberCosto total de los ítems.
total_items_utilitynumberUtilidad total de los ítems.
total_itemsnumberTotal de los ítems (costos más utilidades).
total_cost_overheads_itemsnumberCosto total de los gastos generales.
total_utility_overheads_itemsnumberUtilidad total de los gastos generales.
total_overheads_itemsnumberTotal de los gastos generales por ítem (costo más utilidad).
overheads_items_utilitybooleanIndica si cada gasto general lleva su propia utilidad.
overheads_global_utility_percentagenumberPorcentaje de utilidad global de los gastos generales.
total_overheads_global_utilitynumberMonto de la utilidad global de los gastos generales.
total_overheadsnumberTotal de los gastos generales.
overheads_percentagenumberPorcentaje que representan los gastos generales.
subtotalnumberSubtotal de la cotización.
total_igvnumberMonto del IGV.
totalnumberTotal de la cotización: subtotal más IGV.
total_rentnumberMonto de la renta.
total_detractionnumberMonto de la detracción.
total_with_discountnumberTotal con el descuento aplicado.
status_update_commentstringComentario del último cambio de estado.
status_update_datedatetimeFecha del último cambio de estado.
status_update_user_idintegerUsuario que hizo el último cambio de estado.
previous_statusstringEstado anterior. Lo llena el sistema al cambiar el estado.
create_user_idintegerUsuario que creó el registro. Se asigna automáticamente.
update_user_idintegerUsuario que hizo la última modificación.
delete_user_idintegerUsuario que eliminó el registro.
restore_user_idintegerUsuario que restauró el registro.
restored_atdatetimeFecha de la última restauración.
created_atdatetimeFecha de creación.
updated_atdatetimeFecha de la última modificación.
deleted_atdatetimeFecha de eliminación lógica.
{ "id": 1520, "code": "110012 - INSTALACION_ELECTRICA - ACME_SAC-V1", "version": 1, "igv": 18, "rent": 1.5, "detraction": 12, "name": "Instalación eléctrica", "date": "2026-11-19", "description": "Instalación eléctrica del almacén central", "days_validity": 30, "coin_id": 1, "coin_value": 3.75, "limit_decimals": 4, "customer_id": 8, "customer_contact_id": 14, "seller_id": 5, "project_manager_id": 9, "opportunity_id": 77, "budget_folder_id": 31, "status": "cotizando", "is_global_utility": false, "total_items": 12500, "total_overheads": 1500, "subtotal": 14000, "total_igv": 2520, "total": 16520, "create_user_id": 5, "created_at": "2026-11-19T10:40:15.000000Z", "updated_at": "2026-11-19T10:40:15.000000Z", "deleted_at": null}Relaciones
Sección titulada «Relaciones»| Relación | Tipo | Modelo |
|---|---|---|
seller |
belongsTo | User |
projectManager |
belongsTo | User |
customer |
belongsTo | Customer |
customerContact |
belongsTo | CustomerContact |
coin |
belongsTo | Coin |
opportunity |
belongsTo | Opportunity |
budgetFolder |
belongsTo | BudgetFolder |
project |
belongsTo | Project |
referenceQuotation |
belongsTo | Quotation |
replaceQuotation |
belongsTo | Quotation |
replacedQuotation |
hasOne | Quotation |
versions |
hasMany | Quotation |
quotationItems |
hasMany | QuotationItem |
quotationOverheads |
hasMany | QuotationOverhead |
unitCosts |
hasMany | UnitCost |
quotationLogs |
hasMany | QuotationLog |
quotationCoinItems |
hasMany | QuotationCoinItem |
quotationWorkflows |
hasMany | QuotationWorkflow |
lastQuotationWorkflow |
hasOne | QuotationWorkflow |
El modelo también declara prospect, costCenterType y projectFolder, pero la tabla quotations no tiene las columnas que esas relaciones necesitan.
| Scope | Qué filtra |
|---|---|
customerId |
Por cliente. |
sellerId |
Por vendedor. |
projectManagerId |
Por project manager. |
projectId |
Por proyecto. |
projectFolderId |
Por project_folder_id, columna que no existe en la tabla. |
filterByRole |
Un usuario KAM ve sus cotizaciones como vendedor; uno PM, las suyas como project manager. |
whenBudgetFolderId |
Por carpeta de presupuesto. |
whenNullReferenceQuotationId |
Solo las principales, sin cotización de referencia. |
whenStatusNotIn |
Excluye los estados indicados. |
whenOpportunityId |
Por oportunidad. |
Orden y búsqueda
Sección titulada «Orden y búsqueda»Campos permitidos para ordenar: id, name, created_at, updated_at, status. Por defecto se ordena por id descendente. La búsqueda de texto (search) compara con name y code.
Estados
Sección titulada «Estados»El estado usa ModelStatusEnum. Una cotización nueva queda en cotizando. El flujo permite estas transiciones:
| Desde | Hacia |
|---|---|
cotizando |
revisando, aprobado |
revisando |
cotizando, aprobado |
aprobado |
cotizando, revisando, negociando |
negociando |
cerrado, cotizando, revisando |
cerrado |
ninguno |
Además, una cotización puede pasar a descartado y volver, y al eliminarla pasa a eliminado. Solo se edita en estado cotizando.
Permisos
Sección titulada «Permisos»El módulo usa QuotationPermission (clave quotation): quotation.create, quotation.view, quotation.edit, quotation.delete, quotation.revert-close y los de configuración (quotation.configuration.view, .create, .edit y .delete). Ver cada endpoint para saber cuál se exige.
Cómo se arma una cotización
Sección titulada «Cómo se arma una cotización»Una cotización es el encabezado de un árbol de datos que el servidor recalcula cada vez que cambia algo. Estas son las piezas, según el código.
Ítems. Los ítems (quotation_items) forman un árbol de hasta seis niveles con parent_quotation_item_id. Hay tres tipos (QuotationItemType): simple es un título o subtítulo sin costo, costo unitario es una partida que apunta a un costo unitario (unit_cost_id) y sin costo unitario es una partida directa. Un título suma los totales de sus hijos. Ver Ítems de cotización.
Materiales, mano de obra, equipos y subcontratos. No cuelgan directamente de la cotización: viven dentro del costo unitario de cada ítem (unit_cost_materials, unit_cost_workforces, unit_cost_equipment_tools y unit_cost_subcontracts). El servidor suma esos componentes por categoría en los campos total_materials, total_workforces, total_equipment_tools y total_subcontracts de la cotización, y la suma de todo es total_items. El listado de materiales de la cotización agrupa los materiales de todos sus costos unitarios por producto de proveedor. Ver Costos unitarios, Materiales de la cotización y Subcontratos de la cotización.
Gastos generales. Son un árbol aparte (quotation_overheads, con títulos y gastos) cuyo total se guarda en total_overheads. Pueden llevar utilidad propia (overheads_items_utility) o un porcentaje global (overheads_global_utility_percentage). Ver Gastos generales de la cotización.
Utilidad, descuento e impuestos. La utilidad puede ser global (is_global_utility y global_utility_percentage) o propia de cada ítem. El descuento global resta del total de ítems más gastos generales. Con eso el servidor calcula subtotal, el IGV (subtotal × igv / 100, con el porcentaje tomado de los impuestos) y total como subtotal más IGV.
Alcances y condiciones. Se guardan como listas JSON en las columnas scopes y conditions de la propia cotización y se editan con una sola llamada. Existen además los modelos QuotationScope y QuotationCondition, sin controlador ni rutas. Ver Alcances y Condiciones.
Comisiones. El modelo QuotationCommission guarda la comisión del asesor y el costo de administración, pero ningún controlador ni cálculo de la cotización lo usa hoy. Ver Comisiones.
Monedas. La cotización tiene una moneda (coin_id) y su valor (coin_value). Los componentes de los costos unitarios pueden venir en otra moneda y se convierten con su valor original. La tabla quotation_coin_items guarda, por cada moneda usada, cuántos componentes de cada categoría la usan. Cambiar la moneda reconvierte los ítems. Ver Monedas por ítem.
Versiones y flujo. Una versión (version 2 en adelante) apunta a su principal con reference_quotation_id y comparte con ella nombre, oportunidad y carpeta. El estado avanza por el flujo (cotizando, revisando, aprobado, negociando, cerrado) y cada paso queda en el flujo; los cambios relevantes quedan en el historial.
