VAT regime

Download the full API pública projection: openapi.json.

Sell a unit explains this resource in prose, with runnable examples.

GET /ivaCopy Anchor Link

Read the IVA rate and the dealership default regime

Returns the pinned platform rate and the dealership’s default regime.

rate is \{ bps: 1900, percent: 19, configurable: false, copy \}. The rate is law, not a setting — there is no endpoint that changes it, and copy is the string the UI must render beside it so an operator can see that it is fixed rather than a field somebody forgot to enable.

tenant_default.configured = false means nobody has chosen yet, which is a different claim from having chosen afecto. A unit taken into stock while the default is unconfigured captures nothing, and resolves as platform_fallback.

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

Example response (200)

{
  "data": {
    "rate": {
      "bps": 1900,
      "percent": 19,
      "configurable": false,
      "copy": "IVA legal de Chile (19%). No es configurable: aplica a todos los cálculos fiscales de la plataforma."
    },
    "tenant_default": {
      "regime": "exento",
      "configured": true
    }
  }
}

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

PUT /iva/tenant-defaultCopy Anchor Link

Set the dealership default IVA regime

Sets the regime new units inherit when they enter stock (afecto | exento).

It is not retroactive. A unit captures the default at intake and keeps it, so changing this moves the default for the next car and rewrites nothing that already resolved a regime — including closed months. Units that never captured one (imported before this existed) do follow it, and GET /iva/vehicles/\{id\} reports that as source: tenant_default rather than passing it off as a decision.

The body is .strict(): an unknown key is a 400, because regimen is one character from regime and a silently discarded key is a caller who believes the dealership switched regimes when it did not. Clearing the default is deliberately NOT offered — that is a state to arrive at by never configuring, not one to navigate to.

Body

curl -X PUT https://api.vitrinadev.com/api/v1/iva/tenant-default \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "regime": "exento"
  }'

Example response (200)

{
  "data": {
    "regime": "exento",
    "configured": true
  }
}

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

GET /iva/vehicles/{id}Copy Anchor Link

Resolve the IVA regime for one unit

The unit’s financial-view payload: stored_regime (the raw column — null when this car never captured one), the resolved regime, and source, which says where the answer came from:

• vehicle — captured on the unit. A change to the dealership default cannot move it.
• tenant_default — inherited, so it will move if the default moves.
• platform_fallback — nobody has decided at either grain; determined is false.

Also returns debito (applies + rate_bps) and badge — label, qualifier and the débito consequence spelled out in one sentence, which is the half worth showing: the regime only matters because of what it does to the margin.

A vehicle in another workspace, soft-deleted, merged away, or nonexistent is a 404, all four identically.

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

Example response (200)

{
  "data": {
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "stored_regime": null,
    "tenant_default": {
      "regime": "exento",
      "configured": true
    },
    "regime": "exento",
    "source": "tenant_default",
    "determined": true,
    "captured": false,
    "debito": {
      "applies": false,
      "rate_bps": 0
    },
    "rate": {
      "bps": 1900,
      "percent": 19,
      "configurable": false,
      "copy": "IVA legal de Chile (19%). No es configurable: aplica a todos los cálculos fiscales de la plataforma."
    },
    "badge": {
      "label": "Exento",
      "qualifier": "sin IVA",
      "consequence": "La venta no genera débito fiscal de IVA (venta de autos usados, exenta en Chile): no se descuenta IVA del margen al calcular la comisión ni el neto del vendedor."
    }
  }
}

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

PUT /iva/vehicles/{id}Copy Anchor Link

Override or clear one unit’s IVA regime

Sets this car’s own regime, overriding whatever it inherited — the ordinary case being one used car in an otherwise afecto lot, or the reverse.

regime: null clears the override so the unit inherits the dealership default again. That is a real operation, not a no-op, and it is the only way back from an override set by mistake. Omitting the key entirely is a 400 — clearing an override and sending an empty body must not be the same request.

Requires dealership_economics:write, not marketplace:write: a regime decides whether a stored amount is net or gross, so it is not editable by every principal who can edit stock.

Body

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

Example response (200)

{
  "data": {
    "vehicle_id": "e1e1e1e1-0000-4000-8000-000000000001",
    "stored_regime": "afecto",
    "tenant_default": {
      "regime": "exento",
      "configured": true
    },
    "regime": "afecto",
    "source": "vehicle",
    "determined": true,
    "captured": true,
    "debito": {
      "applies": true,
      "rate_bps": 1900
    },
    "rate": {
      "bps": 1900,
      "percent": 19,
      "configurable": false,
      "copy": "IVA legal de Chile (19%). No es configurable: aplica a todos los cálculos fiscales de la plataforma."
    },
    "badge": {
      "label": "Afecto",
      "qualifier": "con IVA",
      "consequence": "La venta genera débito fiscal de IVA (19%): se descuenta IVA del margen al calcular la comisión y el neto del vendedor."
    }
  }
}

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