Empezar
De cero a leer el stock de una automotora — la key, la lista, una unidad y el sobre de errores, con las respuestas que obtuve al recorrerlo.
Esta página es el camino corto: conseguir una credencial, listar el stock, leer un auto y reconocer una falla. Son cuatro llamadas.
Las respuestas que verás son las que obtuve yo al recorrerla, contra un workspace de prueba con tres autos y dos sucursales. Los identificadores y los autos que veas serán otros; la forma es la misma.
1. Consigue una API key
Toda llamada a esta API viaja con una key sk_, y esa key es lo único que decide de qué workspace lees.
Hay dos caminos para tener la primera, y cuál te toca depende de quién eres.
Si eres la automotora, la key se emite desde la aplicación, en la sección Desarrolladores.
Esta parte todavía no está escrita
La sección Desarrolladores está en construcción. Cuando esté publicada, acá va el recorrido con capturas. Mientras tanto, pídele la primera key a quien administre el workspace, o usa el camino por API de más abajo.
Si ya tienes una key con el permiso api_keys:write, emites las siguientes tú mismo. Es una llamada, y es la que usé para todo lo que sigue:
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 — lectura de stock", "scopes": ["stock:read"] }'{
"data": {
"id": "784cecc0-681c-49a1-9188-db9c8326949c",
"tenant_id": "00000000-0000-4000-8000-000000000001",
"name": "sitio web — lectura de stock",
"prefix": "sk_t2_O9",
"scopes": ["stock:read"],
"created_at": "2026-09-15T19:31:40.643089+00:00",
"last_used_at": null,
"expires_at": null,
"revoked_at": null,
"secret": "sk_t2_O9…"
}
}data.secret es la llave, y es el único momento en que la vas a ver completa. Las lecturas posteriores devuelven prefix — sus primeros ocho caracteres — y nada más. Acá arriba la dejé truncada a propósito: la tuya llega entera.
export VITRINA_KEY="<el data.secret completo de la respuesta>"Trampa
Una key no puede repartir permisos que no tiene
Emití esa misma key desde una credencial que solo tenía api_keys:read y
api_keys:write, y pedí stock:read para la nueva. La respuesta fue un 403:
{
"error": {
"code": "FORBIDDEN",
"message": "You cannot grant an API key that includes a permission you do not have (stock:read)",
"requestId": "1cf632ca-8bf5-438f-b2fa-323277dbff1c"
}
}Es la regla que impide que una credencial acotada se promueva sola. Quien emite tiene que tener ya el permiso que reparte.
2. Lista el stock
curl https://api.vitrinadev.com/api/v1/stock \
-H "Authorization: Bearer $VITRINA_KEY"{
"data": [
{
"id": "f74839ce-14bc-46c0-99f5-d330799bda23",
"make": "Hyundai",
"model": "Tucson",
"version": "2.0 GL",
"year": 2020,
"price": { "amount": 15200000, "currency": "CLP" },
"odometer": { "value": 88900, "unit": "KM" },
"fuel_type": "Diésel",
"gear_type": "Mecánica",
"body_style": "SUV",
"status": "reservado",
"reserved_at": "2026-09-15T18:34:59.348Z",
"sucursal": {
"id": "6812d9f0-9bed-44b5-91df-4e5b90941f6b",
"name": "Sucursal Providencia",
"comuna_code": "13123",
"comuna_name": "Providencia",
"region_code": "13"
},
"photos": [],
"created_at": "2026-09-15T18:34:59.425Z",
"published_at": null
}
],
"meta": { "pagination": { "limit": 20, "offset": 0 } }
}Recorté el ejemplo a un auto y a los campos que se explican solos; la respuesta real trae los tres y unos cuantos campos más, todos en Stock.
Dos cosas que conviene saber ya. La lista trae veinte por página y pagina por offset, no por cursor. Y viene ordenada por fecha de creación descendente, así que lo primero que ves es lo último que cargó la automotora.
3. Lee una unidad
curl https://api.vitrinadev.com/api/v1/stock/08eecaca-10bc-40b0-a2eb-d0915dba1cc9 \
-H "Authorization: Bearer $VITRINA_KEY"{
"data": {
"id": "08eecaca-10bc-40b0-a2eb-d0915dba1cc9",
"make": "Toyota",
"model": "Corolla",
"version": "1.8 XEI CVT",
"year": 2022,
"price": { "amount": 13990000, "currency": "CLP" },
"odometer": { "value": 42500, "unit": "KM" },
"status": "disponible",
"description": "Mantenciones al día en concesionario.",
"photos": [{ "url": "https://images.example.cl/corolla-2022-1.jpg", "order": 0 }],
"created_at": "2026-09-15T18:34:48.575Z"
}
}Mismo objeto que en la lista. No hay una versión "expandida": si un campo no está en la lista, tampoco está acá.
4. Reconoce una falla
Pedí un auto que no existe:
curl https://api.vitrinadev.com/api/v1/stock/00000000-0000-4000-8000-0000000000ff \
-H "Authorization: Bearer $VITRINA_KEY"{
"error": {
"code": "NOT_FOUND",
"message": "Vehículo no encontrado",
"requestId": "e3c36709-4fff-462d-8940-4ff9e8138ce6"
}
}404, y el cuerpo trae error en vez de data. Esa es toda la regla: una respuesta correcta tiene data, una fallida tiene error, nunca las dos.
Ramifica por error.code, no por error.message — el código es el contrato y el mensaje es para una persona. Y guarda el requestId: es lo que nos permite encontrar tu llamada en los logs cuando algo no cuadra.
El catálogo completo, con qué hacer ante cada uno, está en Errores.