Skip to main content

​
Overview

Commercial agreements define the negotiated terms between ICL and each FFWW client, including fiscal deposit fees, deconsolidation rates, insurance terms, and commission structures. These agreements automatically populate relevant costs when creating quotations.

​
Agreement Structure

Each commercial agreement is linked to a single FFWW client and can optionally reference a specific end client for triangular relationships.
Clients with client_type = "Both" can have agreements as both FFWW and end client.

​
Creating a Commercial Agreement

1

Access agreements

Navigate to Maestros → Acuerdos Comerciales or use the Acuerdo Comercial tab when creating/editing a client.
2

Select client relationship

  • Cliente: Primary FFWW client (required)
  • Cliente Final or Cliente FFWW: Conditional field based on client type
    • If primary client is FFWW → Select a Final or Both client
    • If primary client is Final → Select a FFWW or Both client
    • If primary client is Both → Field hidden (no linking)
3

Configure rate schedules

  • Tarifario: Rate schedule reference code
  • Tarifario Fiscal: Fiscal rate schedule
  • Moneda: Agreement currency (USD, EUR, ARS)
4

Set deconsolidation terms

Deconsolidation Rates
  • W/M: Weight/measurement rate type
  • Min: Minimum charge
  • Max: Maximum charge
  • Notas: Deconsolidation notes
5

Define fiscal deposit fees

  • AGP/Tn: Agricultural inspection fee per ton
  • Manejo Documentos: Document handling fee
  • Log Fee: Logistics fee
  • Doc Fee: Documentation fee
  • Certflete: Freight certificate fee
6

Configure insurance terms

  • Seguro %: Insurance percentage of cargo value
  • Seguro Min: Minimum insurance charge
7

Set other fees

  • Emision BL: Bill of lading emission fee
8

Define commercial terms

  • Plazo de Pago: Payment terms (e.g., “Net 30”, “Immediate”)
  • Maximo Descontar: Maximum discount percentage allowed
  • Comision: Commission percentage
  • Incentivo: Incentive percentage
9

Add notes and metadata

  • Datos a Cotizar: Quote data reference
  • Observaciones: General notes
  • Vendedor: Sales representative managing this agreement
  • Ultima Modificacion: Last modified date (auto-updated)
10

Save agreement

Click Guardar to create or update the commercial agreement.

​
Agreement Display in Quotations

When you select a FFWW client in a quotation, the system:
  1. Queries GET /api/acuerdos?cliente_id={id}
  2. If agreement found, displays Gastos en Deposito Fiscal section
  3. Shows all fee fields in read-only format
  4. If not found, displays: “Sin acuerdo comercial para este cliente”
Source: src/components/cotizaciones/cotizacion-form.tsx:235-252

​
Displayed Fields

Deconsolidation

  • W/M rate type
  • Min charge
  • Max charge

Processing Fees

  • AGP/Tn
  • Document handling
  • Log fee
  • Doc fee

Additional Charges

  • Freight certificate
  • Insurance % and min
  • BL emission
Observations appear full-width below the fee grid if present.

​
Client Type Conditional Logic

The first field in the agreement form adapts based on the primary client’s type:
Primary Client TypeField LabelAvailable Options
FFWW”Cliente Final”Clients with client_type = Final or Both
Final”Cliente FFWW”Clients with client_type = FFWW or Both
Both(field hidden)N/A
The combobox uses legal_name as the stored value (not id). Source: docs/flows/07-gestion-maestros.md:49-60

​
Agreement Management Page

The Acuerdos Comerciales master page displays agreements in a grouped table:

​
Table Columns

  • Cliente: Primary FFWW client name
  • Cliente Final: End client reference (if applicable)
  • Vendedor: Sales representative
  • Tarifario: Rate schedule code
  • Moneda: Agreement currency
  • Deconsolidado: W/M, Min, Max values
  • Fees: AGP, Doc handling, Log fee, Doc fee
  • Seguro: Insurance % and minimum
  • Plazo Pago: Payment terms
  • Comision/Incentivo: Commercial percentages
  • Ultima Mod: Last modification date

​
Filter Options

  • Search: Filter by client name, end client, or rate schedule
  • Cliente: Multi-select client filter
  • Vendedor: Filter by sales representative
  • Moneda: Currency filter

​
Actions

  • Nuevo Acuerdo: Create new agreement
  • Edit: Modify agreement details
  • Delete: Remove agreement (admin only)

​
Access Control

OperationAdminCommercial User
View agreements✓✓ (all)
Create agreement✓✗ (403)
Edit agreement✓✗ (403)
Delete agreement✓✗ (403)
View in quotation✓✓ (read-only)
All users can view agreements in quotations, but only admins can create/modify them in the Maestros section.

​
Data Model Reference

From commercial_agreements table (src/db/schema.ts:37-66): 
commercial_agreements {
  id: integer (PK)
  client_id: integer (FK → clients)
  end_client: text // Cliente final name (not FK)
  rate_schedule: text
  deconsolidation_wm: text
  deconsolidation_min: real
  deconsolidation_max: real
  deconsolidation_notes: text
  agp_per_ton: real
  document_handling: real
  log_fee: real
  doc_fee: real
  freight_cert: real
  insurance_pct: real
  insurance_min: real
  bl_emission: real
  payment_terms: text
  max_discount: real
  commission: real
  incentive: real
  quote_data: text
  notes: text
  user_id: integer (FK → users) // Vendedor
  last_modified: text
  fiscal_rate_schedule: text
  currency: "USD" | "EUR" | "ARS" (default: "USD")
  created_at: text
  updated_at: text
}

​
API Endpoints

  • GET /api/acuerdos - List all agreements (supports ?cliente_id=X filter)
  • POST /api/acuerdos - Create new agreement (admin only)
  • GET /api/acuerdos/[id] - Get agreement details
  • PUT /api/acuerdos/[id] - Update agreement (admin only)
  • DELETE /api/acuerdos/[id] - Delete agreement (admin only)

​
Agreement Best Practices

Currency Consistency

Set agreement currency to match the primary currency used in quotations for this client to avoid conversion complexity.

Rate Schedule Codes

Use consistent naming conventions for Tarifario codes (e.g., “2024-Q1-ASIA”, “STD-EUR-2026”) to enable easy filtering and reporting.

Fee Structure

  • Leave fees as null if not applicable rather than setting to 0
  • This distinction helps identify services that don’t apply vs. waived fees

Documentation

Use Observaciones field to note special conditions, validity periods, or exceptions to standard terms.

​
Common Use Cases

​
Volume-Based Deconsolidation

W/M: "Per CBM"
Min: 150 (minimum charge)
Max: 2500 (cap per shipment)

​
Insurance Terms

Seguro %: 0.5 (0.5% of cargo value)
Seguro Min: 25 (minimum $25 charge)

​
Payment and Commission

Plazo de Pago: "Net 30 days"
Comision: 2.5 (2.5% commission)
Incentivo: 1.0 (1% incentive on targets)
Maximo Descontar: 5 (max 5% discount allowed)

Build docs developers (and LLMs) love

Get started for freeTalk to us