La API de Vitrina
Qué expone la plataforma y cómo se ordena esta documentación.
Tu código entra al workspace con una API key. Una llamada basta:
curl https://api.vitrinadev.com/api/v1/locations \
-H "Authorization: Bearer $VITRINA_KEY"{
"data": [
{
"id": "6812d9f0-9bed-44b5-91df-4e5b90941f6b",
"name": "Sucursal Providencia",
"comuna_code": "13123",
"region_code": "13",
"timezone": "America/Santiago",
"is_active": true
}
]
}Todo cuelga de https://api.vitrinadev.com/api/v1 y todo pide esa misma credencial. Lo que salió bien llega dentro de data; lo que falló, dentro de error. El catálogo de códigos está en Errores.
Adentro de un workspace viven los contactos y las conversaciones del negocio. También su agenda, sus sucursales, su equipo y el catálogo de lo que ofrece. Sobre esa base corren las verticales, hoy automotoras y clínicas, con lo propio de cada rubro.
Cómo está ordenada esta documentación
Primero la plataforma: los capítulos que valen en cualquier workspace. Después un grupo por vertical, con lo que solo existe ahí. Los dos traen sus Recetas: una tarea entera, resuelta de punta a punta.
| Capítulo | Para qué |
|---|---|
| Empezar | El camino corto: una credencial, una lectura, una falla y una suscripción a eventos. |
| Aprender con los videos de capacitación | Videos, presentaciones y manuales de la aplicación, en training.vitrinadev.com. |
| Resolver una tarea completa con la API | Las recetas que valen en cualquier workspace: cada una arma una tarea entera, en orden. |
| Usar el SDK de TypeScript | El paquete de TypeScript generado desde el contrato: cliente tipado, paginación y verificación de webhooks. |
| Emitir y rotar tus API keys | Qué credenciales existen, qué es un scope y cómo se emite una key acotada. |
| Emitir un token personal | La credencial de una persona: ve lo mismo que ella y muere con su membresía. |
| Probar tu integración sin tocar datos reales | Un espacio de trabajo sintético, una clave sk_test_ y los envíos que quedan capturados en vez de salir. |
| Enviar mensajes | Escribirle a un contacto por su canal, y los bloqueos que pueden impedirlo. |
| Buscar, crear y fusionar contactos | Las personas del workspace y las empresas a las que pertenecen: buscar, crear, corregir, fusionar y etiquetar. |
| Cargar productos y variantes | El catálogo de lo que ofrece el workspace, sus variantes y los datos propios de cada una. |
| Mover leads por el embudo | Las oportunidades que el equipo trabaja, y el tablero por el que avanzan. |
| Responder hilos y resolver tickets | El hilo con un cliente y el caso que lo sobrevive: leer la bandeja, responder, asignar, posponer y resolver. |
| Escribir correos con un asistente | El borrador que un asistente conectado deja listo, la voz del workspace que lee antes de escribirlo, y el envío que siempre hace una persona. |
| Agendar una hora | La hora reservada, el servicio que se reserva y los eventos que avisan cada cambio de estado. |
| Configurar el agente que conversa | El agente que conversa por el workspace: borrador y versión en vivo, skills, herramientas y Solicitudes. |
| Alimentar la base de conocimiento | Lo que un agente puede citar: archivos subidos y fuentes redactadas a mano. |
| Publicar tu centro de ayuda | El portal de autoservicio de cara al cliente, y su sincronización con la base de conocimiento. |
| Medir el workspace | Los números del workspace y los reportes del panel, en solo lectura. |
| Configurar tus sucursales | Los puntos de atención del workspace, y la dirección con la que se muestran. |
| Administrar el equipo | Los miembros del workspace y sus invitaciones: alta, cambio de rol y una baja que nunca deja trabajo huérfano. |
| Organizar equipos y roles | Los equipos que enrutan canales y tickets, y los roles personalizados que deciden el acceso. |
| Automatizar respuestas y asignaciones | Respuestas con acciones en un clic, y el enrutamiento ordenado que decide a quién le llega cada conversación. |
| Revisar y desconectar canales | Leer, revisar la salud y desconectar un canal de mensajería. |
| Fijar SLAs y automatizar acciones | Los objetivos de tiempo de un ticket, y las automatizaciones evento → condición → acción. |
| Verificar tu dominio de envío | El dominio propio con el que el workspace envía campañas de correo. |
| Usar plantillas y Flows de WhatsApp | Los mensajes pre-aprobados por Meta y los formularios que una conversación puede abrir. |
| Recibir eventos firmados | Suscribirse a los eventos del workspace y verificar la firma con la que llegan. |
| MCP | Conectar un cliente de IA, como Claude o Cursor, al workspace en solo lectura. |
| Leer un error y reaccionar | El sobre que trae cada falla, y qué hacer con cada código. |
| Seguir versiones y deprecaciones | Qué promete cada operación según su nivel, y cuánto dura una que se deprecia. |
| Registro de cambios | Qué operación o evento se agregó, cambió, quedó obsoleto o se quitó, por release. |
| Tratar datos personales y de salud | Qué operaciones tocan datos sensibles y qué obligaciones trae usarlas. |
La Referencia trae el contrato completo, operación por operación. Se genera desde el mismo documento OpenAPI que emite el backend.
Qué está publicado y qué no
Cada operación publicada lleva un nivel, que dice cuánto puede cambiar y con cuánto aviso. Hoy todas están en beta; ninguna llegó a estable. Lo que no lleva nivel publicado es interna: no está documentado y puede cambiar o desaparecer sin aviso, así que no construyas encima. Seguir versiones y deprecaciones explica los tres niveles.
Por dónde partir
Empezar
Conseguir la key, leer algo del workspace, reconocer una falla y recibir el primer evento firmado.
Emitir y rotar tus API keys
Qué es un scope, cómo se emite una key acotada y qué pasa cuando la revocas.
El dinero funciona igual en todos los rubros. Cobrar y conciliar pagos cubre lo que alguien debe, lo que llegó y cómo se imputa.
Cada vertical trae además sus recetas, que resuelven una tarea completa de punta a punta:
Recetas para automotoras
Subir tu stock sin cargar el mismo auto dos veces · Mantener tu stock al día desde tu ERP · Mostrar tu stock en tu sitio web · Sacar la lista de interesados en un auto · Recibir los leads en tu CRM · Avisar a tu cliente cuando llegue el auto que buscaba · Llevar el expediente del auto a tu sistema
Recetas para clínicas
Abrir la agenda de la clínica a tu software · Llevar las citas a tu sistema · Conectar Claude a tu agenda
Y cada una trae sus capítulos propios. En automotoras, Cargar y mantener el lote y Guardar y leer el expediente. En clínicas, Reservar una hora en la clínica, Definir prestaciones y precios y Presupuestar un plan y cerrar caja.