Mostrar tu stock en tu sitio web

AutomotorasSolo en los workspaces de automotoras.

El sitio de la automotora tiene que mostrar el lote, y el lote cambia todos los días. Esta receta lo resuelve con una credencial de solo lectura y tres endpoints. No hay nada que sincronizar ni copia que se desactualice.

Al final vas a tener una página que lista los autos publicados, los filtra por sucursal y abre el detalle de uno.

1. Una key que solo puede leer el lote

Emítela con el permiso más angosto que existe, stock:read, desde una key que ya lo tenga (Autenticación):

curl -X POST https://api.vitrinadev.com/api/v1/api-keys \
  -H "Authorization: Bearer $VITRINA_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "sitio web del lote público", "scopes": ["stock:read"] }'

Trampa

Esta key vive en tu servidor, nunca en el navegador

stock:read es de solo lectura, pero es una credencial del workspace: quien la tenga puede leer todo el lote, cuantas veces quiera, hasta que alguien la revoque. Si la pones en el JavaScript de la página, la tiene cualquiera que abra el inspector. Llama la API desde tu servidor, sea una función, un endpoint tuyo o el render del sitio, y manda al navegador el resultado en vez de la llave.

2. Cuántos hay

GET /stock/count es la llamada más barata de la API. Sirve para saber si hay algo que mostrar antes de armar la página:

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

{ "data": { "count": 7 } }

Acepta los mismos filtros que la lista, así que también es el contador de «7 SUV disponibles» sin traerte los siete.

3. El listado

curl "https://api.vitrinadev.com/api/v1/stock?limit=2" \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    {
      "id": "5d00f5cf-ebe3-4e8b-a456-8d783daed0be",
      "make": "Suzuki",
      "model": "Swift",
      "version": "GL 1.2",
      "year": 2021,
      "price": { "amount": 9490000, "currency": "CLP" },
      "odometer": { "value": 31400, "unit": "KM" },
      "type": "Car",
      "type_label": "Auto",
      "listing_type": "Usado",
      "status": "disponible",
      "reserved_at": null,
      "sold_at": null,
      "sucursal": {
        "id": "6812d9f0-9bed-44b5-91df-4e5b90941f6b",
        "name": "Sucursal Providencia",
        "comuna_code": "13123",
        "comuna_name": "Providencia",
        "region_code": "13"
      },
      "photos": [],
      "created_at": "2026-09-22T00:30:01.896Z",
      "published_at": null
    }
  ],
  "meta": { "pagination": { "limit": 2, "offset": 0 } }
}

Tres cosas que determinan cómo escribes el código de la página:

Pagina por offset y nunca por cursor, con veinte unidades por defecto. Para armar una grilla completa, sube limit o recorre con offset hasta que data venga vacío.
Viene ordenado por fecha de creación descendente. Lo primero que ves es lo último que cargó la automotora, que suele ser lo que quieres arriba.
price.amount viene en pesos enteros y odometer con su unidad explícita. No divides nada y no adivinas. Si la unidad tenía el odómetro en millas, la conversión ya está hecha.

El bloque sucursal viene embebido en cada unidad, con la comuna ya resuelta a nombre. No tienes que cruzar con Sucursales para escribir «Providencia» debajo de la foto.

4. El filtro que de verdad vas a usar

curl "https://api.vitrinadev.com/api/v1/stock?sucursal=6812d9f0-9bed-44b5-91df-4e5b90941f6b" \
  -H "Authorization: Bearer $VITRINA_KEY"

?sucursal= toma el id que viene en el bloque embebido. Para el selector de la página, lista las sucursales una vez con GET /locations y guárdalas: cambian una vez al año. El lote, en cambio, léelo en cada carga.

Los demás filtros están en Stock con sus valores exactos: marca, modelo, año, precio y tipo.

5. El detalle

curl https://api.vitrinadev.com/api/v1/stock/5d00f5cf-ebe3-4e8b-a456-8d783daed0be \
  -H "Authorization: Bearer $VITRINA_KEY"

Devuelve el mismo objeto que trae la lista. No hay una versión «expandida»: si un campo no está en la lista, tampoco está aquí. Puedes renderizar la ficha con lo que ya tienes de la grilla y llamar al detalle solo para refrescar.

6. Lo que nunca vas a recibir, y por qué importa

El lote público es una proyección del inventario. No trae la patente, ni el VIN, ni el costo, ni el margen, ni las notas internas. Tampoco los autos que la automotora tiene sin publicar. Eso vive detrás de otro permiso y de otro endpoint (Autenticación).

Por eso esta receta es segura de poner en un sitio. Aunque la key se filtrara, lo filtrado es lo que la automotora ya está mostrando en la vitrina de su local.

Todos los filtros, el orden y los estados están en Stock. La otra mitad del sitio, lo que pasa cuando alguien consulta, está en Recibir los leads en tu CRM.