Vehículos

Descarga la proyección completa de la API pública: openapi.json.

GET /vehiclesCopiar el enlace a esta sección

Search the tenant vehicle stock (filters + free text)

FIELD-LEVEL COST OMISSION (ERP S3-6): the per-unit money position — floor_price_clp (precio piso) — is withheld unless the caller holds dealership_economics:read. The key is ABSENT from the response object, not null: a caller who checks 'floor_price_clp' in body sees it was never offered. price_clp (the asking price) is unaffected — it is the one money figure about a unit that is meant to be seen. The scope is NOT an alternative to marketplace:read (requireScope ORs its varargs, which would widen this route rather than narrow the field); it is an addition.

TENENCIA (ADR 0025). tenencia filters the vehicle-level discriminator (propio | consignacion); consignacion_modalidad narrows a consignación by its ACTIVE contract — en_local, virtual (the car stays with its dueño) or sin_contrato (consigned with no contract in estado=activo on file). consignacion_modalidad is REFUSED with 400 unless tenencia=consignacion came with it: it names a kind of consignación, so it is only answerable about one.

Every row carries tenencia and not_on_lot — the latter true iff an ACTIVE contract with modalidad=virtual exists, resolved in ONE batched query for the page (never per row). not_on_lot is the flag a test-drive or walking-sheet surface acts on; tenencia alone cannot answer it, because the modalidad lives on the contract.

POSIBLE DUPLICADO. Every row carries possible_duplicate: true when an open duplicate candidate names the car (same photos and specs as another car, plates one character apart or an implausible VIN). The pairs are at GET /vehicles/\{id\}/duplicate-candidates.

⚠ tenencia=propio IS THE COLUMN DEFAULT, not a recorded decision: that cohort includes every unit nobody has classified yet. Do not word it as "comprado".

Phase 2 (tenencia_source): tenencia_source COMPOSES with tenencia rather than narrowing it — ?tenencia=propio&tenencia_source=decided is "propio, and a person or a document actually settled that" (decided ⇒ tenencia_source <> 'default'); document / declared / default match the column exactly. See POST /vehicles/tenencia for how a declared row is produced.

SIN COSTO (ADR 0114 §8). A car that entered without a compra (nota de compra), a consignación (contrato) or a parte de pago (nota de venta) has no acquisition, so nothing records what it cost. Every row carries sin_costo: true for such a unit (any status), and view=sin_costo lists the pile still on the floor — active, not vendido, no acquisition; the SAME predicate as the sin_costo count on GET /vehicles/stats and the stock_without_cost dealer alert. It is never a gate: bulk imports and migrations land cars here on purpose. sin_costo is a statement about the cost basis and follows the cost omission above: ABSENT without dealership_economics:read.

MANDATO SIN FIRMAR (ADR 0114 §5). view=mandato_sin_firmar lists the cars whose consignación (activa or vendida) has an emitted mandato and no signed copy filed in the expediente — the SAME predicate as the mandato_sin_firmar count on GET /vehicles/stats. Never a gate, and no longer a dealer alert (retired 2026-11-10: it is a filter you open, not a to-do).

curl https://api.vitrinadev.com/api/v1/vehicles \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "e1e1e1e1-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "origin_integration_id": null,
      "source": "manual",
      "make": "Toyota",
      "model": "Corolla",
      "version": "1.8 XEI CVT",
      "year": 2022,
      "title": null,
      "short_title": null,
      "price_amount": 13990000,
      "price_clp": 13990000,
      "watch_enabled": false,
      "floor_price_clp": null,
      "target_position": null,
      "abono_amount_clp": 300000,
      "merged_into": null,
      "deleted_at": null,
      "price_currency": "CLP",
      "odometer_value": 42500,
      "odometer_unit": "KM",
      "fuel_type": "Bencina",
      "gear_type": "Automática",
      "body_style": "Sedán",
      "color": "Gris",
      "doors": 4,
      "registration_number": "FGXY21",
      "vin": "9BWZZZ377NP004512",
      "plate_normalized": "FGXY21",
      "listing_type": "Usado",
      "record_type": null,
      "type": "Car",
      "merch_label": null,
      "featured_at": null,
      "vehicle_type": "auto",
      "sale_status": null,
      "status": "disponible",
      "reserved_at": null,
      "reserved_by_name": null,
      "sold_at": null,
      "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
      "estacionamiento": null,
      "description": "Mantenimientos al día en concesionario.",
      "photos": [
        {
          "url": "https://images.example.cl/corolla-2022-1.jpg",
          "order": 0
        }
      ],
      "attributes": {},
      "tags": [],
      "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
      "active": true,
      "protected_fields": [],
      "deactivated_by": null,
      "tenencia": "propio",
      "tenencia_source": "default",
      "tenencia_declared_by": null,
      "tenencia_declared_at": null,
      "iva_regime": null,
      "keys_count": null,
      "municipalidad_comuna_code": null,
      "last_service_date": null,
      "service_odometer_km": null,
      "published_at": null,
      "last_seen_at": null,
      "created_at": "2026-09-15T18:34:48.575Z",
      "updated_at": "2026-09-15T18:34:48.575Z",
      "live_sale_note": null,
      "active_reservation": null,
      "sin_costo": true,
      "not_on_lot": false
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "offset": 0
    },
    "total": 1
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehiclesCopiar el enlace a esta sección

Create a vehicle (manual stock)

plate_normalized is server-derived from registration_number; a plate already claimed by another ACTIVE vehicle of the tenant returns 409 (conflicto de patente).

Plate format. For a road-registered type (auto, camion) a non-empty registration_number must be a Chilean plate: AB1234 (old series), BCDF12 (new series: consonants only, no M/N/Q), or for motorcycles AB123 / BCD12; separators, case and a trailing registry check digit are tolerated. Anything else is a 400 VALIDATION_ERROR with details.reason = "plate_format_invalid" and a Spanish fieldErrors.registration_number. An empty value and a pending declaration («en trámite») stay legal; maquinaria/nautico are not checked. Stock syncs from portals and feeds do not pass through this check.

Publish in the same call (publish_to). Optional. Name the marketplaces this vehicle should go to — portal slugs such as chileautos / mercadolibre, or integration ids from GET /marketplaces — and it is published right after it is saved, through the same path as POST /vehicles/{id}/publish. Omitted or [] saves only; there is no default. Every entry is validated first: a portal with no connected account, a slug matching several accounts, or an id from another workspace answers 422 and nothing is saved. Once saved, the vehicle stays saved: a portal that fails to publish is an error entry in publications, never a failed request (still 201). The response then carries publications, one PublishOutcome per account (published, pending for queued transports such as chileautos_panel, already_published, or error with the reason). publications is absent when publish_to was not sent.

