Margen y rentabilidad
El Resumen del negocio de una unidad vendida (en JSON, PDF, Excel o CSV) y la exportación de Margen y rentabilidad: una fila por nota de venta del período, con las cifras del negocio sin IVA y las del comprador con IVA.
Descarga la proyección completa de la API pública: openapi.json.
Leer las cifras del negocio explica este recurso en prosa, con ejemplos ejecutables.
| Método | Ruta | Qué hace |
|---|---|---|
GET | /margin/export | Export the deals and their margins (xlsx / csv) |
POST | /margin/preview | Preview the margin of a nota de venta being written |
GET | /vehicles/{id}/deal-settlement | The Resumen del negocio of one unit |
GET | /vehicles/{id}/deal-settlement/export | Export the Resumen del negocio (xlsx / csv) |
GET | /vehicles/{id}/deal-settlement/pdf | Print the Resumen del negocio (PDF) |
GET /margin/export
Export the deals and their margins (xlsx / csv)
One row per live nota de venta in the window, with every settlement column: folio, date, status, patente, vehicle, regime, seller, buyer, buyer origin channel, leads, days in stock; then the cifras del negocio, NET of IVA (sale price, Adicionales con margen, revenue, purchase cost, Margen bruto, additional costs, commissions, Utilidad del negocio), the Cobros por cuenta del comprador (cobrado / rendido, neutral); then the cifras del comprador, GROSS and labelled so (sale price con IVA, IVA, published price, discount amount and %); and Completo / Pendiente (what an incomplete sale lacks: «Sin costo», «Sin comisión», «Sin liquidación»). Every sale is a row. A figure that is not recorded or not computable is an EMPTY cell, never 0.
Pass period (YYYY-MM, the Margen screen’s month) OR from/to (YYYY-MM-DD, inclusive, on the dealership’s calendar) — one of the two is required (400 otherwise), never both. format is xlsx (default) or csv. 413 over 2000 deals. Requires dealership_economics:read.
| Parámetro | En | Tipo | Obligatorio | Restricciones |
|---|---|---|---|---|
period | query | OverheadPeriod | no | |
from | query | string | no | patrón ^\d{4}-\d{2}-\d{2}$ |
to | query | string | no | patrón ^\d{4}-\d{2}-\d{2}$ |
format | query | xlsx \ | csv | no |
curl https://api.vitrinadev.com/api/v1/margin/export \
-H "Authorization: Bearer $VITRINA_KEY"Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429
POST /margin/preview
Preview the margin of a nota de venta being written
The margin a nota de venta WOULD leave if the unit sold today at net_clp — what the nota de venta form shows while the price is typed. The same preview the Resumen del negocio serves for a car with no live nota de venta (GET /vehicles/\{id\}/deal-settlement, state: preview), at the typed price instead of the published one: no add-ons, no seller commissions, and the one margin definition. The body is the deal-margin DTO of GET /margin/deals/\{id\} without sale_note_id, display_id and salesperson_id — no document exists yet.
A consigned unit is previewed on its contract’s economics: the split is projected from the active contract’s comisión exactly as the liquidación will compute it (settlement carries the projection), so the dealership’s revenue is the comisión, never the whole price. A contract with no comisión on file has no split to project: its revenue is null with a liquidacion gap.
net_clp is NET of IVA (cifras del negocio, ADR 0114 §2.2). The price a buyer agrees to on an afecto sale includes IVA, like the published price: send round(price / 1,19). Writes nothing. Requires dealership_economics:read; 404 for a unit outside the workspace.
Cuerpo
| Campo | Tipo | Obligatorio | Restricciones |
|---|---|---|---|
vehicle_id | uuid | sí | |
net_clp | integer | sí | ≥ 0, ≤ 999999999999 |
seller_of_record | consignante \ | retoma \ | automotora |
curl -X POST https://api.vitrinadev.com/api/v1/margin/preview \
-H "Authorization: Bearer $VITRINA_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicle_id": "e5e5e5e5-0000-4000-8000-000000000002",
"net_clp": 10000000
}'Ejemplo de respuesta (200)
{
"data": {
"vehicle_id": "e5e5e5e5-0000-4000-8000-000000000002",
"issued_at": "2026-09-29T15:00:00.000Z",
"period": "2026-09",
"regime": "consignacion",
"ingresos_clp": 800000,
"revenue_terms": {
"precio_venta_clp": 10000000,
"add_on_charges_clp": 0,
"pass_through_clp": 0,
"pass_through_paid_out_clp": 0,
"dealer_take_clp": 800000
},
"costo_venta_clp": 0,
"cost_terms": {
"payout_clp": 0,
"retenciones_clp": 0
},
"margen_bruto_clp": 800000,
"deductions": {
"comisiones_vendedores_clp": 0,
"gastos_adicionales_clp": 120000,
"gastos_unidad_clp": 120000,
"ingresos_unidad_clp": 0,
"desembolsos_add_on_clp": 0,
"gastos_fijos_clp": null
},
"margen_neto_clp": 680000,
"settlement": {
"settlement_mode": "stated_commission",
"amount_venta_clp": 10000000,
"monto_owner_clp": 9200000,
"deducciones_clp": 0
},
"cost_rollup": {
"acquisition_net_clp": 0,
"expense_total_clp": 120000,
"income_total_clp": 0,
"total_cost_clp": 120000,
"dealership_cost_clp": 120000,
"by_party": {
"automotora": {
"acquisition_clp": 0,
"expense_clp": 120000,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 120000
},
"dueno": {
"acquisition_clp": 0,
"expense_clp": 0,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 0
},
"cliente": {
"acquisition_clp": 0,
"expense_clp": 0,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 0
}
},
"entry_count": 2,
"complete": true,
"gaps": []
},
"complete": true,
"gaps": []
}
}Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429
GET /vehicles/{id}/deal-settlement
The Resumen del negocio of one unit
Everything about one car’s deal on one read: the published price, the discount (amount and %), the sale price, the purchase or consignment basis, the cost lines grouped by category with who absorbs each (automotora / dueno / cliente), the margin (the platform’s one margin definition, embedded whole with complete and gaps), the commission of each salesperson, the seller, the buyer and the buyer’s origin channel (origin: the sale note’s originating lead — its portal, else the channel of its conversation — then the origin a person declared on the buyer’s contact (origin_channel); null when neither is recorded, which every surface prints as «Sin registrar»), how many people asked about the unit, days in stock (entry → approval) and days to sell (first publication → sale).
Cifras del negocio are NET of IVA (ADR 0114 §2.2): pricing.sale_price_clp and every margin figure. Cifras del comprador are GROSS: pricing.total_clp (what the buyer paid, net + IVA), pricing.list_price_clp and pricing.discount_clp (measured against the published price, which includes IVA). Where both appear together an afecto sale reads «Precio de venta $5.806.723 neto · $6.910.000 con IVA» under a «Cifras sin IVA» heading.
Commissions are frozen when the sale is approved and never change (ADR 0114 §2.4), while margin.margen_bruto_clp is always current: when an approved sale’s commissions[].commission_basis_clp differs from it (it does for sales approved before retenciones joined the Costo de compra, §2.5), say so — «Base fijada al aprobar la venta ($X). Las comisiones aprobadas no se recalculan.» — and never present the difference as an error. The PDF and the planilla print that line.
The car’s lifecycle facts ride along: ingreso (how the car entered stock — compra, consignacion or retoma — the day, and the backing document with its folio; null = «Sin costo»), sale_note.emitted_by and sale_note.approved_by (who emitted and who approved the sale, by name; null = not recorded), basis.consignment.contract_id (where the Liquidación lives) and post_sale (the trámites the approved sale opened: total, pending, overdue on the dealership day and the next deadline; null until the sale is approved).
Cobros por cuenta del comprador (the transfer tax, registry fees, notary — charged at exact cost) are in no margin figure; pricing.pass_through_clp (cobrado) and pricing.pass_through_paid_out_clp (rendido) carry the memo line «Cobrado por cuenta del comprador $X · rendido $Y».
«Costo de compra» (margin.costo_venta_clp) is the nota de compra’s precio acordado: margin.cost_terms.payout_clp (paid to the seller) + margin.cost_terms.retenciones_clp (withheld and paid to third parties on the seller’s behalf), disclosed as «Precio acordado $X · incluye retenciones $Y». The retención lines stay in costs.categories for traceability with in_purchase_cost: true; they are not «Gastos de la unidad».
state is sold (the newest live nota de venta is approved), pending_approval (issued, not yet approved) or preview (no live nota de venta: the settlement at the published price, with no discount, add-ons or commissions, flagged by a preview gap). A figure that is not recorded is null, never 0. Requires dealership_economics:read.
| Parámetro | En | Tipo | Obligatorio | Restricciones |
|---|---|---|---|---|
id | path | uuid | sí |
curl https://api.vitrinadev.com/api/v1/vehicles/<id>/deal-settlement \
-H "Authorization: Bearer $VITRINA_KEY"Ejemplo de respuesta (200)
{
"data": {
"vehicle_id": "e5e5e5e5-0000-4000-8000-000000000001",
"as_of": "2026-09-28T15:00:00.000Z",
"state": "sold",
"vehicle": {
"make": "Toyota",
"model": "RAV4",
"version": "2.0 XLE CVT",
"year": 2021,
"registration_number": "PQRS-12",
"vin": "JTMW43FV0MD000001",
"color": "Gris plata",
"odometer_value": 48300,
"odometer_unit": "km",
"tenencia": "propio",
"status": "vendido",
"price_clp": 12490000
},
"sale_note": {
"id": "d4d4d4d4-0000-4000-8000-000000000001",
"display_id": "V-118",
"status": "approved",
"issued_at": "2026-09-19T13:00:00.000Z",
"approved_at": "2026-09-20T10:30:00.000Z",
"approved_by": {
"user_id": "a1a1a1a1-0000-4000-8000-000000000003",
"name": "Paz Ortiz"
},
"seller_of_record": "automotora"
},
"ingreso": {
"kind": "compra",
"acquired_on": "2026-07-24",
"document": {
"type": "purchase_note",
"id": "e5e5e5e5-0000-4000-8000-000000000001",
"folio": "P-34"
}
},
"pricing": {
"list_price_clp": 12490000,
"sale_price_clp": 11900000,
"tax_clp": 0,
"total_clp": 11900000,
"discount_clp": 590000,
"discount_pct": 4.7,
"add_on_charges_clp": 100000,
"pass_through_clp": 89900,
"pass_through_paid_out_clp": 89900
},
"basis": {
"regime": "propia",
"acquisition_net_clp": 9800000,
"consignment": null,
"settlement": null
},
"costs": {
"categories": [
{
"category_id": "9a9a9a9a-0000-4000-8000-000000000001",
"name": "Mecánica",
"kind": "expense",
"total_clp": 420000,
"by_party": {
"automotora": 420000,
"dueno": 0,
"cliente": 0
},
"line_count": 2,
"in_purchase_cost": false
},
{
"category_id": "9a9a9a9a-0000-4000-8000-000000000002",
"name": "Detailing",
"kind": "expense",
"total_clp": 315000,
"by_party": {
"automotora": 220000,
"dueno": 0,
"cliente": 95000
},
"line_count": 2,
"in_purchase_cost": false
},
{
"category_id": "9a9a9a9a-0000-4000-8000-000000000003",
"name": "Comisión de crédito",
"kind": "income",
"total_clp": 150000,
"by_party": {
"automotora": 150000,
"dueno": 0,
"cliente": 0
},
"line_count": 1,
"in_purchase_cost": false
}
],
"by_party": {
"automotora": {
"acquisition_clp": 9800000,
"expense_clp": 640000,
"purchase_retention_clp": 0,
"income_clp": 150000,
"total_clp": 10290000
},
"dueno": {
"acquisition_clp": 0,
"expense_clp": 0,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 0
},
"cliente": {
"acquisition_clp": 0,
"expense_clp": 95000,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 95000
}
},
"complete": true
},
"margin": {
"vehicle_id": "e5e5e5e5-0000-4000-8000-000000000001",
"sale_note_id": "d4d4d4d4-0000-4000-8000-000000000001",
"display_id": "V-118",
"salesperson_id": "a1a1a1a1-0000-4000-8000-000000000001",
"issued_at": "2026-09-19T13:00:00.000Z",
"period": "2026-09",
"regime": "propia",
"ingresos_clp": 12000000,
"revenue_terms": {
"precio_venta_clp": 11900000,
"add_on_charges_clp": 100000,
"pass_through_clp": 89900,
"pass_through_paid_out_clp": 89900,
"dealer_take_clp": null
},
"costo_venta_clp": 9800000,
"cost_terms": {
"payout_clp": 9800000,
"retenciones_clp": 0
},
"margen_bruto_clp": 2200000,
"deductions": {
"comisiones_vendedores_clp": 220000,
"gastos_adicionales_clp": 490000,
"gastos_unidad_clp": 640000,
"ingresos_unidad_clp": 150000,
"desembolsos_add_on_clp": 0,
"gastos_fijos_clp": null
},
"margen_neto_clp": 1490000,
"settlement": null,
"cost_rollup": {
"acquisition_net_clp": 9800000,
"expense_total_clp": 735000,
"income_total_clp": 150000,
"total_cost_clp": 10385000,
"dealership_cost_clp": 10290000,
"by_party": {
"automotora": {
"acquisition_clp": 9800000,
"expense_clp": 640000,
"purchase_retention_clp": 0,
"income_clp": 150000,
"total_clp": 10290000
},
"dueno": {
"acquisition_clp": 0,
"expense_clp": 0,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 0
},
"cliente": {
"acquisition_clp": 0,
"expense_clp": 95000,
"purchase_retention_clp": 0,
"income_clp": 0,
"total_clp": 95000
}
},
"entry_count": 5,
"complete": true,
"gaps": []
},
"complete": true,
"gaps": []
},
"commissions": [
{
"participation_id": "5d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"user_id": "a1a1a1a1-0000-4000-8000-000000000001",
"name": "Carla Rojas",
"role": "closer",
"commission_rate_bp": 800,
"commission_basis_clp": 2200000,
"commission_clp": 176000
},
{
"participation_id": "6e2d3c4b-5f60-4b7c-9d8e-0f1a2b3c4d5e",
"user_id": "a1a1a1a1-0000-4000-8000-000000000002",
"name": "Diego Muñoz",
"role": "collaborator",
"commission_rate_bp": 200,
"commission_basis_clp": 2200000,
"commission_clp": 44000
}
],
"salesperson": {
"user_id": "a1a1a1a1-0000-4000-8000-000000000001",
"name": "Carla Rojas"
},
"buyer": {
"contact_id": "c3c3c3c3-0000-4000-8000-000000000001",
"name": "Ana Pérez Soto"
},
"origin": {
"source": "mercadolibre",
"channel": "whatsapp",
"label": "Mercado Libre",
"via": "lead",
"lead_id": "b2b2b2b2-0000-4000-8000-000000000001",
"conversation_id": "f6f6f6f6-0000-4000-8000-000000000001"
},
"interest": {
"distinct_contacts": 14,
"named_leads": 16,
"anonymous_interest": 5,
"first_contact_at": "2026-08-02T14:10:00.000Z",
"last_contact_at": "2026-09-18T21:45:00.000Z"
},
"post_sale": {
"total": 3,
"pending": 1,
"overdue": 0,
"next_due_on": "2026-10-20",
"completed_at": null
},
"timeline": {
"entered_stock_at": "2026-07-24T12:00:00.000Z",
"first_published_at": "2026-07-26T15:00:00.000Z",
"sold_at": "2026-09-19T13:00:00.000Z",
"approved_at": "2026-09-20T10:30:00.000Z",
"days_in_stock": 58,
"days_to_sell": 55
},
"complete": true,
"gaps": []
}
}Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429
GET /vehicles/{id}/deal-settlement/export
Export the Resumen del negocio (xlsx / csv)
The same Resumen del negocio as a planilla. xlsx (default) carries three sheets — Resumen (the result walk, net of IVA — its Monto sin IVA column sums to the Utilidad; an afecto sale’s gross price, the published price and the discount are stated as facts, never in that column — and the deal’s facts), Costos (by category and party) and Comisiones (per salesperson, with a note under the table when an approved sale’s frozen commission base differs from the current Margen bruto); csv carries the Resumen. Requires dealership_economics:read.
| Parámetro | En | Tipo | Obligatorio | Restricciones |
|---|---|---|---|---|
id | path | uuid | sí | |
format | query | xlsx \ | csv | no |
curl https://api.vitrinadev.com/api/v1/vehicles/<id>/deal-settlement/export \
-H "Authorization: Bearer $VITRINA_KEY"Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429
GET /vehicles/{id}/deal-settlement/pdf
Print the Resumen del negocio (PDF)
The Resumen del negocio as a PDF (application/pdf, served inline): the workspace’s default deal_settlement template — or template_id — filled with the deal’s facts, followed by a fixed table of the result walk headed «Cifras sin IVA», the costs by category and who absorbs them, and the commissions. Every figure of the walk is net of IVA (ADR 0114 §2.2); an afecto sale’s price reads «$5.806.723 neto · $6.910.000 con IVA», and no gross figure is a step of the walk. With no live template it prints the standard text. A missing fact prints «no registrado»; nothing is refused. A preview carries a «VISTA PREVIA» banner. X-Template-Version names the prose used. Requires dealership_economics:read.
| Parámetro | En | Tipo | Obligatorio | Restricciones |
|---|---|---|---|---|
id | path | uuid | sí | |
template_id | query | uuid | no |
curl https://api.vitrinadev.com/api/v1/vehicles/<id>/deal-settlement/pdf \
-H "Authorization: Bearer $VITRINA_KEY"Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429