Sanity range. A price fans out to every connected portal, so a typo is stopped here. price_amount must be between 100.000 and 2.000.000.000 CLP (a UF price is bounded at the day's UF; other currencies are not bounded) and odometer_value between 0 and 2.000.000; null clears either and is always accepted. Outside the range: 422 VEHICLE_VALUE_OUT_OF_RANGE, with a Spanish message, field_errors.<field> and details.violations[] (field, reason = price_out_of_range | km_out_of_range, value, min, max, currency). A price change beyond 10x up or down from the current price answers 422 PRICE_CHANGE_CONFIRMATION_REQUIRED (details.reason = large_price_change, current_price, requested_price, currency, factor, confirm_flag) unless the body carries confirm_large_price_change: true; ask the user, then resend the same body with it. Nothing is written on either 422.

Normalization and catalog_match. On create and update, make and model that equal an entry of GET /vehicles/catalog/brands and /catalog/models up to case, accents, spaces and hyphens are stored in the catalog's spelling ("toyota" → "Toyota", "mercedes benz" → "Mercedes-Benz", "rav 4" → "RAV4"); fuel_type, gear_type and body_style are stored as vocabulary codes ("Bencina" → gasolina, "Automática" → automatica, "Station Wagon" → wagon; codes: fuel gasolina|diesel|hibrido|electrico|gnc|glp|otro, gear mecanica|automatica|otro, body sedan|hatchback|suv|camioneta|coupe|wagon|furgon|convertible|minivan|otro). Nothing is invented: a value with no match is stored exactly as sent. The response (and GET /vehicles/{id}) carries catalog_match: make / model are matched | unmatched | missing (not_applicable for a non-auto vehicle_type); version adds approximate (word overlap with a catalog version, same displacement) and catalog_version names the catalog version it matched or most resembles; fuel_type / gear_type / body_style are matched | unmatched | missing; warnings[] lists \{ field, code, message \} for everything not matched, with a Spanish message ready to show (codes: make_missing, make_not_in_catalog, model_missing, model_not_in_catalog, version_approximate, version_not_in_catalog, fuel_type_not_recognized, gear_type_not_recognized, body_style_not_recognized). A make or model that is not matched still saves, but Chileautos publishes it without a technical sheet (ficha). catalog_match is null only when the catalog could not be loaded. Example of an unmatched push: {"make":"matched","model":"unmatched","version":"unmatched","catalog_version":null,"fuel_type":"unmatched","gear_type":"matched","body_style":"missing","warnings":[{"field":"model","code":"model_not_in_catalog","message":"Modelo 'Rav-4 xx' no está en el catálogo de Toyota (GET /vehicles/catalog/models); Chileautos lo publicará sin ficha."},{"field":"fuel_type","code":"fuel_type_not_recognized","message":"Combustible 'Hidrógeno' no se reconoce; valores aceptados: gasolina, diesel, hibrido, electrico, gnc, glp, otro."}]}

Photos are re-hosted. A photos[].url that is not already a Vitrina media url is copied, shortly AFTER the response, onto the Vitrina media host and the stored url is rewritten to that copy, in the same order with every other photo field kept. The copy is normalized: EXIF orientation applied to the pixels, EXIF/GPS/XMP removed, long edge capped at 2560 px, re-encoded only when it had to change. Only public https urls are fetched (private/internal addresses are refused) and only image bodies up to 12 MB; a photo that cannot be fetched keeps the url you sent. Re-sending a url that was already copied is stored as the copy straight away, so pushing the same gallery again is not a change. The response of THIS call still shows the urls as sent; read the vehicle again to see the rewritten ones. The rewrite advances updated_at but writes no history entry, triggers no portal republish and emits no webhook.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "price_amount": 13990000,
    "odometer_value": 42500,
    "fuel_type": "Bencina",
    "gear_type": "Automática",
    "body_style": "Sedán",
    "color": "Gris",
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "publish_to": [
      "chileautos",
      "mercadolibre"
    ]
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "origin_integration_id": null,
    "source": "manual",
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "title": null,
    "short_title": null,
    "price_amount": 13990000,
    "price_clp": 13990000,
    "watch_enabled": false,
    "floor_price_clp": null,
    "target_position": null,
    "abono_amount_clp": 300000,
    "merged_into": null,
    "deleted_at": null,
    "price_currency": "CLP",
    "odometer_value": 42500,
    "odometer_unit": "KM",
    "fuel_type": "gasolina",
    "gear_type": "automatica",
    "body_style": "sedan",
    "color": "Gris",
    "doors": 4,
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "plate_normalized": "FGXY21",
    "listing_type": "Usado",
    "record_type": null,
    "type": "Car",
    "merch_label": null,
    "featured_at": null,
    "vehicle_type": "auto",
    "sale_status": null,
    "status": "disponible",
    "reserved_at": null,
    "reserved_by_name": null,
    "sold_at": null,
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "estacionamiento": null,
    "description": "Mantenimientos al día en concesionario.",
    "photos": [
      {
        "url": "https://images.example.cl/corolla-2022-1.jpg",
        "order": 0
      }
    ],
    "attributes": {},
    "tags": [],
    "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
    "active": true,
    "protected_fields": [],
    "deactivated_by": null,
    "tenencia": "propio",
    "tenencia_source": "default",
    "tenencia_declared_by": null,
    "tenencia_declared_at": null,
    "iva_regime": null,
    "keys_count": null,
    "municipalidad_comuna_code": null,
    "last_service_date": null,
    "service_odometer_km": null,
    "published_at": null,
    "last_seen_at": null,
    "created_at": "2026-09-15T18:34:48.575Z",
    "updated_at": "2026-09-15T18:34:48.575Z",
    "live_sale_note": null,
    "active_reservation": null,
    "sin_costo": true,
    "not_on_lot": false,
    "catalog_match": {
      "make": "matched",
      "model": "matched",
      "version": "approximate",
      "catalog_version": "1.8 XEI CVT",
      "fuel_type": "matched",
      "gear_type": "matched",
      "body_style": "matched",
      "warnings": [
        {
          "field": "version",
          "code": "version_approximate",
          "message": "Versión '1.8 XEI CVT full' no coincide exactamente con el catálogo; la más parecida es '1.8 XEI CVT'."
        }
      ]
    },
    "publications": [
      {
        "integration_id": "33333333-0000-4000-8000-000000000003",
        "provider": "chileautos_panel",
        "status": "pending",
        "external_id": null,
        "publication": {
          "id": "88888888-0000-4000-8000-000000000003",
          "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
          "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
          "marketplace_account_id": "33333333-0000-4000-8000-000000000003",
          "provider": "chileautos_panel",
          "external_id": null,
          "status": "pending",
          "origin": "vitrina",
          "permalink": null,
          "last_synced_at": null,
          "last_published_at": null,
          "last_error": null,
          "close_retry_count": 0,
          "portal_state": null,
          "portal_state_at": null,
          "last_push_status": "updated",
          "last_push_at": "2026-09-19T09:58:00.000Z",
          "last_push_error": null,
          "last_push_fields": [
            "priceAmount"
          ],
          "push_delivery": "api",
          "raw_provider_payload": null,
          "created_at": "2026-09-16T09:00:00.000Z",
          "updated_at": "2026-09-19T10:00:00.000Z"
        }
      },
      {
        "integration_id": "33333333-0000-4000-8000-000000000001",
        "provider": "mercadolibre",
        "status": "published",
        "external_id": "MLC-1234567890",
        "publication": {
          "id": "88888888-0000-4000-8000-000000000001",
          "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
          "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
          "marketplace_account_id": "33333333-0000-4000-8000-000000000001",
          "provider": "mercadolibre",
          "external_id": "MLC-1234567890",
          "status": "published",
          "origin": "vitrina",
          "permalink": "https://articulo.mercadolibre.cl/MLC-1234567890",
          "last_synced_at": "2026-09-19T10:00:00.000Z",
          "last_published_at": "2026-09-16T09:00:00.000Z",
          "last_error": null,
          "close_retry_count": 0,
          "portal_state": "active",
          "portal_state_at": "2026-09-19T10:00:00.000Z",
          "last_push_status": "updated",
          "last_push_at": "2026-09-19T09:58:00.000Z",
          "last_push_error": null,
          "last_push_fields": [
            "priceAmount"
          ],
          "push_delivery": "api",
          "raw_provider_payload": null,
          "created_at": "2026-09-16T09:00:00.000Z",
          "updated_at": "2026-09-19T10:00:00.000Z"
        }
      }
    ]
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 422 · 429

DELETE /vehicles/{id}Copiar el enlace a esta sección

Delete a vehicle

Soft-delete: the row and its history remain, deleted_at is stamped, and it drops out of every default list and out of the public stock API. Before the soft-delete it schedules the close of every live ad on every connected portal (the same retry-backed pipeline as POST /vehicles/\{id\}/close-ads). A vehicle a negocio holds (reservado, vendido, or carrying a live nota de venta) cannot be deleted: 409 with details.code: "vehicle_held_by_negocio". Deleting an already deleted vehicle is a 204 no-op.

curl -X DELETE https://api.vitrinadev.com/api/v1/vehicles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Responde: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}Copiar el enlace a esta sección

Get a vehicle

FIELD-LEVEL COST OMISSION (ERP S3-6): the per-unit money position — floor_price_clp (precio piso) — is withheld unless the caller holds dealership_economics:read. The key is ABSENT from the response object, not null: a caller who checks 'floor_price_clp' in body sees it was never offered. price_clp (the asking price) is unaffected — it is the one money figure about a unit that is meant to be seen. The scope is NOT an alternative to marketplace:read (requireScope ORs its varargs, which would widen this route rather than narrow the field); it is an addition.

TENENCIA (ADR 0025): the response carries tenencia and not_on_lot — the SAME two signals the Stock list row carries (composeStockRows), resolved the SAME way (consignmentRepo.listActiveModalidadByVehicleIds + isOffLot), so the ficha can never disagree with the list about which cars are off the lot. not_on_lot is true iff an ACTIVE contract with modalidad=virtual exists; tenencia alone cannot answer it, because the modalidad lives on the contract.

Normalization and catalog_match. On create and update, make and model that equal an entry of GET /vehicles/catalog/brands and /catalog/models up to case, accents, spaces and hyphens are stored in the catalog's spelling ("toyota" → "Toyota", "mercedes benz" → "Mercedes-Benz", "rav 4" → "RAV4"); fuel_type, gear_type and body_style are stored as vocabulary codes ("Bencina" → gasolina, "Automática" → automatica, "Station Wagon" → wagon; codes: fuel gasolina|diesel|hibrido|electrico|gnc|glp|otro, gear mecanica|automatica|otro, body sedan|hatchback|suv|camioneta|coupe|wagon|furgon|convertible|minivan|otro). Nothing is invented: a value with no match is stored exactly as sent. The response (and GET /vehicles/{id}) carries catalog_match: make / model are matched | unmatched | missing (not_applicable for a non-auto vehicle_type); version adds approximate (word overlap with a catalog version, same displacement) and catalog_version names the catalog version it matched or most resembles; fuel_type / gear_type / body_style are matched | unmatched | missing; warnings[] lists \{ field, code, message \} for everything not matched, with a Spanish message ready to show (codes: make_missing, make_not_in_catalog, model_missing, model_not_in_catalog, version_approximate, version_not_in_catalog, fuel_type_not_recognized, gear_type_not_recognized, body_style_not_recognized). A make or model that is not matched still saves, but Chileautos publishes it without a technical sheet (ficha). catalog_match is null only when the catalog could not be loaded. Example of an unmatched push: {"make":"matched","model":"unmatched","version":"unmatched","catalog_version":null,"fuel_type":"unmatched","gear_type":"matched","body_style":"missing","warnings":[{"field":"model","code":"model_not_in_catalog","message":"Modelo 'Rav-4 xx' no está en el catálogo de Toyota (GET /vehicles/catalog/models); Chileautos lo publicará sin ficha."},{"field":"fuel_type","code":"fuel_type_not_recognized","message":"Combustible 'Hidrógeno' no se reconoce; valores aceptados: gasolina, diesel, hibrido, electrico, gnc, glp, otro."}]}

curl https://api.vitrinadev.com/api/v1/vehicles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "origin_integration_id": null,
    "source": "manual",
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "title": null,
    "short_title": null,
    "price_amount": 13990000,
    "price_clp": 13990000,
    "watch_enabled": false,
    "floor_price_clp": null,
    "target_position": null,
    "abono_amount_clp": 300000,
    "merged_into": null,
    "deleted_at": null,
    "price_currency": "CLP",
    "odometer_value": 42500,
    "odometer_unit": "KM",
    "fuel_type": "gasolina",
    "gear_type": "automatica",
    "body_style": "sedan",
    "color": "Gris",
    "doors": 4,
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "plate_normalized": "FGXY21",
    "listing_type": "Usado",
    "record_type": null,
    "type": "Car",
    "merch_label": null,
    "featured_at": null,
    "vehicle_type": "auto",
    "sale_status": null,
    "status": "disponible",
    "reserved_at": null,
    "reserved_by_name": null,
    "sold_at": null,
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "estacionamiento": null,
    "description": "Mantenimientos al día en concesionario.",
    "photos": [
      {
        "url": "https://images.example.cl/corolla-2022-1.jpg",
        "order": 0
      }
    ],
    "attributes": {},
    "tags": [],
    "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
    "active": true,
    "protected_fields": [],
    "deactivated_by": null,
    "tenencia": "propio",
    "tenencia_source": "default",
    "tenencia_declared_by": null,
    "tenencia_declared_at": null,
    "iva_regime": null,
    "keys_count": null,
    "municipalidad_comuna_code": null,
    "last_service_date": null,
    "service_odometer_km": null,
    "published_at": null,
    "last_seen_at": null,
    "created_at": "2026-09-15T18:34:48.575Z",
    "updated_at": "2026-09-15T18:34:48.575Z",
    "live_sale_note": null,
    "active_reservation": null,
    "sin_costo": true,
    "not_on_lot": false,
    "catalog_match": {
      "make": "matched",
      "model": "matched",
      "version": "approximate",
      "catalog_version": "1.8 XEI CVT",
      "fuel_type": "matched",
      "gear_type": "matched",
      "body_style": "matched",
      "warnings": [
        {
          "field": "version",
          "code": "version_approximate",
          "message": "Versión '1.8 XEI CVT full' no coincide exactamente con el catálogo; la más parecida es '1.8 XEI CVT'."
        }
      ]
    }
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /vehicles/{id}Copiar el enlace a esta sección

Update a vehicle

Updating registration_number re-derives plate_normalized; a collision with another ACTIVE vehicle of the tenant returns 409 (conflicto de patente). A CHANGED plate is held to the same Chilean formats as on POST /vehicles (400 plate_format_invalid); re-sending the stored value unchanged is never refused.

publish_to only ADDS portals. Same contract as on POST /vehicles (validated before the edit is written; 422 writes nothing; a portal failure is an error entry in publications, never a failed request). A portal where the vehicle is already live or has a queued publish is a no-op (already_published) — never a second ad, so an ERP may safely retry. A portal LEFT OUT of publish_to is NOT unpublished: removal is DELETE /vehicles/{id}/publications/{pubId}. A body with only publish_to publishes without editing the vehicle.

Sanity range. A price fans out to every connected portal, so a typo is stopped here. price_amount must be between 100.000 and 2.000.000.000 CLP (a UF price is bounded at the day's UF; other currencies are not bounded) and odometer_value between 0 and 2.000.000; null clears either and is always accepted. Outside the range: 422 VEHICLE_VALUE_OUT_OF_RANGE, with a Spanish message, field_errors.<field> and details.violations[] (field, reason = price_out_of_range | km_out_of_range, value, min, max, currency). A price change beyond 10x up or down from the current price answers 422 PRICE_CHANGE_CONFIRMATION_REQUIRED (details.reason = large_price_change, current_price, requested_price, currency, factor, confirm_flag) unless the body carries confirm_large_price_change: true; ask the user, then resend the same body with it. Nothing is written on either 422.

Normalization and catalog_match. On create and update, make and model that equal an entry of GET /vehicles/catalog/brands and /catalog/models up to case, accents, spaces and hyphens are stored in the catalog's spelling ("toyota" → "Toyota", "mercedes benz" → "Mercedes-Benz", "rav 4" → "RAV4"); fuel_type, gear_type and body_style are stored as vocabulary codes ("Bencina" → gasolina, "Automática" → automatica, "Station Wagon" → wagon; codes: fuel gasolina|diesel|hibrido|electrico|gnc|glp|otro, gear mecanica|automatica|otro, body sedan|hatchback|suv|camioneta|coupe|wagon|furgon|convertible|minivan|otro). Nothing is invented: a value with no match is stored exactly as sent. The response (and GET /vehicles/{id}) carries catalog_match: make / model are matched | unmatched | missing (not_applicable for a non-auto vehicle_type); version adds approximate (word overlap with a catalog version, same displacement) and catalog_version names the catalog version it matched or most resembles; fuel_type / gear_type / body_style are matched | unmatched | missing; warnings[] lists \{ field, code, message \} for everything not matched, with a Spanish message ready to show (codes: make_missing, make_not_in_catalog, model_missing, model_not_in_catalog, version_approximate, version_not_in_catalog, fuel_type_not_recognized, gear_type_not_recognized, body_style_not_recognized). A make or model that is not matched still saves, but Chileautos publishes it without a technical sheet (ficha). catalog_match is null only when the catalog could not be loaded. Example of an unmatched push: {"make":"matched","model":"unmatched","version":"unmatched","catalog_version":null,"fuel_type":"unmatched","gear_type":"matched","body_style":"missing","warnings":[{"field":"model","code":"model_not_in_catalog","message":"Modelo 'Rav-4 xx' no está en el catálogo de Toyota (GET /vehicles/catalog/models); Chileautos lo publicará sin ficha."},{"field":"fuel_type","code":"fuel_type_not_recognized","message":"Combustible 'Hidrógeno' no se reconoce; valores aceptados: gasolina, diesel, hibrido, electrico, gnc, glp, otro."}]}

Photos are re-hosted. A photos[].url that is not already a Vitrina media url is copied, shortly AFTER the response, onto the Vitrina media host and the stored url is rewritten to that copy, in the same order with every other photo field kept. The copy is normalized: EXIF orientation applied to the pixels, EXIF/GPS/XMP removed, long edge capped at 2560 px, re-encoded only when it had to change. Only public https urls are fetched (private/internal addresses are refused) and only image bodies up to 12 MB; a photo that cannot be fetched keeps the url you sent. Re-sending a url that was already copied is stored as the copy straight away, so pushing the same gallery again is not a change. The response of THIS call still shows the urls as sent; read the vehicle again to see the rewritten ones. The rewrite advances updated_at but writes no history entry, triggers no portal republish and emits no webhook.

Cuerpo

curl -X PUT https://api.vitrinadev.com/api/v1/vehicles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 13490000
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "origin_integration_id": null,
    "source": "manual",
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "title": null,
    "short_title": null,
    "price_amount": 13490000,
    "price_clp": 13490000,
    "watch_enabled": false,
    "floor_price_clp": null,
    "target_position": null,
    "abono_amount_clp": 300000,
    "merged_into": null,
    "deleted_at": null,
    "price_currency": "CLP",
    "odometer_value": 42500,
    "odometer_unit": "KM",
    "fuel_type": "gasolina",
    "gear_type": "automatica",
    "body_style": "sedan",
    "color": "Gris",
    "doors": 4,
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "plate_normalized": "FGXY21",
    "listing_type": "Usado",
    "record_type": null,
    "type": "Car",
    "merch_label": null,
    "featured_at": null,
    "vehicle_type": "auto",
    "sale_status": null,
    "status": "disponible",
    "reserved_at": null,
    "reserved_by_name": null,
    "sold_at": null,
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "estacionamiento": null,
    "description": "Mantenimientos al día en concesionario.",
    "photos": [
      {
        "url": "https://images.example.cl/corolla-2022-1.jpg",
        "order": 0
      }
    ],
    "attributes": {},
    "tags": [],
    "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
    "active": true,
    "protected_fields": [],
    "deactivated_by": null,
    "tenencia": "propio",
    "tenencia_source": "default",
    "tenencia_declared_by": null,
    "tenencia_declared_at": null,
    "iva_regime": null,
    "keys_count": null,
    "municipalidad_comuna_code": null,
    "last_service_date": null,
    "service_odometer_km": null,
    "published_at": null,
    "last_seen_at": null,
    "created_at": "2026-09-15T18:34:48.575Z",
    "updated_at": "2026-09-15T18:34:48.575Z",
    "live_sale_note": null,
    "active_reservation": null,
    "sin_costo": true,
    "not_on_lot": false,
    "catalog_match": {
      "make": "matched",
      "model": "matched",
      "version": "approximate",
      "catalog_version": "1.8 XEI CVT",
      "fuel_type": "matched",
      "gear_type": "matched",
      "body_style": "matched",
      "warnings": [
        {
          "field": "version",
          "code": "version_approximate",
          "message": "Versión '1.8 XEI CVT full' no coincide exactamente con el catálogo; la más parecida es '1.8 XEI CVT'."
        }
      ]
    }
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 422 · 429

GET /vehicles/{id}/activityCopiar el enlace a esta sección

This car’s lead timeline

Every named lead that asked about this vehicle, merged with its anonymous Yapo phone-reveals, newest first. This is the car’s HISTORY, so unlike /interest a sold vehicle keeps its timeline.

Each lead row carries conversation_id: the chat to open for that person (the lead's own conversation, else the contact's most recent one, e.g. the first-touch WhatsApp after a portal inquiry). Null when there is none.

The Stock detail screen merges this with /vehicles/\{id\}/history (the change log) into one "Leads y cambios" feed — they are two endpoints because they are two different kinds of event. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/activity \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "kind": "lead",
      "contact_id": "22222222-0000-4000-8000-000000000001",
      "lead_id": "99999999-0000-4000-8000-000000000002",
      "conversation_id": "99999999-0000-4000-8000-000000000003",
      "portal": "website",
      "at": "2026-09-19T15:30:00.000Z"
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/busquedasCopiar el enlace a esta sección

Who is waiting for this car (ADR 0109 §4)

Which open Búsquedas (customer wants) does THIS unit answer, graded live — calza (every bound holds) or calza_parcial (the name and years hold; the budget or the kilometres are over by no more than the workspace tolerance, with the difference stated). A want recorded AFTER the car arrived is never missed — this grades the CURRENT row on every call, not an activity log from intake.

notice is what became of the notice about THIS car, or null when the customer has not heard about it yet. Búsqueda notices go out automatically. notice.state is notified or dismissed (the pair was considered and deliberately not sent); notice.at is when; notice.channel is the channel it went out on (whatsapp, email, instagram, voice, or human_self when the want was reserved by a member and only that member was told). notice.conversation_id + notice.message_id open the exact thread and message the notice went out in — both null when the notice has no thread of its own. notice.replied_at is the customer’s first message in that thread after the notice (null = no reply yet, or no thread to read). already_notified is notice != null.

⚠ SCOPE IS followups:read, not marketplace:read — this reports CRM demand, not stock. ⚠ TENANT-WIDE, not row-visibility-gated: a shared review sheet about a unit in the shared stock. contact.name / contact.phone are further gated on contacts:read — a caller without it still sees the full worklist, minus the customer’s name and phone. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/busquedas \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "subscription_id": "5b5b5b5b-0000-4000-8000-000000000001",
      "contact_id": "22222222-0000-4000-8000-000000000001",
      "contact": {
        "id": "22222222-0000-4000-8000-000000000001",
        "name": "Camila Rojas",
        "phone": "+56912345678"
      },
      "lead_id": "99999999-0000-4000-8000-000000000001",
      "owner": {
        "user_id": "33333333-0000-4000-8000-000000000001",
        "name": "Valentina Soto",
        "avatar_url": null
      },
      "status": "active",
      "trigger_key": "vehicle_in_stock",
      "criteria": {
        "make": "Mazda",
        "model": "CX-30",
        "year_min": 2021,
        "max_price": 18000000
      },
      "note": null,
      "sought_label": "Mazda CX-30 · 2021 en adelante",
      "expires_at": "2026-10-19T12:00:00.000Z",
      "days_left": 27,
      "notice_count": 0,
      "verdict": "calza_parcial",
      "differences": [
        {
          "bound": "budget",
          "stated": 18000000,
          "actual": 18900000,
          "over": 900000,
          "overFraction": 0.05,
          "text": "Está $900.000 sobre el presupuesto de $18.000.000"
        }
      ],
      "already_notified": false,
      "notice": null
    },
    {
      "subscription_id": "5b5b5b5b-0000-4000-8000-000000000002",
      "contact_id": "11111111-0000-4000-8000-000000000002",
      "contact": {
        "id": "11111111-0000-4000-8000-000000000002",
        "name": "Tomás Herrera",
        "phone": "+56911112222"
      },
      "lead_id": null,
      "owner": null,
      "status": "open",
      "trigger_key": "vehicle_in_stock",
      "criteria": {
        "make": "Mazda",
        "model": "CX-30"
      },
      "note": null,
      "sought_label": "Mazda CX-30",
      "expires_at": "2026-12-01T12:00:00.000Z",
      "days_left": 70,
      "notice_count": 1,
      "verdict": "calza",
      "differences": [],
      "already_notified": true,
      "notice": {
        "state": "notified",
        "at": "2026-09-29T17:02:00.000Z",
        "channel": "whatsapp",
        "conversation_id": "7c7c7c7c-0000-4000-8000-000000000001",
        "message_id": "8d8d8d8d-0000-4000-8000-000000000001",
        "replied_at": "2026-09-29T17:10:41.000Z"
      }
    }
  ],
  "meta": {
    "total": 2
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/close-adsCopiar el enlace a esta sección

Close all of a vehicle’s ads

Cierre de avisos: removes the vehicle from EVERY connected portal at once. Contrast DELETE /vehicles/\{id\}/publications/\{pubId\}, which removes one publication synchronously — this closes the whole vehicle and is enqueued.

Answers \{ enqueued: true, vehicle_id \} immediately. That is an acknowledgement, not a result: the retry-backed pipeline does the portal work afterwards because portal removal fails often enough that doing it inline would strand ads. Poll the vehicle’s publications for the real state. It is enqueued with the sold intent. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/close-ads \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "enqueued": true,
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/document-discrepanciesCopiar el enlace a esta sección

What this car’s official papers disagree with

Each row carries what the document says, what stock said when it was read, and — once decided — who decided, why, and what stock held at that instant (applied_prior_value).

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/document-discrepancies \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "66666666-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "attachment_id": "f1f1f1f1-0000-4000-8000-000000000001",
      "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
      "attachment_kind": "padron",
      "field": "registration_number",
      "document_value": "FGXY22",
      "observed_stock_value": "FGXY21",
      "note": "El padrón trae una letra distinta a la patente registrada.",
      "observed_at": "2026-09-18T14:00:00.000Z",
      "observed_by": "11111111-0000-4000-8000-000000000001",
      "resolution": null,
      "resolution_reason": null,
      "resolved_on": null,
      "resolved_at": null,
      "resolved_by": null,
      "applied_prior_value": null,
      "created_at": "2026-09-18T14:00:00.000Z",
      "updated_at": "2026-09-18T14:00:00.000Z"
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/document-discrepanciesCopiar el enlace a esta sección

Record that an official document disagrees with stock

⚠ WRITES NOTHING BUT THE OBSERVATION — the vehicle is untouched, and stays untouched until a person applies it. attachment_id points into the ERP S15-20 vehicle expediente (never raw bytes), must belong to THIS car, and its kind must be one of padron, factura, certificado_anotaciones — all three issued OUTSIDE the dealership. A contrato is refused: a compraventa is dealer-asserted, and this is the one place an external fact may overrule a dealer-asserted one. field is bounded to the six a registry actually states — an unbounded list would let a factura "correct" the asking price. A reading that AGREES with stock is refused; it is not a discrepancy.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/document-discrepancies \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment_id": "f1f1f1f1-0000-4000-8000-000000000001",
    "field": "registration_number",
    "document_value": "FGXY22",
    "note": "El padrón trae una letra distinta a la patente registrada."
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "id": "66666666-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "attachment_id": "f1f1f1f1-0000-4000-8000-000000000001",
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "attachment_kind": "padron",
    "field": "registration_number",
    "document_value": "FGXY22",
    "observed_stock_value": "FGXY21",
    "note": "El padrón trae una letra distinta a la patente registrada.",
    "observed_at": "2026-09-18T14:00:00.000Z",
    "observed_by": "11111111-0000-4000-8000-000000000001",
    "resolution": null,
    "resolution_reason": null,
    "resolved_on": null,
    "resolved_at": null,
    "resolved_by": null,
    "applied_prior_value": null,
    "created_at": "2026-09-18T14:00:00.000Z",
    "updated_at": "2026-09-18T14:00:00.000Z"
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/document-discrepancies/{discrepancyId}/applyCopiar el enlace a esta sección

Apply the document — the document wins

Rewrites the field to what the document says, THROUGH the same ownership-aware write path a hand edit takes: the corrected field joins the vehicle’s Override local set (ADR 0023), so the next portal sync does not undo it. What stock held at that instant is preserved on the discrepancy and stamped into the car’s Historial. reason is mandatory; a second decision is a 409, and there is deliberately no un-apply verb — release the field to hand it back to sync.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/document-discrepancies/<id>/apply \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "El padrón es el vigente; se corrige la patente en stock."
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "66666666-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "attachment_id": "f1f1f1f1-0000-4000-8000-000000000001",
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "attachment_kind": "padron",
    "field": "registration_number",
    "document_value": "FGXY22",
    "observed_stock_value": "FGXY21",
    "note": "El padrón trae una letra distinta a la patente registrada.",
    "observed_at": "2026-09-18T14:00:00.000Z",
    "observed_by": "11111111-0000-4000-8000-000000000001",
    "resolution": "applied",
    "resolution_reason": "El padrón es el vigente; se corrige la patente en stock.",
    "resolved_on": "2026-09-19T09:00:00.000Z",
    "resolved_at": "2026-09-19T09:00:00.000Z",
    "resolved_by": "11111111-0000-4000-8000-000000000001",
    "applied_prior_value": "FGXY21",
    "created_at": "2026-09-18T14:00:00.000Z",
    "updated_at": "2026-09-18T14:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/document-discrepancies/{discrepancyId}/dismissalCopiar el enlace a esta sección

Dismiss the document — stock stands

Records that the document does NOT overrule the stock record. ⚠ NEVER touches stock, and carries the same actor and the same MANDATORY reason as an apply: a dismissal nobody signed is not a decision, it is a discrepancy that quietly stopped being displayed.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/document-discrepancies/<id>/dismissal \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "El padrón es el vigente; se corrige la patente en stock."
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "66666666-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "attachment_id": "f1f1f1f1-0000-4000-8000-000000000001",
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "attachment_kind": "padron",
    "field": "registration_number",
    "document_value": "FGXY22",
    "observed_stock_value": "FGXY21",
    "note": "El padrón trae una letra distinta a la patente registrada.",
    "observed_at": "2026-09-18T14:00:00.000Z",
    "observed_by": "11111111-0000-4000-8000-000000000001",
    "resolution": "dismissed",
    "resolution_reason": "El padrón es del dueño anterior y es previo al regrabado.",
    "resolved_on": "2026-09-19T09:00:00.000Z",
    "resolved_at": "2026-09-19T09:00:00.000Z",
    "resolved_by": "11111111-0000-4000-8000-000000000001",
    "applied_prior_value": null,
    "created_at": "2026-09-18T14:00:00.000Z",
    "updated_at": "2026-09-18T14:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/documentsCopiar el enlace a esta sección

Every document of one car

The car’s papers in one read (ADR 0114 §7), in the dealership’s order: how it entered (purchase_note, nota de compra — or the sale_note with role: parte_de_pago that took it as a trade-in), the consignment_contract (contrato de consignación, the mandato), each sale_note (nota de venta, voided ones included) followed by its compraventa (contrato de compraventa), the deal_settlement (Resumen del negocio; preview while the car is in stock) and the liquidacion (liquidación al consignante).

A paper the car is expected to have and does not is listed with status: missing (a nota de venta before the sale, a compraventa before approval, a liquidación before the consignor is paid). Other statuses: issued, approved, voided (notas), printed / unprinted (compraventa, mandato — frozen instruments), preview / final (Resumen del negocio), paid / withdrawal (liquidación).

pdf is where the PDF is read (method + path under /api/v1); print is the call that issues an unprinted instrument (needs the write scope). signable says whether a signed copy belongs on the document; signed_copy is that copy in the expediente (upload it with POST /vehicle-attachments and signed_document_type + signed_document_id), null when missing and ABSENT for a caller without vehicle_registry:read.

Requires marketplace:read. Each document type is listed only for a caller holding its read scope (purchase_notes:read, consignments:read, sale_notes:read, dealership_economics:read). No amounts.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/documents \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "documents": [
      {
        "type": "purchase_note",
        "id": "d5d5d5d5-0000-4000-8000-000000000001",
        "folio": "P-34",
        "issued_at": "2026-08-02T14:10:00.000Z",
        "printed_at": null,
        "status": "issued",
        "pdf": {
          "method": "GET",
          "path": "/purchase-notes/d5d5d5d5-0000-4000-8000-000000000001/pdf"
        },
        "print": null,
        "signable": true,
        "signed_copy": null
      },
      {
        "type": "sale_note",
        "id": "d4d4d4d4-0000-4000-8000-000000000001",
        "folio": "V-12",
        "issued_at": "2026-09-20T15:02:00.000Z",
        "printed_at": null,
        "status": "approved",
        "pdf": {
          "method": "GET",
          "path": "/sale-notes/d4d4d4d4-0000-4000-8000-000000000001/pdf"
        },
        "print": null,
        "signable": true,
        "signed_copy": null
      },
      {
        "type": "compraventa",
        "id": "d4d4d4d4-0000-4000-8000-000000000001",
        "folio": "V-12",
        "issued_at": "2026-09-20T16:40:00.000Z",
        "printed_at": "2026-09-20T16:40:00.000Z",
        "status": "printed",
        "pdf": {
          "method": "GET",
          "path": "/sale-notes/d4d4d4d4-0000-4000-8000-000000000001/compraventa/pdf"
        },
        "print": null,
        "signable": true,
        "signed_copy": {
          "attachment_id": "f1f1f1f1-0000-4000-8000-000000000003",
          "filename": "compraventa-firmada.pdf",
          "mime_type": "application/pdf",
          "uploaded_at": "2026-09-21T10:05:00.000Z"
        }
      },
      {
        "type": "deal_settlement",
        "id": null,
        "folio": null,
        "issued_at": "2026-09-20T15:30:00.000Z",
        "printed_at": null,
        "status": "final",
        "pdf": {
          "method": "GET",
          "path": "/vehicles/e1e1e1e1-0000-4000-8000-000000000001/deal-settlement/pdf"
        },
        "print": null,
        "signable": false
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/duplicate-candidatesCopiar el enlace a esta sección

Possible duplicates of this car

Posible duplicado: other cars of the workspace that share this car’s photos and specs but whose identifiers conflict in a way a person could have typed. reason is plate_typo (both plates present, one character apart) or invalid_vin (at least one VIN is implausible: not 17 characters, a non-alphanumeric character, an I/O/Q, or all digits). The nightly photo reconciliation records them; it never merges such a pair on its own.

Only OPEN candidates are listed: not dismissed, not resolved by a merge, and with both cars live (not merged, not deleted). The car may sit on either side of a pair; other_vehicle is always the OTHER car, with lead_count = the lead interests pointing at it. Act on a candidate with POST /vehicles/\{id\}/merge or POST /vehicles/duplicate-candidates/\{candidateId\}/dismiss. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/duplicate-candidates \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "0b7c4e2a-5d1f-4a8e-9c3b-2f6d8e1a4b70",
      "reason": "plate_typo",
      "detected_at": "2026-10-26T06:12:40.000Z",
      "other_vehicle": {
        "id": "88f2fa25-3c71-4e0b-9a4d-6b1e2c7d5f90",
        "title": "MINI Cooper S 2017",
        "plate_normalized": "JLGJ42",
        "vin": "25423423423131313",
        "status": "disponible",
        "active": true,
        "price_clp": 15990000,
        "photo_url": "https://cdn.example.com/vehicles/88f2fa25/1.jpg",
        "lead_count": 5,
        "created_at": "2026-09-02T14:05:11.000Z"
      }
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/ficha-tecnicaCopiar el enlace a esta sección

The printable spec sheet for one unit

Renders the "hoja de mesón" — the counter sheet a customer walking the lot takes home — and streams it as application/pdf. ⚠ IT IS NOT AN ISSUANCE. Nothing is stored: no rendered_document row, no folio, no supersede chain, and no immutability claim of any kind. Calling it twice with the vehicle edited in between returns two DIFFERENT sheets, by design — the sheet is a render of the row as it is right now, which is why there is no companion metadata route and no stored-bytes hash to verify against (contrast GET /consignments/\{id\}/contract/pdf, which REFUSES to serve bytes whose sha256 disagrees with its row).

Everything printed comes from the PUBLIC projection of the vehicle — the same DTO GET /stock/\{id\} serves to a dealer’s own website — plus the workspace’s branding and the unit’s branch. The plate, the VIN, the floor price, the target position, the IVA regime and the patio position are not expressible in that projection and never appear on the paper. Unlike /stock/\{id\}, there is NO status gate: an operator can print the sheet for a reservado or vendido unit they can already see. Scoped marketplace:read (a public-fields render, not dealer economics); 404 for another tenant’s vehicle, so the route is not an existence oracle.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/ficha-tecnica \
  -H "Authorization: Bearer $VITRINA_KEY"

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/fields/protectCopiar el enlace a esta sección

Protect (lock) vehicle fields against sync

Explicitly pin the named canonical fields to their current value (ADR 0023, two-way candado) so no sync overwrites them — without editing the value first. Non-protectable names (price_amount, status, …) are a no-op. Symmetric to /fields/release.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/fields/protect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      "price_amount"
    ]
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "origin_integration_id": null,
    "source": "manual",
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "title": null,
    "short_title": null,
    "price_amount": 13990000,
    "price_clp": 13990000,
    "watch_enabled": false,
    "floor_price_clp": null,
    "target_position": null,
    "abono_amount_clp": 300000,
    "merged_into": null,
    "deleted_at": null,
    "price_currency": "CLP",
    "odometer_value": 42500,
    "odometer_unit": "KM",
    "fuel_type": "Bencina",
    "gear_type": "Automática",
    "body_style": "Sedán",
    "color": "Gris",
    "doors": 4,
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "plate_normalized": "FGXY21",
    "listing_type": "Usado",
    "record_type": null,
    "type": "Car",
    "merch_label": null,
    "featured_at": null,
    "vehicle_type": "auto",
    "sale_status": null,
    "status": "disponible",
    "reserved_at": null,
    "reserved_by_name": null,
    "sold_at": null,
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "estacionamiento": null,
    "description": "Mantenimientos al día en concesionario.",
    "photos": [
      {
        "url": "https://images.example.cl/corolla-2022-1.jpg",
        "order": 0
      }
    ],
    "attributes": {},
    "tags": [],
    "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
    "active": true,
    "protected_fields": [],
    "deactivated_by": null,
    "tenencia": "propio",
    "tenencia_source": "default",
    "tenencia_declared_by": null,
    "tenencia_declared_at": null,
    "iva_regime": null,
    "keys_count": null,
    "municipalidad_comuna_code": null,
    "last_service_date": null,
    "service_odometer_km": null,
    "published_at": null,
    "last_seen_at": null,
    "created_at": "2026-09-15T18:34:48.575Z",
    "updated_at": "2026-09-15T18:34:48.575Z",
    "live_sale_note": null,
    "active_reservation": null,
    "sin_costo": true,
    "not_on_lot": false
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/fields/releaseCopiar el enlace a esta sección

Release Override local protection on vehicle fields

Drop protection (ADR 0023) on the named canonical fields so the next sync re-follows the source. Releasing an unprotected field is a no-op.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/fields/release \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      "color"
    ]
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "origin_integration_id": null,
    "source": "manual",
    "make": "Toyota",
    "model": "Corolla",
    "version": "1.8 XEI CVT",
    "year": 2022,
    "title": null,
    "short_title": null,
    "price_amount": 13990000,
    "price_clp": 13990000,
    "watch_enabled": false,
    "floor_price_clp": null,
    "target_position": null,
    "abono_amount_clp": 300000,
    "merged_into": null,
    "deleted_at": null,
    "price_currency": "CLP",
    "odometer_value": 42500,
    "odometer_unit": "KM",
    "fuel_type": "Bencina",
    "gear_type": "Automática",
    "body_style": "Sedán",
    "color": "Gris",
    "doors": 4,
    "registration_number": "FGXY21",
    "vin": "9BWZZZ377NP004512",
    "plate_normalized": "FGXY21",
    "listing_type": "Usado",
    "record_type": null,
    "type": "Car",
    "merch_label": null,
    "featured_at": null,
    "vehicle_type": "auto",
    "sale_status": null,
    "status": "disponible",
    "reserved_at": null,
    "reserved_by_name": null,
    "sold_at": null,
    "location_id": "b1b1b1b1-0000-4000-8000-000000000001",
    "estacionamiento": null,
    "description": "Mantenimientos al día en concesionario.",
    "photos": [
      {
        "url": "https://images.example.cl/corolla-2022-1.jpg",
        "order": 0
      }
    ],
    "attributes": {},
    "tags": [],
    "searchable_text": "toyota corolla 1.8 xei cvt sedán bencina automática gris 2022",
    "active": true,
    "protected_fields": [],
    "deactivated_by": null,
    "tenencia": "propio",
    "tenencia_source": "default",
    "tenencia_declared_by": null,
    "tenencia_declared_at": null,
    "iva_regime": null,
    "keys_count": null,
    "municipalidad_comuna_code": null,
    "last_service_date": null,
    "service_odometer_km": null,
    "published_at": null,
    "last_seen_at": null,
    "created_at": "2026-09-15T18:34:48.575Z",
    "updated_at": "2026-09-15T18:34:48.575Z",
    "live_sale_note": null,
    "active_reservation": null,
    "sin_costo": true,
    "not_on_lot": false
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/historyCopiar el enlace a esta sección

A vehicle's change history (Historial)

Reverse-chronological audit trail for this vehicle — created, field edits (with a before→after diff), publish/unpublish/cierre, and Override local protect/release — with teammate actors resolved to display names. It also carries the deal's milestones, read from each document's own audit rows: nota de compra emitted/voided (purchase_note_issued, purchase_note_voided), nota de venta emitted/approved/voided (sale_note_issued, sale_note_approved, sale_note_voided), contrato de compraventa first printed (compraventa_printed), mandato de consignación first printed (mandato_issued), a signed copy filed (signed_copy_filed, with metadata.signed_document_type) and the liquidación paid to the consignor (liquidacion_paid). metadata.folio names the document when it has one. Each document type appears only for a caller holding its read scope (purchase_notes:read, sale_notes:read, consignments:read; signed copies also need vehicle_registry:read). A download of the Resumen del negocio is deal_settlement_downloaded. The car's papers (ADR 0114 §7 — permiso de circulación, revisión técnica, SOAP, padrón, CAV, any named paper) appear as paper_added (a file filed; metadata.replaced_attachment_id when it replaced one), paper_updated (renamed or its «Vence» day set, metadata.changed) and paper_removed, each with metadata.kind, metadata.label and metadata.expires_on — only for a caller holding vehicle_registry:read. A value changed directly on a connected system (price, km; Veekls also year and version) and taken into Vitrina is portal_edit (system actor, changes, metadata.provider, metadata.portal, metadata.summary); a portal value that was not taken in is portal_edit_ignored (metadata.summary; metadata.ignored: field, portal_value, kept_value, reason = pending_vitrina_edit when it lost to a Vitrina edit still waiting to be pushed, out_of_range when it fell outside the price/km sanity range). The UI merges it with /activity (leads) into one "Leads y cambios" timeline.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/history \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "99999999-0000-4000-8000-000000000005",
      "action": "sale_notes.approve",
      "kind": "sale_note_approved",
      "actor": {
        "kind": "user",
        "id": "11111111-0000-4000-8000-000000000001",
        "name": "Ana Torres"
      },
      "changes": [],
      "metadata": {
        "folio": "V-13",
        "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001"
      },
      "at": "2026-09-18T15:02:11.000Z"
    },
    {
      "id": "99999999-0000-4000-8000-000000000003",
      "action": "vehicles.create",
      "kind": "created",
      "actor": {
        "kind": "user",
        "id": "11111111-0000-4000-8000-000000000001",
        "name": "Ana Torres"
      },
      "changes": [],
      "metadata": {},
      "at": "2026-09-15T18:34:58.390Z"
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/interestCopiar el enlace a esta sección

Who is asking about this car

The interest rollup: distinct contacts, how many became named leads, a per-portal breakdown of where they came from, first and last contact, and days in stock.

It answers "is anyone interested NOW", which is why a sold vehicle rolls up empty (ADR 0030) rather than showing its historical interest — use /activity for the history. No contact ids are echoed, deliberately: the endpoint reports demand without becoming a way to enumerate the contact table. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/interest \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "distinct_contacts": 2,
    "named_leads": 1,
    "by_portal": [
      {
        "portal": "website",
        "contacts": 2
      }
    ],
    "first_contact_at": "2026-09-16T12:00:00.000Z",
    "last_contact_at": "2026-09-19T15:30:00.000Z",
    "anonymous_interest": 1,
    "in_stock_since": "2026-09-15T18:34:48.575Z",
    "time_in_stock_days": 6,
    "is_sold": false,
    "lifetime": {
      "distinct_contacts": 2,
      "named_leads": 1,
      "anonymous_interest": 1,
      "first_contact_at": "2026-09-16T12:00:00.000Z",
      "last_contact_at": "2026-09-19T15:30:00.000Z"
    }
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /vehicles/{id}/mergeCopiar el enlace a esta sección

Merge two cars into one

Fusionar: collapse this car and other_vehicle_id into ONE car. The survivor is chosen by the platform, never by the caller: an active car beats an inactive one, then the ERP stock-of-record row beats a portal row, then the car with more activity (leads, alerts, publications), then the older one. Every lead, reserva, documento, publicación, cita and cost line of the loser moves onto the survivor; the loser stops appearing in Stock. It cannot be undone through the API.

Any two live cars of the workspace may be merged; a duplicate candidate is not required. Merging resolves every candidate naming the loser. 404 when either car is unknown, merged or deleted; 409 when both ids are the same car. Answers \{ survivor_id, loser_id \}. Automotive-vertical only: a workspace on another vertical gets 403 here however its scopes are set.

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/vehicles/<id>/merge \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "other_vehicle_id": "88f2fa25-3c71-4e0b-9a4d-6b1e2c7d5f90"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "survivor_id": "3b1f8a52-9d34-4a7e-8f2c-1a2b3c4d5e6f",
    "loser_id": "88f2fa25-3c71-4e0b-9a4d-6b1e2c7d5f90"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /vehicles/{id}/pipelineCopiar el enlace a esta sección

Place a vehicle on a reconditioning board, move boards, or remove it

Places the car on a kind=vehicle pipeline, landing on that board's ENTRY column (lowest position, category open) unless stage_id names another column OF THAT SAME BOARD. A car already placed is RE-placed and the change is recorded in stage_transition_log. ⚠ pipeline_id: null TAKES THE CAR OFF ITS BOARD AND DELETES NOTHING — the car, its history and its past transitions all remain; only the placement is cleared. Placement is OPTIONAL by design: most cars are on no board at all, and that is not an error state. A pipeline of another kind is a 400; an unknown or foreign one is a 404.

Cuerpo

curl -X PUT https://api.vitrinadev.com/api/v1/vehicles/<id>/pipeline \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "44444444-0000-4000-8000-000000000001"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "pipeline_id": "44444444-0000-4000-8000-000000000001",
    "stage_id": "55555555-0000-4000-8000-000000000001",
    "stage_entered_at": "2026-09-20T01:46:33.764Z",
    "status": "disponible",
    "stage_blocked_reason": null,
    "prep_assignee_user_id": null,
    "registration_number": null,
    "title": null
  },
  "meta": {
    "outcome": "moved"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /vehicles/{id}/prep-assigneeCopiar el enlace a esta sección

Name (or un-name) the person driving a vehicle's preparación

Sets who owns getting this unit out of the column it is on. user_id: null un-assigns. The value is a RAW user id and every read returns it as one — the display name is resolved CLIENT-SIDE against GET /memberships, this platform's convention wherever a person appears on a card, because the column carries no FK (it outlives a membership delete). ⚠ ANY WELL-FORMED uuid IS ACCEPTED AND MEMBERSHIP IS NOT VALIDATED — deliberately identical to lead.owner_user_id and ticket.assignee_user_id, and recorded as a known cross-entity gap rather than a rule invented for one noun. UNLIKE THE BLOCK, THIS SURVIVES A STAGE MOVE: the person driving the unit does not change because it reached the next column. A car that is on NO board is a 409.

Cuerpo

curl -X PUT https://api.vitrinadev.com/api/v1/vehicles/<id>/prep-assignee \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "11111111-0000-4000-8000-000000000001"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "e1e1e1e1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "pipeline_id": "44444444-0000-4000-8000-000000000001",
    "stage_id": "55555555-0000-4000-8000-000000000002",
    "stage_entered_at": "2026-09-20T01:46:34.125Z",
    "status": "disponible",
    "stage_blocked_reason": "Esperando repuesto de importación",
    "prep_assignee_user_id": "11111111-0000-4000-8000-000000000001",
    "registration_number": null,
    "title": null
  },
  "meta": {
    "outcome": "moved"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /vehicles/{id}/publicationsCopiar el enlace a esta sección

List marketplace publications of a vehicle

Every publication row for this vehicle, one per connected portal it has ever been sent to — including a deleted/error row from a past close/unpublish, since a row here is a tombstone rather than an absence. status is the real PublicationStatus (never a boolean): pending (device-agent transport, facebook_marketplace — enqueued but not yet posted), published/imported/updating/error (live on the portal — error too, since only a later refresh failed), removing (device-agent transport — a removal was enqueued but not yet confirmed, so the ad is presumptively still live, the opposite fact from pending), paused (Cierre de avisos reversible hide, portals that support pausing) or deleted (gone, or a portal-specific terminal state like Chileautos’ Withdrawn). external_id is the portal’s own id for the ad; it is never a key inside Vitrina.

Per-portal push status. After a dealer edit, each row reports the result of its last push: last_push_status is updating (the edit is queued, running or being retried), updated (the portal took it; last_push_at is when and last_push_fields lists what went out) or failed (the final retry failed: last_push_error is the portal’s reason in Spanish, last_push_at is when it gave up). A failed push retries automatically and the row stays failed until a later push succeeds; one portal failing never changes the others. null means never pushed. push_delivery says what updated means: api (the change is on the portal), feed (Yapo: the change is in the feed and shows when Yapo reads it) or extension (Facebook Marketplace: queued for the dealer’s browser extension). The same fields ride on GET /vehicles/publications.

curl https://api.vitrinadev.com/api/v1/vehicles/<id>/publications \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "88888888-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
      "marketplace_account_id": "33333333-0000-4000-8000-000000000001",
      "provider": "mercadolibre",
      "external_id": "MLC-1234567890",
      "status": "published",
      "origin": "vitrina",
      "permalink": "https://articulo.mercadolibre.cl/MLC-1234567890",
      "last_synced_at": "2026-09-19T10:00:00.000Z",
      "last_published_at": "2026-09-16T09:00:00.000Z",
      "last_error": null,
      "close_retry_count": 0,
      "portal_state": "active",
      "portal_state_at": "2026-09-19T10:00:00.000Z",
      "last_push_status": "updated",
      "last_push_at": "2026-09-19T09:58:00.000Z",
      "last_push_error": null,
      "last_push_fields": [
        "priceAmount"
      ],
      "push_delivery": "api",
      "raw_provider_payload": null,
      "created_at": "2026-09-16T09:00:00.000Z",
      "updated_at": "2026-09-19T10:00:00.000Z"
    }
  ]
}