La API y los webhooks de vFound
Conecte la suite de vFound con los sistemas que ya utiliza: gestión hotelera, servicios de asistencia, sistemas de RR. HH. y de estudiantes, escáneres de sala de correo, almacenes de datos o sus propias aplicaciones. Lea y modifique registros en todos los productos, mantenga sincronizada su lista de personas, reciba un webhook firmado en cuestión de segundos cuando ocurra algo y deje que los asistentes de IA ayuden en el mostrador.
¿Prefiere una configuración guiada? Consulte las guías de integración de vFound para Cloudbeds, OfficeRnD Flex, Microsoft Entra, Slack, Microsoft Teams, Google Chat, calendarios, Zapier y clientes MCP.
Autenticación
Cada establecimiento dispone de la API. Un propietario o responsable crea hasta 10 claves en Ajustes, Para desarrolladores y elige qué puede hacer cada una. La clave completa se muestra una sola vez. Envíela como token Bearer:
curl https://vfound.io/api/v1/items \
-H "Authorization: Bearer vf_live_xxxxxxxxxx_…"
| Alcance | Permite | Endpoints |
|---|---|---|
items:read | Leer objetos encontrados, categorías y traslados entre establecimientos | GET /items, /items/{id}, /categories, /item-transfers |
items:write | Añadir y actualizar objetos encontrados, y enviarlos a otros establecimientos o recibirlos de ellos | POST /items, PATCH /items/{id}, POST /item-transfers y sus acciones de cancelar y recibir |
claims:write | Registrar las revisiones humanas de titularidad, las decisiones, la aprobación de entrega y la recogida | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | Crear avisos de pérdida de visitantes para un centro de contacto | POST /lost-reports |
claims:read | Leer las reclamaciones, con los datos de contacto de quien reclama | GET /claims, /claims/{id} |
lost_reports:read | Leer los avisos de pérdida de los visitantes | GET /lost-reports |
analytics:read | Leer el resumen de analítica | GET /analytics |
parcels:read | Leer los paquetes, con el nombre y el correo de cada destinatario | GET /parcels, /parcels/{id} |
parcels:write | Registrar, entregar, devolver y recordar | POST /parcels y sus acciones |
checkroom:read | Leer tickets, puestos, eventos, la fila de salida y los informes | GET bajo /checkroom |
checkroom:write | Registrar la entrada, devolver, marcar como listo y gestionar puestos o eventos | POST y PUT bajo /checkroom |
loans:read | Leer los equipos y quién los tiene | GET /loans, /loans/items y uno de cada |
loans:write | Añadir equipos, entregarlos, ampliar el plazo y recibirlos de vuelta | POST y PATCH bajo /loans |
visitors:read | Leer las visitas | GET /visitors, /visitors/{id} |
visitors:write | Invitar, registrar la entrada y la salida, cancelar, enviar un pase | POST /visitors y sus acciones |
visitors:screening | Confirmar que se revisó una coincidencia de la verificación de un visitante: envíe screening_reviewed, o apruebe una visita que una coincidencia mantiene retenida. Desactivado de forma predeterminada; lo que hace la clave queda registrado como de la clave, con su nombre | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | Leer la lista de personas | GET /people, /people/{id} |
people:write | Añadir, actualizar, sincronizar y eliminar personas | POST, PATCH y DELETE bajo /people |
stays:read | Leer el contexto privado de las estancias de hotel y su historial de correcciones | GET /stays, /stays/{stay} |
stays:write | Añadir o actualizar de forma idempotente el contexto de una estancia desde un sistema hotelero | POST /stays |
school:read | Leer las llegadas tarde y las salidas anticipadas del alumnado desde la secretaría | GET /school/movements |
school:write | Añadir o actualizar alumnos desde el sistema de información escolar | PUT /school/pupils |
queue:read | Leer filas, tickets, horas reservadas, mensajes, cifras de encuestas y el informe de la fila | GET bajo /queue |
queue:write | Añadir personas a una fila, llamarlas, finalizar sus tickets, reservar y cancelar horas y escribir a las personas en fila | POST bajo /queue |
webhooks:manage | Suscribir y cancelar la suscripción de las direcciones de webhook propias de la clave, para eventos cuyos datos la clave puede leer | GET, POST y DELETE /webhooks |
Los objetos, las reclamaciones, los avisos de pérdida y la analítica requieren vFound Lost & Found; los paquetes requieren vFound Parcels; los tickets requieren vFound Checkroom; los equipos requieren vFound Equipment; las visitas requieren vFound Visitors; la lista de personas requiere Parcels, Visitors o Equipment; las estancias de hotel requieren Lost & Found o Parcels; la secretaría escolar requiere Visitors con la secretaría escolar activada (responde 404 mientras está desactivada); las filas y los tickets requieren vFound Queue. Un producto que no está abierto para el establecimiento responde 403.
Una clave actúa como la persona que la creó y deja de funcionar si esa persona ya no gestiona el establecimiento, salvo que la solicitud indique a un miembro del equipo en X-Acting-User (consulte Actuar en nombre de un miembro del equipo). Los cambios hechos con una clave siguen las mismas reglas, los mismos correos y el mismo historial de auditoría que el mostrador, y cada entrada de auditoría registra la clave que hizo el cambio. Cada clave puede hacer 120 solicitudes por minuto. Dirección base: https://vfound.io/api/v1. Las listas devuelven 25 registros por página (hasta 100 con per_page) y aceptan page; la mayoría también filtra con updated_since (ISO 8601) y search, como se indica más abajo.
Claves de prueba
Una clave creada como clave de prueba empieza por vf_test_ y solo puede tener queue:read y queue:write. Funciona en una sola fila de prueba con etiqueta, Test line (sandbox) (fila 1, mostrador 1), y en ningún otro sitio: las mismas direcciones de Queue que una clave real para filas, franjas, tickets, /queue/join, llamar al siguiente, llamar, atendido, ausencia y eliminar responden desde la fila de prueba; cualquier otra dirección responde 403 con code: test_key. Una clave de prueba nunca lee ni modifica una fila o un ticket reales y no envía ningún correo, mensaje de texto, aviso del navegador ni webhook. Una clave de prueba ignora Idempotency-Key: la misma solicitud enviada dos veces se ejecuta dos veces. Las respuestas incluyen "sandbox": true y el encabezado X-Vfound-Sandbox: 1. Una fila de prueba admite hasta 100 tickets por clave, sin dirección de correo, y se eliminan junto con la clave y a los siete días. Use nombres inventados.
Reintentos seguros
Envíe un encabezado Idempotency-Key (cualquier valor único de hasta 191 caracteres visibles, como un UUID) con un POST, PATCH o DELETE. Si la conexión se interrumpe y usted envía de nuevo la misma solicitud con la misma clave en un plazo de 24 horas, vFound no repite el cambio: responde con la primera respuesta y el encabezado Idempotent-Replayed: true. La misma clave con una solicitud distinta se rechaza (422, idempotency_key_reused); una clave cuya primera solicitud sigue en curso responde 409 (idempotency_in_progress). Después de borrar los datos personales de quien encontró un objeto o de quien reclama, las respuestas guardadas de ese establecimiento devuelven en su lugar 410 sin los datos borrados; actualice el registro en lugar de reintentar la escritura anterior con una clave nueva. Los errores del servidor no se guardan, así que reintentar después de uno vuelve a ejecutar la solicitud. Una respuesta que incluye algo que se muestra una sola vez, como el secreto de firma de POST /webhooks o un código de vinculación de quiosco, tampoco se guarda nunca: un reintento vuelve a ejecutar la solicitud, así que consulte GET /webhooks antes de suscribir dos veces la misma dirección.
Actuar en nombre de un miembro del equipo
Una aplicación que su equipo utiliza en el mostrador, como una aplicación de puesto o de depósito, puede indicar en nombre de qué miembro del equipo actúa. Envíe X-Acting-User con el correo de inicio de sesión de la persona o su identificador de usuario. Debe ser en ese momento un miembro activo del establecimiento de la clave. La solicitud se ejecuta entonces como esa persona: el historial del objeto y el de la reclamación nombran a esa persona en lugar de a quien creó la clave, y el historial de auditoría nombra a esa persona, la clave y al responsable que creó la clave. Solo puede hacer lo que permitan a la vez los alcances de la clave y su propio rol en el establecimiento: quien tiene el rol de lector solo puede leer, el personal también puede modificar objetos, reclamaciones, avisos de pérdida, paquetes, tickets de guardarropa, equipos, visitas y estancias de hotel, y los propietarios y responsables pueden usar todos los alcances de la clave. Un nombre que no sea un miembro activo del establecimiento se rechaza con 403 y acting_user_refused, con el mismo mensaje exista o no la dirección; un alcance que el rol de la persona no permite se rechaza con 403 y acting_user_role. Los reintentos seguros se guardan por persona, así que la respuesta guardada de una persona nunca se repite para otra. El encabezado funciona solo con claves de establecimiento, no con un asistente conectado mediante inicio de sesión, que ya actúa como la persona que lo conectó. vFound comprueba que la persona indicada sea un miembro activo; no le pide que inicie sesión, así que indique solo a personas de una aplicación en la que su equipo inicia sesión. Sin el encabezado, una clave funciona exactamente como antes.
OpenAPI
Toda la API, cada evento y cada objeto se describen en un archivo OpenAPI 3.1: vfound.io/openapi/v1.json. Impórtelo en Postman, Insomnia o en su propio generador de código. Una prueba lo mantiene al día con la API, así que nunca incluye un endpoint que no exista ni omite uno que sí existe.
Conexiones preparadas con sistemas operativos
Los propietarios y responsables configuran estas conexiones de proveedor de solo lectura en Ajustes, Conexiones, Sistemas operativos. Son independientes de la API REST pública: el cliente crea y controla la credencial del proveedor, la conexión debe superar una prueba antes de activarse, los fallos repetidos pausan solo esa conexión y el trabajo manual sigue disponible.
| Sistema | Qué lee vFound | Áreas de vFound |
|---|---|---|
| Cloudbeds | Contexto mínimo de reservas y habitaciones mediante una clave del hotel controlada por el cliente y limitada a read:reservation. Forma parte de vFound Enterprise. | Estancias privadas para Lost & Found y Parcels |
| OfficeRnD Flex | ID de socio, nombre, correo y estado activo mediante flex.community.members.read, con un filtro opcional por lugar. | La lista de personas compartida de Parcels, Equipment y Visitors |
| Microsoft Entra ID | ID de usuario, nombre visible, correo y estado activo mediante las actualizaciones delta de Microsoft Graph y User.Read.All con consentimiento del administrador. | La lista de personas compartida de Parcels, Equipment y Visitors |
Son conexiones de API configuradas por el cliente, no afirmaciones de certificación del proveedor. Probar, activar y sincronizar una conexión forman parte de vFound Enterprise. En concreto, la conexión con Entra no es una aplicación de Microsoft Marketplace.
Objetos
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/items | Objetos, primero los modificados más recientemente. Filtros: status, search (palabras del título, la descripción, la marca, el color o las etiquetas), updated_since (ISO 8601), page, per_page (hasta 100). | items:read |
| GET/items/{id} | Un objeto por su identificador. | items:read |
| GET/categories | Los nombres de categoría que puede usar un objeto. | items:read |
| POST/items | Añade un objeto encontrado. Se publica en su página de visitantes, activa las alertas y la coincidencia, y aparece en su historial de auditoría como uno añadido a mano. | items:write |
| PATCH/items/{id} | Cambia los detalles o el estado. | items:write |
| GET/item-transfers | Objetos encontrados que este establecimiento envió a otro establecimiento del mismo grupo de clientes, o recibe de él, primero los que están en camino. También lista los establecimientos a los que puede enviar (destinations) y los contenedores de almacenamiento de este establecimiento (bins). Filtros: status (in_transit, received o cancelled), direction (incoming o outgoing). | items:read |
| POST/item-transfers | Envía un objeto que espera a su dueño a otro establecimiento del grupo: item_id, destination_business_id y una note opcional. Solo para claves creadas por un propietario o responsable. El objeto sale de la página de visitantes del establecimiento emisor (si ese establecimiento muestra sus objetos encontrados) y no puede cambiar hasta que llegue. Un objeto con alguna reclamación se queda donde está. | items:write |
| POST/item-transfers/{id}/cancel | El establecimiento emisor recupera el objeto antes de que se reciba. | items:write |
| POST/item-transfers/{id}/receive | El establecimiento receptor confirma que llegó, con bin_id (obligatorio cuando el establecimiento tiene contenedores de almacenamiento) o location. El objeto pasa entonces a este establecimiento con sus fotos, su historial y sus fechas, y se compara con los avisos de pérdida de este establecimiento como un objeto recién registrado. | items:write |
Herramientas de mostrador de Lost & Found y Checkroom
Los ajustes nuevos de correo están desactivados de forma predeterminada. Los recuentos de escaneo y las discrepancias de cierre son solo de revisión. P90 usa el percentil 90 por rango más próximo de los intervalos de tiempo válidos; si no hay muestras, devuelve null. La capacidad física de piezas avisa pero nunca bloquea el registro de entrada. Consulte la descripción de OpenAPI para los campos de la solicitud. Las plantillas de configuración y los ajustes requieren un propietario o responsable.
| Método y ruta | Qué hace | Alcance |
|---|---|---|
| GET /lost-found/context-schema | Lee las definiciones versionadas de los campos de contexto privado, sin valores de registros. Basta con cualquiera de los alcances de lectura indicados. | items:read o lost_reports:read |
| GET /lost-found/desk-settings | Lee los ajustes opcionales del mostrador. | lost_reports:read |
| PUT /lost-found/desk-settings | Sustituye los ajustes del mostrador; solo propietario o responsable. Los ajustes de correo nuevos están desactivados de forma predeterminada. | lost_reports:write |
| GET /checkroom/desk-settings | Lee los ajustes opcionales del mostrador. | checkroom:read |
| PUT /checkroom/desk-settings | Sustituye los ajustes del mostrador; solo propietario o responsable. Los ajustes de correo nuevos están desactivados de forma predeterminada. | checkroom:write |
| GET /lost-found/counts | Lista las últimas 30 sesiones de recuento por escaneo. | items:read |
| POST /lost-found/counts | Captura los identificadores de los objetos conservados para un recuento solo de informe; no cambia ninguna custodia. | items:write |
| GET /lost-found/counts/{id} | Lee un recuento con las cifras de objetos que faltan, inesperados y que ya no están aquí. | items:read |
| POST /lost-found/counts/{id}/scan | Registra el escaneo de un QR o de una etiqueta corta de objeto; un objeto conocido duplicado cuenta una vez. | items:write |
| POST /lost-found/counts/{id}/finish | Finaliza un recuento sin modificar objetos. | items:write |
| GET /lost-found/queues | Lista las colas de trabajo guardadas de quien creó la clave en este establecimiento. | lost_reports:read |
| PUT /lost-found/queues/{id} | Sustituye su propia cola guardada; los objetos y las reclamaciones de fondo no cambian. | lost_reports:write |
| DELETE /lost-found/queues/{id} | Elimina su propia cola guardada; los objetos y las reclamaciones de fondo no cambian. | lost_reports:write |
| POST /lost-found/queues | Guarda un ajuste preestablecido de cola de trabajo con nombre para quien creó la clave. | lost_reports:write |
| GET /lost-found/queues/{id} | Lee los registros actuales de una cola guardada. Los traslados entrantes abren la vista de traslado existente, con sus permisos. | lost_reports:read, items:read, claims:read |
| POST /lost-found/intake-review | Devuelve indicaciones deterministas de integridad y privacidad; sin IA ni modificaciones. | items:read |
| GET /checkroom/templates | Lista las plantillas de configuración, que solo contienen configuración; solo responsable. | checkroom:read |
| PUT /checkroom/templates/{id} | Sustituye una plantilla de configuración como responsable; los eventos, puestos y tickets de fondo no cambian. | checkroom:write |
| DELETE /checkroom/templates/{id} | Elimina una plantilla de configuración como responsable; los eventos, puestos y tickets de fondo no cambian. | checkroom:write |
| POST /checkroom/templates | Guarda la configuración de puestos de un evento sin visitantes ni tickets; solo responsable. | checkroom:write |
| POST /checkroom/templates/{id}/apply | Crea un evento nuevo y puestos; si hay colisiones de rangos de números activos, se rechaza toda la operación. | checkroom:write |
Centro de contacto y custodia de Lost & Found
Las integraciones operadas por personas pueden crear un aviso de pérdida, registrar una revisión de titularidad, decidir una reclamación y registrar la recogida física. Los alcances de escritura nuevos deben seleccionarse de forma explícita; las claves existentes no los obtienen. Ninguna de estas escrituras de reclamaciones o de destino se ofrece como herramienta de MCP ni de Ask vFound. Su integración es responsable de identificar y autorizar a su operador humano: la auditoría nombra al responsable que creó la clave y, cuando la integración envía X-Acting-User, también al miembro del equipo indicado, a quien vFound no autentica.
| Método y ruta | Qué hace | Alcance |
|---|---|---|
| POST /lost-reports | Alta desde el centro de contacto: first_name, last_name, email, title y description; opcionales phone, category id, colour_brand, place_lost, date_lost y language. Envía la confirmación normal al visitante y el enlace privado, e inicia el seguimiento de 90 días. El consentimiento telefónico nunca se presupone. Se aplican los límites existentes de avisos abiertos. | lost_reports:write |
| PUT /lost-reports/{id} | Edita lo que se perdió usando la huella devuelta por GET /lost-reports. El título y la descripción son obligatorios. Si se omite el recorrido, se conservan los detalles guardados; si la recogida está desactivada, se rechazan los cambios de contexto. Los cambios de contacto requieren el flujo independiente de contacto verificado. | lost_reports:write |
| GET /lost-reports/{id}/matches | Hasta 24 candidatos activos de texto o categoría, cada uno con match.label, reason y source. Los veredictos de IA guardados y recientes usan cached_ai; de lo contrario, una sugerencia por palabras clave se etiqueta como posible. Ninguna llamada nueva a un modelo ni decisión de titularidad. | lost_reports:read e items:read |
| GET /items/{id}/matches | Identificador y título del aviso coincidente sin los datos de contacto de quien lo hizo; hasta 24 coincidencias entre los últimos 1,000 avisos abiertos. Mismas etiquetas de origen y ninguna llamada nueva a un modelo. | items:read y lost_reports:read |
| POST /claims/{id}/verification | Registre verified (booleano) y method (distinctive_details, purchase_proof o staff_review). Es una declaración humana, no una autenticación automática de documentos; sin copia de documento ni pruebas en texto libre. La última revisión debe superarse antes de que la API acepte. | claims:write |
| POST /claims/{id}/decision | status: open, accepted, rejected, expired, ready_for_pickup, ready_for_shipment, shipped o handed_to_courier. Se aplican la máquina de estados existente y la segunda aprobación. Los campos de envío manual usan las reglas del espacio de trabajo. Con accepted, un return opcional (pickup o shipment) lleva la reclamación a esa etapa en la misma solicitud, con un solo correo a quien reclama; cuando una entrega de alto valor aún necesita su segunda aprobación, la reclamación sigue en accepted y return_notice explica por qué (repetir la misma solicitud no cambia nada). Un arranged_by opcional (site u owner) indica quién contrata una devolución por mensajería o correo, y cada respuesta de reclamación lo muestra. Sin arranged_by, una dirección de entrega enviada en shipment (o una que la reclamación ya tenga) significa que su equipo lo envía, como antes; de lo contrario, decide el ajuste de Lost & Found del establecimiento. owner significa que recoge el objeto el propio mensajero de quien reclama: no se pide dirección, se rechaza una dirección enviada con owner y se rechaza shipped. Cuando su mensajero lo recoge, envíe handed_to_courier con la empresa de mensajería en shipment.carrier y su referencia de reserva en shipment.tracking_number; la reclamación se cierra. Para cambiar quién lo contrata, devuelva la reclamación a ready_for_pickup y de nuevo a ready_for_shipment con arranged_by. | claims:write |
| POST /claims/{id}/release-approval | Un responsable distinto aprueba la entrega de alto valor ya aceptada, con las mismas comprobaciones que el espacio de trabajo. | claims:write |
| GET /claims/{id}/custody | Revisión e historial de etapas, aprobador y nombre y hora de la recogida. signature_recorded es un booleano; no se expone ninguna imagen de firma ni dirección de archivo privado. | claims:read |
| POST /claims/{id}/handover | Registra la recogida física desde ready_for_pickup, con handover.name y una URL de datos PNG en handover.signature cuando se exija. Las llamadas repetidas ya cerradas conservan el primer recibo. | claims:write |
| POST /items/{id}/disposition | kind donated/disposed, recipient para una donación, notes opcionales. Se aplican la fecha de conservación y las comprobaciones de reclamaciones pendientes o aceptadas. Devuelve el recibo del lote numerado. | items:write |
Use una Idempotency-Key para los reintentos de escritura. Un registro de verificación no autentica un documento de identidad ni aprueba por sí mismo la titularidad. La creación inicial del aviso sigue el flujo del visitante, incluida la IA activada por el establecimiento; las consultas GET de coincidencias usan veredictos guardados y solo búsqueda de texto. Son operaciones REST/OpenAPI genéricas; no se ha certificado ninguna instalación de WSO2 ni ningún conector nativo.
Añadir un objeto
curl https://vfound.io/api/v1/items -X POST \
-H "Authorization: Bearer $VFOUND_KEY" -H "Content-Type: application/json" \
-d '{"title":"Black leather wallet","category":"Wallets & Purses","found_date":"2026-09-23",
"location":"Front desk","colour":"Black","brand":"Fossil","tags":["leather","cards"],
"photo":"data:image/jpeg;base64,…","photo_public":true}'
Campos: title y category son obligatorios. Opcionales: found_date, found_time (HH:MM), keep_until, location, description, colour, brand, tags, value_band (unknown, low, medium, high), notes (solo para el personal), photo (una URL de datos base64 de hasta 8 MB) y photo_public. La protección de privacidad de vFound AI no comprueba las fotos enviadas por la API, así que establezca photo_public en false para cualquier foto que muestre datos personales.
El objeto
{"id":"9b2f…","title":"Black leather wallet","status":"in_care","category":"Wallets & Purses",
"found_date":"2026-09-23","found_time":"14:30","keep_until":"2026-10-21","location":"Front desk",
"description":null,"colour":"Black","brand":"Fossil","tags":["leather","cards"],"value_band":"low",
"photo_public":true,"photo_url":"https://vfound.io/uploads/…","transfer":null,"created_at":"…","updated_at":"…"}
El estado es uno de in_care, in_transit (de camino a otro establecimiento; transfer nombra entonces ambos establecimientos), claimed, expired, donated, disposed o trash. Un PATCH puede establecer in_care, expired, donated, disposed o trash; las devoluciones a un visitante se hacen mediante reclamaciones.
Reclamaciones
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/claims | Reclamaciones, primero las modificadas más recientemente. Filtros: status, updated_since, page, per_page. | claims:read |
| GET/claims/{id} | Una reclamación por su referencia. | claims:read |
{"id":"k3f9x2a1b7c4d8e6","status":"ready_for_pickup","item":{"id":"9b2f…","title":"Black leather wallet"},
"claimant":{"first_name":"Ana","last_name":"Ruiz","email":"ana@example.com","phone":null},
"description":"…","place_lost":"Bar","date_lost":"2026-09-22","language":"es","arranged_by":null,"created_at":"…","updated_at":"…"}
Estado de la reclamación: unread, open, accepted, awaiting_information, ready_for_pickup, ready_for_shipment, shipped, closed, rejected o expired (aceptada pero nunca recogida). arranged_by indica quién contrata una devolución por mensajería o correo: venue (su equipo la envía) u owner (la recoge el propio mensajero de quien reclama); null cuando la reclamación no tiene tal devolución. Los datos de quienes reclaman son datos personales: consérvelos solo el tiempo que los necesite.
Avisos de pérdida
GET/lost-reports lista lo que los visitantes comunicaron haber perdido, con status (open o closed), los datos de contacto de quien lo comunicó, el idioma que usó y cualquier enlace de Find My que compartió. Alcance: lost_reports:read.
Analítica
GET/analytics?days=30 devuelve el mismo resumen que Informes: objetos registrados y devueltos, tasa de devolución, mediana de días hasta la devolución, dónde terminaron los objetos, categorías, puntos críticos, días de más actividad, resultados del equipo, la tendencia y los comentarios de los visitantes. days es 7, 30, 90 o 365. Alcance: analytics:read.
Estancias de hotel
El contexto de estancia es privado del establecimiento y deliberadamente mínimo. Contiene una referencia de estancia estable, una referencia opcional del huésped, el nombre del huésped, la llegada y la salida, la zona horaria de origen, la habitación actual, el estado y las marcas de tiempo de origen. Nunca contiene tarifas, datos de pago, datos de fidelización, documentos de identidad, preferencias ni notas de reserva no relacionadas.
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/stays | Lista las estancias. Filtros: search (huésped, referencia estable o habitación actual), state, source, page y per_page. Una coincidencia de habitación solo ayuda a navegar; nunca sugiere quién es el dueño. | stays:read |
| GET/stays/{stay} | Una estancia y su historial auditable de origen y correcciones. | stays:read |
| POST/stays | Crea o actualiza el registro de origen de la API identificado por external_stay_ref. Envíe source_updated_at; los eventos retrasados o repetidos que no sean más recientes que el guardado se confirman sin reemplazar datos más nuevos. | stays:write |
curl https://vfound.io/api/v1/stays -X POST \
-H "Authorization: Bearer $VFOUND_KEY" -H "Idempotency-Key: pms-event-901" \
-H "Content-Type: application/json" \
-d '{"external_stay_ref":"BOOK-100","guest_name":"Avery Chen","current_room":"412",
"stay_state":"in_house","source_timezone":"America/New_York","source_updated_at":"2026-10-03T12:00:00Z"}'
Los objetos y los paquetes aceptan stay_id y room_at_event de forma opcional. Si se omite la habitación en el momento del evento, vFound guarda una instantánea de la habitación actual de la estancia. Esa instantánea no cambia tras un cambio de habitación; el registro muestra también la habitación actual, así que el mostrador ve ambas.
Parcels
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/parcels | Paquetes, primero los modificados más recientemente. Filtros: status (waiting, collected o returned), search (destinatario, unidad, número de seguimiento, remitente o código de recogida), updated_since. | parcels:read |
| GET/parcels/{id} | Un paquete. | parcels:read |
| POST/parcels | Registra un paquete para recipient_email (comparado con su lista de personas) o recipient_name, con unit, carrier, tracking, sender y shelf opcionales. A la persona se le envía por correo su código de recogida, salvo que notify sea false. | parcels:write |
| POST/parcels/{id}/collect | Lo entrega: collected_by (obligatorio) y una signature opcional (una URL de datos PNG). | parcels:write |
| POST/parcels/{id}/return | Lo devuelve al remitente, con una note opcional. | parcels:write |
| POST/parcels/{id}/remind | Envía al destinatario un correo recordándole que lo recoja. | parcels:write |
| POST/parcels/tracking | Normaliza un número de seguimiento y detecta UPS, FedEx, USPS, DHL, Amazon o un operador internacional S10. Un SSCC de GS1 válido se acepta como seguimiento de envío; un identificador de producto GS1 se identifica pero nunca se trata como número de paquete. | parcels:read |
| GET/parcels/pickup-queue | Personas que dijeron estar en el mostrador, con su número de paquetes y sus estantes. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | Marca como atendida una llegada al mostrador. | parcels:write |
| POST/parcels/bulk-remind | Envía recordatorios por correo de hasta 200 paquetes en espera seleccionados. | parcels:write |
| POST/parcels/bulk-return | Devuelve al remitente hasta 200 paquetes en espera seleccionados. | parcels:write |
| GET/parcels/shelves | Capacidades de los estantes de paquetes y ocupación actual. | parcels:read |
| POST/parcels/shelves | Crea un estante o cambia su capacidad. | parcels:write |
| GET/parcels/analytics | Volumen, combinación de operadores, tiempo de recogida, tasa de paquetes sin recoger y estantes más ocupados. | parcels:read |
| GET/parcels/outgoing | Paquetes salientes listos para un mensajero o ya entregados. | parcels:read |
| POST/parcels/outgoing | Registra un paquete saliente. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | Registra el mensajero y la firma en la entrega. | parcels:write |
| GET/parcels/rounds | Rondas de reparto y sus paradas. | parcels:read |
| POST/parcels/rounds | Crea una ronda de campus u oficina a partir de paquetes en espera. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | Completa una parada con el nombre del destinatario y la firma. | parcels:write |
| GET/parcels/couriers | Mensajeros registrados mediante Visitors, con status in u out. | parcels:read |
{"id":412,"status":"waiting","recipient":{"name":"Ana Ruiz","email":"ana@example.com","unit":"Room 214","reference":"S1044"},
"carrier":"UPS","tracking":"1Z999AA10123456784","sender":null,"size":"small","shelf":"B2","pickup_code":"KQHRER",
"notified_at":"…","collected_at":null,"collected_by":null,"returned_at":null,"created_at":"…","updated_at":"…"}
El código de recogida se muestra solo mientras el paquete espera. Los datos de los destinatarios son datos personales: consérvelos solo el tiempo que los necesite.
Checkroom
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/checkroom/tickets | Tickets, primero los modificados más recientemente, con status (pending, in, returned, left o moved), el número, lo que se entregó, piece_records etiquetados individualmente, los datos del cliente si los dio, la tarifa registrada en el mostrador y las horas. Filtros: status, search (cliente, habitación, número de ticket, etiqueta de pieza o código de ticket), updated_since. | checkroom:read |
| GET/checkroom/tickets/{id} | Un ticket. | checkroom:read |
| POST/checkroom/tickets | Registra la entrada de algo y asigna el siguiente número libre: kind (coat, bag, luggage u other, obligatorio), pieces, piece_details opcional con un tipo y un lugar de almacenamiento para cada pieza, guest_name, guest_email, guest_room, collect_by para equipaje, notes, fee_method (cash o card), station_id, event_id, storage_location, language y photo. La respuesta incluye también guest_ticket (el código y la dirección privada del ticket) una sola vez, para mostrarlo como código QR o imprimirlo para el cliente; las lecturas, las listas y los webhooks nunca lo incluyen. | checkroom:write |
| POST/checkroom/tickets/{id}/hand-back | Lo devuelve una vez que su sistema ha leído el ticket del cliente, con collected_by y signature opcionales. Envíe piece_ids para devolver piezas seleccionadas y dejar las demás abiertas; omítalo para devolver todas las piezas abiertas. without_ticket registra que el cliente perdió su ticket y entonces requiere collected_by y signature. | checkroom:write |
| GET/checkroom/stations | Lista los puestos de guardarropa del establecimiento, sus rangos de números y sus lugares de almacenamiento. | checkroom:read |
| POST/checkroom/stations | Crea un puesto con un rango de números que no se superponga. | checkroom:write |
| PUT/checkroom/stations/{id} | Cambia un puesto, su rango de números, sus lugares de almacenamiento o su estado activo. | checkroom:write |
| GET/checkroom/events | Lista los eventos de guardarropa recientes y próximos. | checkroom:read |
| POST/checkroom/events | Crea un evento con su volumen previsto y sus puestos. | checkroom:write |
| PUT/checkroom/events/{id} | Cambia los horarios, la previsión o los puestos de un evento. | checkroom:write |
| GET/checkroom/exit-queue | Tickets cuyos clientes pidieron al mostrador que les prepare sus cosas. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | Marca un ticket en espera como listo y avisa al cliente. | checkroom:write |
| GET/checkroom/report | Volumen de tickets, horas pico, tiempo de devolución y tarifas por método y por miembro del personal. | checkroom:read |
| GET/checkroom/export | Descarga las filas del informe de guardarropa como CSV a prueba de fórmulas. | checkroom:read |
Queue
Filas, las personas que esperan en ellas y los mostradores a los que se las llama. Cada cambio sigue los mismos pasos que el mostrador, con el mismo historial, como quien creó la clave o el miembro del equipo indicado en X-Acting-User. Un ticket nunca incluye el correo del visitante ni sus respuestas a las preguntas de la fila.
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/queue/lines | Filas con su estado actual, las personas que esperan y una espera estimada para quien se incorpora ahora. | queue:read |
| GET/queue/lines/{id} | Una fila. | queue:read |
| GET/queue/tickets | Tickets de un día del establecimiento (day, hoy de forma predeterminada), en orden de llamada; filtre por line y status. | queue:read |
| GET/queue/tickets/{id} | Un ticket. | queue:read |
| GET/queue/report | Tickets, personas atendidas, ausencias, personas que se fueron, y mediana de la espera y de los minutos de atención de los últimos days. | queue:read |
| POST/queue/tickets | Añade a una persona a una fila, como hace el mostrador. | queue:write |
| POST/queue/call-next | Llama a la siguiente persona a un mostrador (counter_id). Dos personas que llaman a la vez nunca reciben a la misma persona; data es null cuando nadie espera. | queue:write |
| POST/queue/tickets/{id}/call | Llama a una persona elegida a un mostrador. | queue:write |
| POST/queue/tickets/{id}/served | Marca como atendida a la persona que está en un mostrador. | queue:write |
| POST/queue/tickets/{id}/no-show | Marca como ausencia a una persona llamada que no vino. | queue:write |
| POST/queue/tickets/{id}/remove | Saca a una persona de la fila. | queue:write |
| GET/queue/bookings | Horas reservadas, las más próximas primero, con from, to, line, status y paginación. Nunca el correo de la persona. | queue:read |
| POST/queue/bookings | Reserva una de las horas libres de la página de horas reservadas de una fila para una persona (line_id, starts_at, email). | queue:write |
| POST/queue/bookings/{id}/cancel | Cancela una hora reservada; se avisa por correo a la persona de que el equipo la canceló. | queue:write |
| POST/queue/bookings/{id}/arrived | Registra la llegada de una persona con hora reservada; su ticket se coloca según la hora reservada. | queue:write |
| POST/queue/tickets/{id}/arrived | Marca como presente a una persona que se incorporó antes de llegar. | queue:write |
| GET/queue/tickets/{id}/messages | Los mensajes entre una persona en la fila y el equipo, los más antiguos primero. Al leerlos, los mensajes de la persona se marcan como leídos. | queue:read |
| POST/queue/tickets/{id}/messages | Escribe a una persona en la fila (body, de 1 a 500 caracteres), como el miembro del equipo de la clave. | queue:write |
| GET/queue/survey | Cifras de la encuesta posterior a la atención: respuestas, promedio, cada valoración, por fila, servicio, mostrador y miembro del equipo (el promedio de un miembro del equipo aparece a partir de 5 respuestas). Nunca comentarios. | queue:read |
| GET/queue/performance | Cifras sencillas de cada miembro del equipo para los mismos días que el informe. Sin puntuación ni clasificación. | queue:read |
| GET/queue/lines/{id}/slots | Las horas reservadas abiertas de una fila, tal como las ofrece su página de reservas. | queue:read |
| POST/queue/join | Asigna un número a un visitante de su propio sitio web, bajo las reglas del visitante (fila abierta, límites, respuestas obligatorias y casillas de consentimiento). Envíelo desde su servidor: la clave sustituye al captcha. | queue:write |
| GET/queue/tickets/lookup | Busca tickets por el número que tiene el visitante. | queue:read |
| GET/queue/tickets/{id}/status | Lo que muestra la página del ticket del propio visitante: lugar, estimación y frase. | queue:read |
| GET/queue/tickets/{id}/history | Los pasos de un ticket. Quién hizo cada uno es team, guest, api (una incorporación mediante una clave) o system (hecho automáticamente, como la ausencia automática), nunca un nombre. | queue:read |
| GET/queue/customers/history | Visitas de quien pidió que se le recordara, encontradas por correo, mientras el establecimiento tiene activado el reconocimiento. Indica a quien tiene la clave si una dirección de correo pertenece a un visitante recordado. | queue:read |
| GET/queue/insights | Recuentos de los mismos días que el informe: personas que se fueron antes de que se las llamara, personas con hora reservada y sin cita, la proporción de personas llamadas dentro del objetivo de espera por fila y semana, y horas de más actividad de semanas anteriores. Solo recuentos; nunca un nombre ni una respuesta. | queue:read |
| GET/queue/report-data | Los tickets de Queue tal como los lee el generador de informes (fields[], limit hasta 1000, offset), para herramientas de BI. El nombre del visitante nunca se incluye. | queue:read |
Equipment
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/loans | Equipos entregados, primero los modificados más recientemente, con status (out, returned o lost), si está overdue, el equipo, quien lo tiene y las horas. Filtros: status (out, returned, lost u overdue), search (nombre de quien lo tiene, correo o referencia), updated_since. | loans:read |
| GET/loans/{id} | Una entrega. | loans:read |
| POST/loans | Entrega algo: item_id o item_code (el código de su etiqueta, o el enlace que contiene su código QR), borrower_name (obligatorio), person_id opcional para vincular la lista de personas, borrower_email para un recibo, borrower_reference, due_at, note, language y signature. | loans:write |
| POST/loans/{id}/extend | Da más tiempo: un nuevo due_at. Se avisa por correo a la persona de la nueva hora. | loans:write |
| POST/loans/{id}/return | Lo recibe de vuelta, con condition opcional (good, damaged o incomplete), note y set_aside para apartar el equipo y repararlo. | loans:write |
| POST/loans/returns | Recibe varias cosas de vuelta a la vez: loan_ids (de 1 a 50), con los mismos condition, note y set_aside opcionales para todas. Todo o nada: si una ya está de vuelta o no se encuentra, no cambia nada. Una persona con dirección de correo recibe un recibo por cada entrega, con todo lo que volvió, y cada entrega envía su propio evento loan.returned. | loans:write |
| GET/loans/items | Todo lo que entrega el mostrador, por nombre. Filtros: status (available, out, repair o retired), search (nombre, etiqueta de activo o código de etiqueta), updated_since. | loans:read |
| GET/loans/items/{id} | Un equipo, con el enlace que contiene el código QR de su etiqueta. | loans:read |
| GET/loans/items/{id}/tickets | Tickets enviados al Jira, Zendesk o ServiceNow propios del establecimiento para este equipo (beta), con el último estado leído de vuelta. | loans:read |
| POST/loans/items | Añade equipos: name (obligatorio), category, tag, location, notes, loan_hours (cuántas horas suele estar entregado), photo, product y variant (las unidades de un mismo producto y variante pueden reservarse como una sola), y copies para añadir hasta 50 equipos idénticos, numerados. | loans:write |
| PATCH/loans/items/{id} | Cambia sus detalles, o establece status en available, repair o retired. product y variant cambian su familia de producto; cleaning_status con needs_cleaning lo marca como pendiente de limpieza y con null lo marca como limpio. Los equipos muestran product, variant, cleaning_status y cleaning_since. | loans:write |
| GET/loans/items/{id}/tag | Si hay una etiqueta NFC o RFID vinculada, y los últimos cuatro dígitos hexadecimales de su número de serie. | loans:read |
| PUT/loans/items/{id}/tag | Vincula una etiqueta por su número de serie, tal como lo lee un teléfono o como lo escribe un lector tipo teclado (hexadecimal, hexadecimal invertido o decimal); sustituye cualquier etiqueta que tuviera el equipo. | loans:write |
| DELETE/loans/items/{id}/tag | Elimina la etiqueta del equipo. | loans:write |
| POST/loans/checkouts | Entrega de uno a 50 equipos en una sola entrega atómica, o entrega un kit guardado. Acepta una persona, una hora límite, una nota y una firma opcional, y líneas de existencias (stock) entregadas en el mismo recibo, que se devuelven en stock. custom_values establece los atributos personalizados del establecimiento para la entrega. | loans:write |
| GET/loans/kits | Grupos guardados de equipos que suelen entregarse juntos. | loans:read |
| POST/loans/kits | Guarda un kit de al menos dos partes en total: item_ids con nombre, lines (una cantidad de una categoría) y child_kit_ids (kits dentro de él, hasta tres niveles), stock_lines (existencias contadas que se entregan con él, nunca retenidas para una reserva), y opcionalmente locked para que sus equipos con nombre salgan solo juntos. | loans:write |
| PUT/loans/kits/{id} | Cambia un kit guardado y sus equipos. | loans:write |
| GET/loans/trainings | Las formaciones que una categoría o un equipo pueden exigir antes de que alguien lo reciba (se configuran en Equipment, Políticas, Formación). | loans:read |
| GET/loans/trainings/{id}/holders | Quién tiene una formación, desde cuándo y hasta cuándo, y si ha caducado. | loans:read |
| POST/loans/trainings/{id}/holders | Da a una persona de la lista de personas una formación, o la renueva, con un documento de prueba opcional. | loans:write |
| DELETE/loans/trainings/{id}/holders/{person} | Quita una formación a una persona, con su documento de prueba. | loans:write |
| GET/loans/borrower-types | Los tipos de usuario: el límite de equipos de cada uno, su duración habitual y las categorías que sus personas ven y pueden recibir (se configuran en Equipment, Políticas). Un límite o una duración vacíos significan que se aplica el del propio establecimiento. | loans:read |
| GET/loans/borrower-types/{id}/members | Quién tiene un tipo de usuario. | loans:read |
| POST/loans/borrower-types/{id}/members | Asigna un tipo de usuario a personas de la lista de personas (hasta 500 a la vez). | loans:write |
| PUT/loans/borrower-types/{id}/members/{person} | Cambia la pertenencia de una persona a un tipo de usuario: su día de inicio, su día de fin (después de él siguen viendo lo que muestra el tipo, pero no pueden reservarlo ni recibirlo) y una nota sobre dónde se cobró una tarifa. vFound no cobra ningún pago. | loans:write |
| DELETE/loans/borrower-types/{id}/members/{person} | Quita un tipo de usuario a una persona. | loans:write |
| GET/loans/credits | Créditos de reserva concedidos recientemente y el saldo de una persona. Los créditos son un recuento que las reservas gastan, nunca dinero. | loans:read |
| POST/loans/credits | Concede créditos de reserva a una persona, o retira algunos con un número negativo (propietarios y responsables). | loans:write |
| GET/loans/holds | Bloqueos activos de entrega: mientras dura uno, no se entrega nada a la persona y no puede reservar. | loans:read |
| POST/loans/holds | Pone un bloqueo a las entregas a una persona, con un motivo opcional (se guarda para el equipo, nunca en el correo), una hora de fin y un correo para la persona. | loans:write |
| POST/loans/holds/{id}/lift | Levanta un bloqueo. | loans:write |
| GET/loans/spaces | Salas, puestos de trabajo, plazas de aparcamiento y otros lugares que el establecimiento reserva por un tiempo, filtrados opcionalmente por type. Cada uno es un equipo de tipo space y nunca se entrega. | loans:read |
| POST/loans/spaces | Añade una sala o un espacio con su tipo, cuántas personas admite y dónde está. | loans:write |
| PUT/loans/spaces/{id} | Cambia una sala o un espacio. | loans:write |
| GET/loans/spaces/availability | Cada sala o espacio con sus reservas abiertas entre from y to (hasta 31 días), con el nombre de la persona, cuántas personas acuden y las instrucciones de preparación. | loans:read |
| POST/loans/spaces/{id}/book | Reserva una sala o un espacio para una persona y un horario, solos o con equipos (todo o nada), con instrucciones de preparación para el equipo. | loans:write |
| POST/loans/reservation-groups/{id}/parts | Añade un equipo, o uno de una categoría, a la reserva de un kit o de un carrito, comprobado como una reserva nueva. Se rechaza para un kit bloqueado. Una parte de una categoría que cubre el formulario de riesgos del establecimiento requiere risk_answers, y la evaluación de la reserva espera una nueva revisión. | loans:write |
| POST/loans/reservations/{id}/remove-part | Quita una parte de la reserva de un kit o de un carrito; la última parte se cancela junto con la reserva. | loans:write |
| GET/loans/places | Los lugares anidados del propio establecimiento: edificios, salas, estantes, obras y camiones. El place_id de un equipo establece dónde está y rellena su location y su sub_location. | loans:read |
| GET/loans/category-tree | Las categorías de equipos agrupadas en un árbol, primero las principales. Las reglas y las reservas siguen aplicándose a la categoría propia de cada equipo. | loans:read |
| GET/loans/asset-models | Modelos a partir de los cuales se crean equipos nuevos. Envíe asset_model_id en POST /loans/items para rellenar todos los detalles que se dejen vacíos. | loans:read |
| GET/loans/items/{id}/links | Los vínculos de un equipo con otros equipos del mismo establecimiento: funciona con, una alternativa, sustituye a. | loans:read |
| POST/loans/items/{id}/links | Vincula un equipo con otro del mismo establecimiento, con una nota. | loans:write |
| DELETE/loans/items/{id}/links/{link} | Quita un vínculo de ambos equipos. | loans:write |
| POST/loans/kits/{id}/move | Traslada un kit a un lugar del establecimiento: todos los equipos con nombre que contiene, y los de los kits que hay dentro, van allí de una vez (propietarios y responsables). | loans:write |
| GET/loans/items/{id}/meter-readings | Lecturas de contador escritas para un equipo, las más recientes primero. | loans:read |
| POST/loans/items/{id}/meter-readings | Registra una lectura de contador. Un plan de mantenimiento con every_meter vence cuando el contador ha avanzado tanto; las lecturas solo suben. | loans:write |
| GET/loans/contracts | Contratos de proveedores vinculados con los equipos que cubren (propietarios y responsables). | loans:read |
| GET/loans/resale | Equipos puestos a la venta con su precio pedido y su valor contable (propietarios y responsables). Solo una lista: no se anuncia ni se vende nada. | loans:read |
| GET/loans/points | Puntos de recogida y de devolución que una reserva puede indicar. | loans:read |
| POST/loans/points | Añade un punto (propietarios y responsables). Una reserva indica uno para recoger y otro para devolver con pickup_point_id y dropoff_point_id. | loans:write |
| PUT/loans/points/{id} | Cambia un punto o lo desactiva. | loans:write |
| GET/loans/projects | Proyectos a los que puede pertenecer una reserva. No se recoge nada para un proyecto hasta que se aprueba. | loans:read |
| POST/loans/projects | Añade un proyecto (en espera de aprobación). | loans:write |
| POST/loans/projects/{id}/decision | Aprueba o rechaza un proyecto (propietarios y responsables). | loans:write |
| GET/loans/risk-assessments | Evaluaciones de riesgo en espera de revisión (o por status), con las respuestas de la persona. | loans:read |
| POST/loans/risk-assessments/{id}/review | Aprueba o rechaza una evaluación de riesgo (propietarios y responsables). Un rechazo cancela la reserva. | loans:write |
| POST/loans/reservation-series | Reserva un equipo, una categoría o una sala o un espacio cada día o cada semana (repeat: frequency, every, weekdays, count o until, skip_conflicts). Cada fecha sigue las reglas de reserva y cuenta las anteriores; no se reserva nada si una está ocupada, salvo que skip_conflicts esté activado. Como máximo 52 fechas, dentro de un año. | loans:write |
| POST/loans/reservations/{id}/move | Traslada una reserva, con todas las partes de una reserva de kit o de carrito juntas, a nuevos horarios o a otro equipo de la misma categoría. Se comprueba de nuevo como una reserva nueva; todo o nada. | loans:write |
| GET/loans/waitlist | Personas que esperan un horario que se ocupó, por status (waiting de forma predeterminada). | loans:read |
| POST/loans/waitlist | Añade a alguien a la lista de espera de un equipo, una categoría o un espacio y un horario. Cuando queda libre, se reserva a la primera persona cuyo horario encaja y se le envía un correo. | loans:write |
| POST/loans/waitlist/{id}/cancel | Quita a alguien de la lista de espera. | loans:write |
| GET/loans/fees | El libro de tarifas, las más recientes primero (filtre por party_key, kind, status, billing_code, from, to), con los ajustes de tarifas del establecimiento y todas las personas que deben algo o tienen un depósito retenido. Los importes son enteros en la unidad menor de la moneda. vFound registra tarifas; nunca procesa un pago. | loans:read |
| GET/loans/fees/party | Una persona (person_id o party_key): lo que debe por moneda, depósitos retenidos, apuntes y facturas. | loans:read |
| GET/loans/fees/billing-codes | Cobrado, condonado, saldado y aún pendiente por código de facturación y moneda en un periodo; format=csv para un CSV. | loans:read |
| POST/loans/fees/charges | Registra una tarifa por daños, por reposición u otra, o una tarifa con precio por fee_template_id. Se aplica el impuesto del establecimiento salvo que taxable sea false. | loans:write |
| POST/loans/fees/payments | Registra el dinero que el establecimiento cobró por su cuenta (efectivo, su propio terminal de tarjetas, una transferencia). Salda primero los cargos abiertos más antiguos. | loans:write |
| POST/loans/fees/deposits | Registra un depósito que cobró el establecimiento; se retiene hasta que se devuelve o se conserva. | loans:write |
| POST/loans/fees/deposits/{id}/return | Devuelve un depósito retenido. | loans:write |
| POST/loans/fees/deposits/{id}/keep | Conserva un depósito retenido o una parte de él (propietarios y responsables, con un motivo); la parte conservada cuenta como un pago. | loans:write |
| POST/loans/fees/{id}/waive | Condona lo que aún necesita un cargo (propietarios y responsables, con un motivo). | loans:write |
| POST/loans/fees/{id}/void | Anula un pago registrado por error (propietarios y responsables, con un motivo). Anular el pago que generó un depósito conservado vuelve a retener ese importe como depósito. | loans:write |
| GET/loans/{id}/fees | Lo que se ofrece al mostrador para una entrega ya devuelta: la multa por retraso aún no registrada, el valor de reposición cuando se perdió o se dañó, y los depósitos retenidos. | loans:read |
| POST/loans/{id}/late-fine | Añade la multa por retraso de una entrega que volvió con retraso, contada desde que volvió. Una vez por entrega. | loans:write |
| GET/loans/invoices | Facturas, primero el número más reciente. | loans:read |
| POST/loans/invoices | Emite una factura numerada con los cargos abiertos de una persona en una moneda. | loans:write |
| POST/loans/invoices/{id}/void | Anula una factura (propietarios y responsables, con un motivo); reissue pasa sus cargos abiertos a una nueva que la sustituye. | loans:write |
| GET/loans/reservations | Reservas por hora de inicio, filtradas opcionalmente por status o from. | loans:read |
| POST/loans/reservations | Reserva un equipo concreto o un equipo de una categoría para una persona y un periodo. custom_values establece los atributos personalizados del establecimiento para la reserva. | loans:write |
| POST/loans/reservations/{id}/approve | Aprueba una reserva que está esperando revisión. Cuando el establecimiento tiene pasos de aprobación, una clave firma un paso solo en nombre del miembro del equipo que indica en X-Acting-User, una conexión de asistente nunca firma ninguno y nadie firma un paso de una reserva que hizo (approval_not_yours). Reservar sobre un conflicto sigue la misma regla. | loans:write |
| POST/loans/reservations/{id}/cancel | Cancela una reserva pendiente, aprobada o lista. | loans:write |
| POST/loans/reservations/{id}/pickup | Entrega de forma atómica el equipo reservado y cierra la reserva como recogida. | loans:write |
| POST/loans/reservation-groups | Reserva un kit (kit_id) o un carrito (items: un equipo, o una categoría y una cantidad, por línea) para una persona y un periodo: todas las partes o ninguna. Aprobar, cancelar o recoger cualquier parte actúa sobre todas las partes abiertas. | loans:write |
| GET/loans/downtimes | Periodos con fecha en los que un equipo no puede reservarse ni entregarse y que aún no han terminado (item_id limita a un equipo). | loans:read |
| POST/loans/downtimes | Añade un periodo a un equipo: loan_item_id, starts_at, ends_at y un reason opcional. Se rechaza mientras una reserva o una entrega retenga el equipo en cualquier parte de ese tiempo. | loans:write |
| DELETE/loans/downtimes/{id} | Quita un periodo. | loans:write |
| GET/loans/extra-values/{type}/{id} | Los atributos personalizados del establecimiento para una persona (person), una reservation o una checkout, con los campos definidos para ese tipo de registro. | loans:read |
| PUT/loans/extra-values/{type}/{id} | Establece esos atributos, comprobados con los campos del establecimiento y sus condiciones de visibilidad. | loans:write |
| GET/loans/closures | Días en que el mostrador de equipos está cerrado y que aún no han terminado. | loans:read |
| POST/loans/closures | Añade un cierre: fechas starts_on y ends_on en la zona horaria del establecimiento, hasta 366 días. La note opcional es interna; public_message (hasta 300 caracteres) se muestra a los usuarios. Las notas existentes nunca se copian al mensaje para los usuarios. | loans:write |
| DELETE/loans/closures/{id} | Quita un cierre. | loans:write |
| GET/loans/rules | Valores predeterminados del establecimiento, reglas de categoría de duración, límites, bloqueos por retraso, aprobación y reservas (márgenes entre reservas, antelación mínima, con cuánta antelación se puede reservar) y cierres. | loans:read |
| POST/loans/rules | Crea o sustituye una regla de categoría. Los campos de reglas de reserva que se omiten conservan sus valores guardados. | loans:write |
| GET/loans/timeline | Comprobaciones de capacidad por días completos de equipo o categoría. Obligatorias las fechas from y until, inclusivas y en la hora local del establecimiento, como máximo 31 días desde hoy hasta el año próximo; opcionales group=item|category, item_id, category exacta, page (50 filas). Las celdas son true, false o null (incierto). Los días contiguos no garantizan una reserva continua. | loans:read |
| GET/loans/warranties | Fechas de garantía registradas; filter=soon|expired|all, category exacta, page (50 filas). Soon incluye desde hoy hasta 30 días después. La suscripción personal a recordatorios está en el espacio de trabajo. | loans:read |
| GET/loans/utilization | Horas transcurridas por activo a partir del historial de estados registrado. Obligatorias las fechas from y until, inclusivas y en la hora local del establecimiento, dentro de los últimos 365 días y limitadas al momento actual; opcionales item_id, category exacta, format=csv. JSON da segundos exactos; las horas en CSV usan seis decimales. Disponible incluye lo entregado; el tiempo de reparación o servicio y otros tiempos no disponibles se excluyen. El tiempo de inactividad anterior se desconoce. Los totales concuerdan con las filas de activos. | loans:read |
| GET/loans/maintenance | Historial de servicio, calibración, pruebas de seguridad, inspección, limpieza, reparación y notas; filtre por equipo, trabajo próximo u órdenes de trabajo (abiertas o todas) y su técnico. | loans:read |
| POST/loans/maintenance | Registra el mantenimiento y la próxima fecha de vencimiento de un equipo. Con plan_id, el trabajo hecho de un plan repetitivo, que inicia su siguiente ronda. | loans:write |
| GET/loans/service-plans | Planes repetitivos de servicio, calibración, pruebas de seguridad, inspección y limpieza, con si cada uno vence por fecha, horas de entrega o número de entregas. | loans:read |
| POST/loans/service-plans | Añade un plan repetitivo a un equipo (propietarios y responsables). | loans:write |
| PUT/loans/maintenance/{id} | Cambia o cierra una orden de trabajo: estado, técnico, proveedor, coste y, para done, su resultado y si el equipo vuelve a estar en servicio. | loans:write |
| GET/loans/maintenance/costs | Coste de servicio, reparación y limpieza por equipo, a partir de apuntes terminados y órdenes de trabajo hechas. | loans:read |
| GET/loans/items/{id}/lifecycle | El registro de compra, amortización, seguro y baja de un equipo, con su valor actual (propietarios y responsables). | loans:read |
| PUT/loans/items/{id}/lifecycle | Guarda el precio de compra, la fecha, el proveedor y el pedido, el método de amortización (lineal o saldo decreciente), la vida útil y el valor residual, y el seguro (propietarios y responsables). | loans:write |
| POST/loans/items/{id}/dispose | Registra cómo salió un equipo (vendido, desechado, donado, reciclado, perdido o robado); se retira y se cancelan sus reservas abiertas y sus órdenes de trabajo. | loans:write |
| DELETE/loans/items/{id}/dispose | Deshace una baja hecha por error; el equipo vuelve a estar disponible. | loans:write |
| GET/loans/valuation | El valor de los equipos en una fecha, al céntimo, con los totales de lo que aún se conserva (propietarios y responsables). | loans:read |
| POST/loans/service-plans/import | Comprueba o añade planes desde un CSV con las columnas documentadas, nombrando los equipos por etiqueta de activo (propietarios y responsables). | loans:write |
| POST/loans/maintenance/work-orders/import | Comprueba o añade órdenes de trabajo abiertas desde un CSV con las columnas documentadas (propietarios y responsables). | loans:write |
| GET/loans/maintenance/planner | Trabajo programado y órdenes de trabajo abiertas por día propio del establecimiento durante hasta 62 días, opcionalmente para un técnico. | loans:read |
| GET/loans/funding | Lo que compró cada fondo, subvención o centro de coste y qué trabajo se le cargó, filtrable por fondo y fechas (propietarios y responsables). Solo un registro: vFound no cobra ningún pago. | loans:read |
| GET/loans/substances | El registro de sustancias peligrosas: sustancia, lugar, clases de peligro y fechas de revisión. Un registro de lo que declara el establecimiento; vFound no da consejos de seguridad. | loans:read |
| POST/loans/substances | Añade una sustancia, con su hoja de datos de seguridad en PDF o foto (propietarios y responsables). | loans:write |
| PUT/loans/substances/{id} | Cambia una sustancia o sustituye su hoja de datos (propietarios y responsables). | loans:write |
| DELETE/loans/substances/{id} | Quita una sustancia y su hoja de datos conservada (propietarios y responsables). | loans:write |
| GET/loans/licences | Licencias de los equipos del establecimiento con puestos, fecha de fin y los equipos en los que están instaladas (propietarios y responsables). No se guarda ninguna clave de licencia. | loans:read |
| POST/loans/licences | Añade una licencia (propietarios y responsables). | loans:write |
| PUT/loans/licences/{id} | Cambia una licencia y dónde está instalada. | loans:write |
| DELETE/loans/licences/{id} | Quita una licencia. | loans:write |
| GET/loans/expiries | Seguros y licencias que terminan pronto o que ya terminaron (propietarios y responsables). | loans:read |
| GET/loans/stocktakes | Inventarios de equipos recientes con recuentos escaneados y faltantes. | loans:read |
| POST/loans/stocktakes | Inicia un inventario abierto para el establecimiento: de todo, de un lugar, una categoría o un kit, o de lo que tiene una persona (custodian_id), asignado opcionalmente a un miembro del equipo (assigned_to). | loans:write |
| POST/loans/stocktakes/{id}/scan | Escanea la etiqueta de un equipo, una etiqueta de activo o un número de serie en el inventario abierto. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | Cuenta hasta 2,000 códigos a la vez (un lector RFID tipo teclado o una lista); cada uno cuenta una vez y los códigos sin coincidencia se devuelven. | loans:write |
| PUT/loans/stocktakes/{id}/assign | Da el inventario abierto a un miembro del equipo para que lo cuente (assigned_to), o a nadie (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | Finaliza el inventario y devuelve la lista de equipos que faltan. | loans:write |
| GET/loans/stocktake-schedules | Inventarios que se abren solos, una vez o de forma repetida. | loans:read |
| POST/loans/stocktake-schedules | Programa un inventario, una vez, cada semana, cada mes, cada tres meses o cada año, a la hora del día propia del establecimiento. | loans:write |
| PATCH/loans/stocktake-schedules/{id} | Cambia, pausa o reanuda una programación. | loans:write |
| DELETE/loans/stocktake-schedules/{id} | Elimina una programación; los inventarios que abrió se conservan. | loans:write |
| GET/loans/last-seen | Dónde se escaneó cada equipo por última vez, cuando el establecimiento guarda posiciones de escaneo (solo de miembros del equipo que lo aceptaron; nunca de una clave). | loans:read |
| GET/loans/transfers | Traslados de equipos entrantes y salientes de este establecimiento. | loans:read |
| POST/loans/transfers | Prepara equipos para otro establecimiento autorizado del mismo grupo de clientes. | loans:write |
| POST/loans/transfers/{id}/send | Registra que los equipos preparados salieron del establecimiento de origen. | loans:write |
| POST/loans/transfers/{id}/receive | Recibe los equipos en el destino con su lugar y su estado de llegada. | loans:write |
| POST/loans/transfers/{id}/cancel | Cancela un traslado preparado antes del envío. | loans:write |
| POST/loans/transfers/{id}/reject | Rechaza un traslado preparado en el destino antes del envío. | loans:write |
| POST/loans/transfers/{id}/exception | Registra un problema mientras los equipos están en tránsito. | loans:write |
| POST/loans/import | Previsualiza o importa hasta 5,000 filas de CSV con encabezados de vFound, Snipe-IT, Sortly o Cheqroom. | loans:write |
Visitors
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/visitors | Visitas, primero las modificadas más recientemente, con status (expected, in, out, cancelled o missed), el visitante, el anfitrión, el código del pase mientras es válido y las horas. Filtros: status, search (visitante, empresa, anfitrión o código del pase), updated_since. | visitors:read |
| GET/visitors/{id} | Una visita. | visitors:read |
| POST/visitors | Invita a un visitante o registra su entrada. Acepta los campos del visitante, del anfitrión y de la hora, además de visitor_type_id, respuestas, fechas de validez y una repetición diaria o por días laborables. | visitors:write |
| POST/visitors/{id}/sign-in | Registra la entrada de un visitante previsto; se avisa al anfitrión. Envíe answers para un miembro del grupo cuyo tipo tenga preguntas obligatorias, y id_expires_on con identity_checked cuando el establecimiento registre la fecha de caducidad de un documento de identidad físico. La visita incluye entonces id_expires_on y id_expired. | visitors:write |
| POST/visitors/{id}/group/sign-in | Registra la entrada de todas las personas del grupo de la visita que se esperan hoy, con un solo correo al anfitrión; quien necesite su propia foto, comprobación de identidad, firma, respuestas o condiciones aparece en skipped. | visitors:write |
| POST/visitors/{id}/sign-out | Registra su salida. | visitors:write |
| POST/visitors/{id}/cancel | Cancela una invitación. | visitors:write |
| POST/visitors/{id}/send-pass | Vuelve a enviar el pase por correo. | visitors:write |
| POST/visitors/{id}/approve | Aprueba una visita pendiente y envía el pase. | visitors:write |
| POST/visitors/{id}/deny | Deniega una visita pendiente. | visitors:write |
| GET/visitors/{id}/badge | Descarga la acreditación imprimible desde el navegador. Elija size 4x3, brother o dymo. | visitors:read |
| GET/visitors/{id}/card | Si la visita tiene una tarjeta RFID y sus últimos cuatro caracteres (nunca el número). Desactivado hasta que el establecimiento active Tarjetas y llaveros. | visitors:read |
| POST/visitors/{id}/card | Da una tarjeta, por su número, a una visita prevista o con entrada registrada; un número está activo en una sola visita a la vez. | visitors:write |
| DELETE/visitors/{id}/card | Recupera la tarjeta. | visitors:write |
| GET/visitors/{id}/assets | Los objetos entregados a la visita, escritos a mano. | visitors:read |
| POST/visitors/{id}/assets | Registra un objeto entregado a la visita, con una etiqueta opcional. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | Marca un objeto como devuelto. | visitors:write |
| GET/visitor-assets/not-returned | Objetos entregados a visitantes y aún no devueltos, los más recientes primero. | visitors:read |
| GET/visitors/{id}/fast-track | Si la visita tiene un código de acceso rápido activo, hasta cuándo y cuántas veces se usó (nunca el código, que solo ve el visitante). | visitors:read |
| POST/visitors/{id}/fast-track | Da a un visitante que vuelve un código de acceso rápido que dura days (de 1 a 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | Recupera el código. | visitors:write |
| GET/visitor-types | Lista los tipos de visitante y sus preguntas, condiciones, acreditaciones, aprobaciones y conservación (retention_days es null cuando el tipo sigue el valor predeterminado del establecimiento). | visitors:read |
| POST/visitor-types | Crea un tipo de visitante. | visitors:write |
| PATCH/visitor-types/{id} | Cambia los campos del tipo de visitante que envíe. | visitors:write |
| DELETE/visitor-types/{id} | Desactiva un tipo de visitante sin cambiar las visitas anteriores. | visitors:write |
| GET/visitor-roll-call | Obtiene el último pase de lista y sus recuentos en tiempo real. Un pase de lista en curso añade a quien haya registrado su entrada desde que empezó; uno que lleve 6 horas en curso se cierra. | visitors:read |
| POST/visitor-roll-call | Inicia un pase de lista, con la opción de incluir a los visitantes previstos hoy y a quien espera aprobación. | visitors:write |
| PATCH/visitor-roll-call/entries/{entry} | Marca una entrada como a salvo o como desaparecida. | visitors:write |
| POST/visitor-roll-call/{id}/finish | Finaliza el pase de lista activo y conserva su informe. | visitors:write |
| GET/staff-attendance | Lista la asistencia del personal en un intervalo de fechas según el reloj del establecimiento (hoy de forma predeterminada, como máximo 366 días), o solo las personas con entrada registrada ahora con open=true. Nunca incluye el correo de la persona. | visitors:read |
| POST/staff-attendance | Registra la entrada (mode office o remote) o la salida de una persona de la lista del personal, con las mismas reglas que el mostrador. Requiere tener activado el registro del personal en el establecimiento. | visitors:write |
| POST/staff-presence | Envía hasta 50 eventos de presencia (in, out o muster) desde su sistema de acreditaciones, de control horario o de Wi-Fi, cada uno nombrando a una persona de la lista del personal por referencia, ID externo o correo. Requiere tener activados en el establecimiento el registro del personal y el flujo de presencia. Responde lo que ocurrió con cada evento, nunca quién. | visitors:write |
| POST/visitors/{id}/catering | Crea, cambia o (sin elementos) elimina la solicitud de catering de una visita prevista o con entrada registrada, entre las opciones que lista el establecimiento. Envía un solo correo a la bandeja de catering del establecimiento; vFound no pide nada ni cobra ningún pago. Requiere tener activado el catering en el establecimiento. | visitors:write |
| GET/workplace/spaces | Lista los puestos de trabajo, las salas de reuniones y las plazas de aparcamiento que las personas pueden reservar en el establecimiento. | visitors:read |
| GET/workplace/free | Busca espacios libres durante todo un periodo (como máximo 7 días), sin contar un puesto reservado para otra persona. | visitors:read |
| GET/workplace/bookings | Lista las reservas de puestos, salas y aparcamiento en un intervalo de como máximo 31 días. Nunca incluye el correo de la persona. | visitors:read |
| POST/workplace/bookings | Reserva un espacio para una persona, una vez o como reserva repetida (diaria o semanal, hasta 52 veces, todo o nada), según las reglas de reserva de Equipment. | visitors:write |
| POST/workplace/bookings/{id}/cancel | Cancela una reserva, o con scope following o series sus fechas posteriores. | visitors:write |
| POST/workplace/bookings/{id}/check-in | Registra la llegada a una reserva, desde 15 minutos antes de que empiece hasta que termine. | visitors:write |
| POST/visitors/{id}/room | Reserva una sala de reuniones para una visita, a la hora de la visita; la sala sigue a la visita. | visitors:write |
| GET/appointment-pages | Lista las páginas de citas del establecimiento, sus horarios y si cada una está abierta ahora a los visitantes. | visitors:read |
| GET/visitor-roll-call/archive | Lista los pases de lista terminados (emergencias, simulacros y avisos), los más recientes primero. | visitors:read |
| GET/visitor-roll-call/{id} | Un pase de lista con sus personas, cronología, rastreos y recuentos de mensajes. | visitors:read |
| POST/visitor-roll-call/{id}/people | Añade a una persona (empleado, otra o contratista) al pase de lista en curso. | visitors:write |
| POST/visitor-roll-call/{id}/scan | Marca a un visitante a salvo desde el enlace o el código de su pase, en un punto de reunión. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | Registra una zona como rastreada y despejada o como con personas dentro. | visitors:write |
| POST/visitor-roll-call/{id}/messages | Envía un mensaje a todos, a las personas que aún no están a salvo o a las que necesitan ayuda. Se envía por correo, aviso del navegador y, con el proveedor propio del establecimiento, SMS o WhatsApp, con un enlace privado para responder que está a salvo o que necesita ayuda. | visitors:write |
| GET/visitor-roll-call/{id}/people/{entry}/messages | La conversación con una persona de un pase de lista: lo que el equipo le envió y lo que respondió desde su enlace privado, la más antigua primero. Responda con el endpoint de mensajes y audience entry. | visitors:read |
| POST/visitor-hazard-alerts | Un aviso que un miembro del equipo escribe y envía a un grupo elegido: hazard, message y group (on_site, visitor_type, host o tenant, con group_ref). Inicia un pase de lista de tipo hazard para ese grupo. vFound no lee ningún flujo de meteorología, noticias o amenazas: no se envía nada salvo que usted envíe esta solicitud. Responde 409 mientras otro pase de lista está en curso. | visitors:write |
| POST/visitor-help-alerts | Pide ayuda con discreción: se avisa a los miembros del equipo elegidos para ello; ningún visitante ve nada. | visitors:write |
| GET/visitor-kiosks | Lista los quioscos vinculados, pendientes y revocados. | visitors:read |
| POST/visitor-kiosks/pairing | Crea un código de vinculación de ocho caracteres que dura diez minutos. | visitors:write |
| DELETE/visitor-kiosks/{id} | Revoca un quiosco. | visitors:write |
| PUT/visitor-kiosks/{id}/settings | Cambia los ajustes de un quiosco: un correo cuando no se le ha visto durante un número de minutos, volver al inicio tras un tiempo de inactividad, una firma al registrar la entrada y la impresión de la acreditación desde la tableta. Todo empieza desactivado. | visitors:write |
| GET/visitor-analytics | Totales por día, hora, tipo y anfitrión, además de la estancia media del último año. | visitors:read |
| GET/visitor-registration | Obtiene el enlace de autorregistro del establecimiento y si está activado. | visitors:read |
| GET/school/movements | Llegadas tarde y salidas anticipadas del alumnado, las más antiguas primero, desde since (por defecto las últimas 24 horas), con la reference de cada alumno para el sistema de información escolar. Un miembro del equipo con rol de solo lectura, indicado en X-Acting-User, no puede usarlo. | school:read |
| PUT/school/pupils | Añade o actualiza hasta 500 alumnos por reference; envíe active false para un alumno que se fue. Aquí no se elimina nada. | school:write |
Los datos de los visitantes son datos personales: consérvelos solo el tiempo que los necesite.
Personas
La lista de personas contiene a los residentes, el personal o los estudiantes a quienes atiende su mostrador. Parcels busca en ella a los destinatarios, Visitors busca anfitriones y Equipment sugiere usuarios. Manténgala sincronizada con su sistema de RR. HH., de estudiantes o de gestión inmobiliaria mediante la API.
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/people | La lista, por nombre. Filtros: search (nombre, correo, unidad o referencia), updated_since. | people:read |
| GET/people/{id} | Una persona. | people:read |
| POST/people | Añade a alguien: name (obligatorio), email, unit, reference y language para sus correos. | people:write |
| POST/people/upsert | Añade o actualiza hasta 500 personas en una sola llamada: people es una lista de los mismos campos. Se actualiza a quien ya tenga su correo en la lista. Responde cuántas se añadieron, se actualizaron y se omitieron. | people:write |
| PATCH/people/{id} | Cambia solo los campos que envíe. | people:write |
| DELETE/people/{id} | Elimina a alguien. Sus paquetes, visitas y entregas conservan el nombre que tenía. | people:write |
| GET/people/export | Descarga la lista completa de personas como CSV a prueba de fórmulas. | people:read |
| POST/people/{id}/send-my-vfound | Envía por correo a una persona activa la página firmada con sus paquetes, visitantes y equipos vinculados. | people:write |
| GET/people/sync-source | Muestra el directorio CSV guardado y el último resultado de sincronización. | people:read |
| PUT/people/sync-source | Guarda una url de CSV pública por HTTPS y un mode (upsert o mirror). | people:write |
| DELETE/people/sync-source | Quita la conexión y conserva las personas ya importadas. | people:write |
| POST/people/sync-source/run | Ejecuta ahora la conexión guardada. | people:write |
Los propietarios y responsables también pueden conectar desde Personas un enlace CSV público por HTTPS. vFound lo comprueba cada hora, sigue como máximo tres redirecciones tras comprobar cada destino, acepta como máximo 10 MB y, en modo mirror, se detiene antes de hacer cambios cuando el número de filas válidas baja más de un 30 por ciento. Los campos conectados se cambian en su origen.
Aprovisionamiento automático desde el directorio
Microsoft Entra tiene la conexión preparada, configurada por el cliente, descrita más arriba. Los directorios de identidad, incluidos Okta, OneLogin y JumpCloud, pueden en cambio aprovisionar la lista de personas en https://vfound.io/api/scim/v2/Users con una clave de API de vFound que tenga people:write. Use la clave bearer como token secreto. Al desactivar, la persona deja de aparecer en las sugerencias; DELETE anonimiza los vínculos con las mismas reglas de Personas. Este endpoint solo crea entradas de la lista de personas y nunca accesos del equipo.
Las listas de formación de Equipment pueden proceder del mismo directorio: vincule una formación con un grupo del directorio por su nombre (Equipment, Políticas, Formación) y asigne después ese grupo a la aplicación de vFound. https://vfound.io/api/scim/v2/Groups responde solo por los grupos que nombra una formación y rechaza cualquier otro grupo. Sus miembros son las personas (por su ID de usuario SCIM) que tienen la formación; una persona que sale del grupo pierde la formación solo cuando la concedió el directorio, así que un registro añadido por el personal se conserva. Un registro concedido por el directorio que ha caducado se renueva desde ese día cuando el directorio vuelve a enviar el grupo con la persona todavía en él. Los grupos responden solo en un establecimiento con Equipment. Como la pertenencia a un grupo concede una formación, y una formación permite a las personas retirar el equipo que la requiere, una clave con people:write puede conceder formaciones de este modo: reserve esa clave para su proveedor de identidad.
Webhooks
Añada hasta 25 direcciones HTTPS en Ajustes, Para desarrolladores, o mediante la API que figura más abajo, y elija cuáles de los eventos siguientes recibe cada una. vFound envía un POST JSON en cuestión de segundos, reintenta los fallos durante unas tres horas y pausa una dirección tras 15 envíos fallidos seguidos.
| Evento | Cuándo | Datos |
|---|---|---|
item.created | Se añade un objeto encontrado | Objeto |
item.updated | Cambia su estado, título, lugar, categoría, fecha de conservación o visibilidad de la foto | Objeto |
item.transfer_sent | Se envía un objeto encontrado a otro establecimiento del grupo (ambos establecimientos lo reciben) | Traslado de objeto |
item.transfer_cancelled | El establecimiento emisor lo recupera antes de que llegue | Traslado de objeto |
item.transfer_received | El establecimiento receptor confirma que llegó | Traslado de objeto |
claim.created | Un visitante envía una reclamación | Reclamación |
item.disposition_recorded | Se dona o se elimina un objeto | Objeto |
item.match_updated | Cambia un veredicto de coincidencia de IA guardado; report_id, item_id, label y reason | Par de coincidencia |
lost_report.match_updated | Cambia un veredicto de coincidencia de IA guardado; report_id, item_id, label y reason | Par de coincidencia |
claim.ownership_reviewed | Un responsable registra una revisión de titularidad; consulte la custodia para ver el historial de revisiones | Reclamación |
claim.decision_recorded | Se acepta o se rechaza una reclamación | Reclamación |
claim.release_approved | Un responsable distinto aprueba la entrega | Reclamación |
claim.handover_recorded | La recogida física cierra una reclamación lista para recoger | Reclamación |
claim.status_changed | Una reclamación pasa a un estado nuevo | Reclamación |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | Un visitante comunica una pérdida | Aviso de pérdida |
parcel.logged | Se registra un paquete en el mostrador o mediante la API | Paquete |
parcel.updated | Cambia cualquiera de sus datos en el mostrador, como el destinatario, el número de seguimiento o el estante | Paquete |
parcel.reminded | Se envía un recordatorio al destinatario, desde el mostrador o de forma automática | Paquete |
parcel.collected | Se entrega un paquete | Paquete |
parcel.returned | Se devuelve un paquete al remitente | Paquete |
parcel.recipient_arrived | Un destinatario dice que está en el mostrador | Entrada de la fila de recogida |
parcel.reminders_snoozed | Un destinatario pausa sus recordatorios | Persona y número de paquetes |
parcel.held | Un destinatario fija una fecha de retención | Persona, fecha y número de paquetes |
parcel.proxy_created | Un destinatario envía por correo un código de recogida a un delegado | Persona, delegado y caducidad |
parcel.pickup_served | El mostrador marca una llegada como atendida | Entrada de la fila de recogida |
parcel.escalated | Un paquete en espera alcanza la antigüedad de escalado del establecimiento | Paquete |
parcel.outgoing_logged | Se registra un paquete saliente | Paquete saliente |
parcel.outgoing_handed_over | Un paquete saliente se entrega a un mensajero | Entrega del paquete saliente |
parcel.round_created | Se crea una ronda de reparto | Resumen de la ronda |
parcel.round_delivered | Se completa una parada de una ronda de reparto | Identificadores de la ronda, la parada y el paquete |
checkroom.checked_in | Se registra la entrada de algo y se le asigna un número | Ticket |
checkroom.handed_back | Se devuelve | Ticket |
checkroom.left | Se cierra la noche con ello todavía en el guardarropa | Ticket |
checkroom.self_checkin_started | Un cliente inicia un ticket desde un quiosco vinculado | Ticket |
checkroom.ready_requested | Un cliente pide al mostrador que le prepare sus cosas | Ticket |
checkroom.ready | El mostrador marca como listas las cosas de un cliente | Ticket |
checkroom.station_created | Se crea un puesto de guardarropa | Puesto |
checkroom.station_updated | Cambia un puesto de guardarropa | Puesto |
checkroom.event_created | Se crea un evento de guardarropa | Evento |
checkroom.event_updated | Cambia un evento de guardarropa | Evento |
loan.checked_out | Se entrega un equipo | Entrega |
loan.due_soon | Su hora límite está a menos de dos horas, una vez por hora límite | Entrega |
loan.overdue | Pasa su hora límite y no ha vuelto, una vez por hora límite | Entrega |
loan.extended | Cambia su hora límite | Entrega |
loan.returned | Vuelve al mostrador | Entrega |
loan.lost | Se registra que no volverá | Entrega |
loan.checkout_created | Se crea una entrega atómica de varios equipos | Entrega, con las existencias del mismo recibo en stock |
loan.self_checkout | Una persona completa la entrega en el quiosco | Entrega |
loan.kit_created | Se crea un kit de equipos guardado | Kit |
loan.kit_updated | Cambia un kit de equipos guardado | Kit |
loan.reservation_requested | Una reserva espera aprobación | Reserva |
loan.reservation_created | Una reserva se confirma de inmediato | Reserva |
loan.reservation_approved | Se aprueba una reserva pendiente | Reserva |
loan.reservation_ready | El equipo reservado está listo para recoger | Reserva |
loan.reservation_cancelled | Se cancela una reserva | Reserva |
loan.reservation_collected | Se entrega el equipo reservado | Entrega |
loan.extension_requested | Una persona pide más tiempo | Entrega |
loan.problem_reported | Una persona comunica un problema con un equipo | Entrega |
loan.rule_updated | Cambia una regla de entrega de una categoría | Regla |
loan.maintenance_logged | Se registra un mantenimiento | Mantenimiento |
loan.maintenance_due | Un mantenimiento programado llega a su fecha | Mantenimiento |
loan.service_due | Un plan de servicio repetitivo llega a su fecha (por fecha, horas de entrega o número de entregas), una vez por ronda | Mantenimiento |
loan.work_order_opened | Se abre una orden de trabajo, por el personal o por una devolución para la que el establecimiento pide abrir una | Mantenimiento |
loan.work_order_closed | Una orden de trabajo se completa o se cancela | Mantenimiento |
loan.item_disposed | Se da de baja un equipo (vendido, desechado, donado, reciclado, perdido o robado) | Equipment |
loan.stocktake_started | Empieza un inventario de equipos | Inventario |
loan.stocktake_completed | Termina un inventario de equipos | Inventario |
loan.transfer_prepared | Un establecimiento autorizado prepara equipos para trasladarlos | Traslado |
loan.transfer_sent | Los equipos preparados salen de su establecimiento de origen | Traslado |
loan.transfer_received | El destino recibe los equipos | Traslado |
loan.transfer_rejected | El destino rechaza un traslado preparado | Traslado |
loan.transfer_cancelled | El origen cancela un traslado preparado | Traslado |
loan.transfer_exception | Un traslado en tránsito necesita atención | Traslado |
loan.transfer_lost | El origen cierra un traslado que nunca llegó | Traslado |
loan.charge_recorded | Se registra un cargo por multa, daño, reposición, uso u otro concepto | Apunte de tarifas |
loan.charge_waived | Un responsable condona lo que aún necesita un cargo, con un motivo | Apunte de tarifas |
loan.payment_recorded | El personal registra dinero que el establecimiento cobró por su cuenta (vFound nunca procesa un pago) | Apunte de tarifas |
loan.payment_voided | Un responsable anula un pago registrado por error | Apunte de tarifas |
loan.deposit_recorded | El personal registra un depósito que cobró el establecimiento | Apunte de tarifas |
loan.deposit_resolved | Se devuelve o se conserva un depósito retenido | Apunte de tarifas |
loan.invoice_issued | Se emite una factura por los cargos de una persona | Factura |
loan.invoice_voided | Un responsable anula una factura, con un motivo | Factura |
loan.quote_accepted | El equipo acepta un presupuesto y se crean sus reservas | Presupuesto |
loan.payment_request_created | El equipo registra una solicitud de pago (no se envía nada a la persona) | Solicitud de pago |
loan.payment_request_paid | Los pagos registrados contra una solicitud la cubren por completo | Solicitud de pago |
loan.delivery_done | Se marca como hecha una entrega o una recogida | Entrega |
loan.items_imported | Se completa una importación de equipos desde CSV | Recuentos |
visit.expected | Se invita a un visitante | Visita |
visit.signed_in | Un visitante registra su entrada, en el mostrador o desde su cartel con QR | Visita |
visit.host_confirmed | El mostrador confirma a quién venía a ver un visitante que registró su propia entrada | Visita |
visit.signed_out | Registra su salida, en el mostrador, desde su pase o automáticamente al terminar el día | Visita |
visit.cancelled | Se cancela una invitación | Visita |
visit.approval_requested | Una visita espera la aprobación del personal | Visita |
visit.approved | Se aprueba una visita pendiente | Visita |
visit.denied | Se deniega una visita pendiente | Visita |
visit.host_replied | Un anfitrión responde desde su enlace privado | Visita |
visit.roll_call_started | Empieza un pase de lista en vivo (una emergencia, un simulacro o un aviso) | Resumen del pase de lista |
visit.roll_call_completed | Termina un pase de lista en vivo | Resumen del pase de lista |
visitor_type.created | Se crea un tipo de visitante | Tipo de visitante |
visitor_type.updated | Cambia un tipo de visitante | Tipo de visitante |
visitor_type.deactivated | Se desactiva un tipo de visitante | Tipo de visitante |
visitor_agreement.signed | Un visitante firmó un documento de acuerdo, con un enlace a la copia firmada que funciona durante siete días | Firma de acuerdo |
kiosk.paired | Se vincula un quiosco de visitantes | Quiosco |
kiosk.revoked | Se revoca un quiosco de visitantes | Quiosco |
courier.signed_in | Se registra en Parcels a un visitante de reparto | Mensajero |
courier.signed_out | Se va un visitante de reparto | Mensajero |
staff.signed_in | Una persona de la lista del personal registra su entrada, en la oficina o a distancia | Asistencia del personal |
staff.signed_out | Una persona de la lista del personal registra su salida, o se registra su salida automáticamente | Asistencia del personal |
person.created | Se añade una persona | Persona |
person.updated | Se cambia una persona | Persona |
person.deactivated | El aprovisionamiento desde el directorio desactiva a una persona | Persona |
person.deleted | Se elimina una persona | Persona |
people.sync.completed | Se completa una sincronización de CSV conectado | Recuentos |
people.sync.failed | Una sincronización de CSV conectado falla de forma segura | Error |
report.delivered | Se ejecuta un informe programado de Informes y analítica, compartido con el establecimiento, con envío a los webhooks elegidos (un informe privado nunca se envía a webhooks); suscríbase en Ajustes, Para desarrolladores (una clave de API no puede suscribirse) | Todas las columnas que nombra el informe y hasta 5,000 filas, o todos los grupos |
queue.ticket_joined | Una persona se incorpora a una fila, desde su teléfono, un quiosco, el mostrador o la API | Ticket de la fila |
queue.ticket_called | Se llama a una persona a un mostrador, o se la vuelve a llamar | Ticket de la fila |
queue.ticket_served | Se marca a una persona como atendida | Ticket de la fila |
queue.ticket_no_show | Se marca como ausencia a una persona llamada, por el equipo o pasados los minutos de la fila | Ticket de la fila |
queue.ticket_left | Una persona sale de la fila desde su ticket, o el equipo la saca | Ticket de la fila |
queue.ticket_transferred | Se traslada a una persona a otra fila o a otro mostrador | Ticket de la fila |
queue.ticket_closed | Se cierra un ticket que sigue abierto al terminar el día del establecimiento, o en una fila archivada | Ticket de la fila |
queue.booking_created | Una persona reserva una hora en la página de horas reservadas de una fila, o la API reserva una | Reserva de la fila |
queue.booking_cancelled | La persona, el equipo o la API cancelan una hora reservada | Reserva de la fila |
queue.ticket_arrived | Una persona que se incorporó antes de llegar dice que ya está aquí, o el equipo la marca como llegada | Ticket de la fila |
queue.message_received | Una persona en la fila escribe al equipo desde la página de su ticket; el evento no incluye las palabras | Mensaje de la fila |
queue.message_sent | El equipo escribe a una persona en la fila; el evento no incluye las palabras | Mensaje de la fila |
queue.survey_answered | Una persona atendida responde a la encuesta; el evento incluye la valoración y nunca el comentario | Respuesta a la encuesta de la fila |
{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
"venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}
Comprobar la firma
Cada envío incluye Vfound-Signature: t=<unix time>,v1=<hex>, donde el hexadecimal es un HMAC SHA256 de t + "." + raw body con el secreto de su endpoint. Rechace los envíos de más de cinco minutos. Después de crear un nuevo secreto de firma, los envíos incluyen dos valores v1 durante 24 horas, uno por cada secreto, así que acepte el envío si coincide cualquiera de ellos.
// Node.js
const crypto = require("crypto");
function verified(rawBody, header, secret) {
const parts = header.split(",").map((p) => p.split("="));
const t = (parts.find(([k]) => k === "t") || [])[1];
const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && parts.some(([k, v]) => k === "v1" && v.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v)));
}
// PHP
$t = null; $signatures = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', $part, 2), 2, '');
if ($k === 't') { $t = $v; } elseif ($k === 'v1') { $signatures[] = $v; }
}
$expected = hash_hmac('sha256', $t.'.'.$rawBody, $secret);
$ok = abs(time() - (int) $t) < 300
&& count(array_filter($signatures, fn ($s) => hash_equals($expected, $s))) > 0;
Los encabezados incluyen también Vfound-Event y un identificador único Vfound-Delivery que puede usar para ignorar repeticiones. Los webhooks se envían solo a direcciones HTTPS públicas en el puerto 443.
Suscribirse mediante la API
Herramientas como Zapier pueden añadir y quitar sus propias direcciones con una clave que tenga webhooks:manage. El secreto de firma se muestra una sola vez, en la respuesta al POST. La respuesta incluye también un encabezado Location con la dirección a la que llamar con DELETE cuando se quite la suscripción.
Una clave solo puede suscribirse a eventos cuyos datos podría leer: cada evento necesita el alcance de lectura de su producto (items:read para eventos de objetos, claims:read para eventos de reclamaciones, lost_reports:read, parcels:read, checkroom:read, loans:read para eventos de equipos, visitors:read para eventos de visitas, tipos de visitante, quioscos y mensajeros, y people:read para eventos de personas y de la lista de personas). Una clave lista y quita solo las direcciones que creó ella misma; las direcciones añadidas en Ajustes, o por otra clave, no le son visibles.
| Solicitud | Qué hace | Alcance |
|---|---|---|
| GET/webhooks | Las direcciones que creó esta clave y sus eventos. | webhooks:manage |
| POST/webhooks | Añade una dirección: url (HTTPS público en el puerto 443) y events, una lista de los eventos anteriores que la clave puede leer. | webhooks:manage |
| DELETE/webhooks/{id} | Quita una dirección que creó esta clave y su historial de envíos. | webhooks:manage |
Historial de envíos
Ajustes, Para desarrolladores, lista todos los envíos a cada dirección de los últimos 30 días, con cómo fueron, y puede volver a enviar cualquiera de ellos con el mismo identificador Vfound-Delivery. Allí también puede editar una dirección, volver a activar una pausada y crear un nuevo secreto de firma. Una dirección que falla 15 envíos seguidos se pausa, y el propietario del establecimiento recibe un correo.
Fuente de datos de informes (Power BI)
Un propietario o responsable crea un enlace de fuente de datos en Informes y analítica, en Fuente de datos para Power BI, para los productos que elija. El enlace se muestra una sola vez. En Power BI elija Obtener datos, después Web, y péguelo. Cada enlace lee un solo establecimiento y deja de funcionar al instante cuando se revoca, cuando la persona que lo creó deja de ser propietaria o responsable del establecimiento, o cuando el establecimiento se pausa o se cierra.
GET /api/feeds/reports/{token}/{dataset} responde con las filas de un conjunto de datos: equipment_loans, equipment_activity, visits o checkroom_tickets. Elija su periodo con days (de 1 a 366, 90 si se omite) o con from y to (AAAA-MM-DD, según el reloj del establecimiento). GET /api/feeds/reports/{token}/saved/{id} responde con un informe guardado compartido con todo el establecimiento, para el propio periodo de ese informe; days, from y to no lo cambian. También puede enviar el token como Authorization: Bearer <token> a /api/feeds/reports/{dataset} o /api/feeds/reports/saved/{id}. Una respuesta contiene hasta 100,000 filas en value, así que Obtener datos, Web lee el resultado completo; después convierta la lista value en una tabla. La respuesta termina con total y truncated: cuando coinciden más filas de las que cabe en una respuesta, truncated es true y @odata.nextLink nombra el resto ($top y $skip recorren las páginas, para las herramientas que lo siguen); Obtener datos, Web no lo sigue, así que elija un periodo más corto. Cuando las filas de un informe requerirían leer más de 400,000 filas o más de 20 segundos, la respuesta termina con error, total null y truncated true; un informe guardado agrupado responde 422 con el motivo en su lugar. Las filas llegan en el orden en que se registraron. Las horas de las filas están en UTC (ISO 8601); un informe guardado agrupado por una fecha etiqueta cada grupo por el día, la semana, el mes, el día de la semana o la hora según el reloj del establecimiento. Las direcciones de correo y el nombre y la habitación de un cliente de guardarropa se omiten, salvo que el enlace se haya creado para incluir los datos de contacto.
Asistentes de IA (MCP)
vFound es un servidor del Model Context Protocol en https://vfound.io/api/mcp, de modo que los asistentes de IA pueden consultar datos y ayudar en el mostrador. Conecte uno de dos modos: iniciar sesión con vFound, para los asistentes cuyos conectores inician sesión con OAuth, o una clave de API, para los clientes que envían un encabezado, como Claude Code, Cursor y Visual Studio Code. En cualquier caso, solo ve las herramientas que sus alcances permiten, para los productos que su establecimiento tiene abiertos. Un cliente conectado con una clave de API también puede enviar X-Acting-User; cada herramienta se ejecuta entonces como ese miembro del equipo, dentro de su rol.
# Claude Code
claude mcp add --transport http vfound https://vfound.io/api/mcp \
--header "Authorization: Bearer $VFOUND_KEY"
// Cursor (.cursor/mcp.json)
{"mcpServers":{"vfound":{"url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}
// Visual Studio Code (.vscode/mcp.json)
{"servers":{"vfound":{"type":"http","url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}
| Herramienta | Qué hace | Alcance |
|---|---|---|
search_found_items | Buscar objetos encontrados por palabras como “iPhone negro” | items:read |
list_expected_visitors | Visitantes invitados que aún no han llegado | visitors:read |
list_visitors_on_site | Visitantes con la entrada registrada ahora | visitors:read |
list_visitor_types | Tipos de visitante y sus reglas | visitors:read |
visitor_analytics | Totales, patrones y estancia media de visitantes | visitors:read |
visitor_registration_link | El enlace de autorregistro del establecimiento | visitors:read |
list_couriers_on_site | Mensajeros con la entrada registrada mediante Visitors | parcels:read |
list_waiting_parcels | Paquetes que esperan a ser recogidos | parcels:read |
detect_parcel_tracking | Normalizar un número de seguimiento y detectar su operador | parcels:read |
parcel_pickup_queue | Personas que esperan en el mostrador de paquetes | parcels:read |
parcel_shelves | Capacidad y ocupación de los estantes de paquetes | parcels:read |
parcel_analytics | Volumen de paquetes, operadores y rendimiento de recogida | parcels:read |
list_outgoing_parcels | Paquetes salientes y su estado de entrega | parcels:read |
list_parcel_rounds | Rondas de reparto de paquetes y paradas | parcels:read |
list_checkroom_exit_queue | Tickets cuyos clientes esperan en la salida | checkroom:read |
mark_checkroom_ready | Marcar un ticket en espera como listo y avisar al cliente | checkroom:write |
list_checkroom_stations | Puestos de guardarropa y rangos de números | checkroom:read |
list_checkroom_events | Eventos de guardarropa recientes y próximos | checkroom:read |
checkroom_report | Volumen de guardarropa, tiempo de devolución y totales de tarifas | checkroom:read |
list_queue_lines | Filas, personas que esperan y espera estimada ahora | queue:read |
list_queue_waiting | Personas que esperan hoy, en orden de llamada | queue:read |
queue_report | Totales de Queue y mediana de la espera y de los minutos de atención | queue:read |
call_next_in_queue | Llamar a la siguiente persona a un mostrador | queue:write |
mark_queue_ticket_served | Marcar como atendida a la persona que está en un mostrador | queue:write |
list_overdue_equipment | Equipos con retraso, y quién los tiene | loans:read |
list_equipment_kits | Grupos de equipos guardados | loans:read |
create_equipment_kit | Guardar un kit de equipos reutilizable sin entregarlo | loans:write |
list_equipment_reservations | Reservas por hora y estado | loans:read |
reserve_equipment | Reservar un equipo o una categoría sin entregarlo | loans:write |
book_repeating_reservation | Reservar un equipo, una categoría o un espacio cada día o cada semana | loans:write |
move_reservation | Trasladar una reserva a nuevas horas o a otro equipo de su categoría | loans:write |
list_waitlist | Las personas que esperan una hora que se ocupó | loans:read |
join_waitlist | Añadir a alguien a la lista de espera | loans:write |
list_space_bookings | Cada sala, puesto o plaza de aparcamiento y sus reservas entre dos horas | loans:read |
book_space | Reservar una sala o un espacio para una persona y una hora; nunca se entrega | loans:write |
list_equipment_rules | Reglas de entrega del establecimiento y de las categorías | loans:read |
save_equipment_rule | Crear o sustituir una regla de categoría | loans:write |
list_equipment_maintenance | Historial de mantenimiento de equipos y trabajo próximo | loans:read |
list_equipment_service_plans | Planes repetitivos de servicio, calibración, pruebas de seguridad, inspección y limpieza, y cuáles vencen | loans:read |
update_equipment_work_order | Cambiar o cerrar una orden de trabajo de equipos | loans:write |
get_equipment_maintenance_costs | Coste de servicio, reparación y limpieza por equipo | loans:read |
get_equipment_valuation | El valor de los equipos en una fecha tras la amortización (propietarios y responsables) | loans:read |
list_equipment_substances | El registro de sustancias peligrosas: sustancia, lugar, clases de peligro y fechas de revisión (un registro, sin consejos de seguridad) | loans:read |
get_equipment_funding | Lo que compró cada fondo, subvención o centro de coste y qué trabajo se le cargó (propietarios y responsables) | loans:read |
get_equipment_planner | Trabajo programado y órdenes de trabajo abiertas por día propio del establecimiento | loans:read |
list_equipment_licences | Licencias de los equipos con puestos y fechas de fin (propietarios y responsables) | loans:read |
get_equipment_expiries | Seguros y licencias que terminan pronto o que ya terminaron (propietarios y responsables) | loans:read |
log_equipment_maintenance | Registrar un servicio, una calibración, una prueba de seguridad, una inspección, una limpieza, una reparación o una nota | loans:write |
list_equipment_stocktakes | Inventarios recientes y sus recuentos | loans:read |
start_equipment_stocktake | Iniciar un inventario | loans:write |
scan_equipment_stocktake | Registrar un equipo en un inventario abierto | loans:write |
scan_many_equipment_stocktake | Contar muchos códigos a la vez en un inventario abierto | loans:write |
finish_equipment_stocktake | Finalizar un inventario y devolver lo que falta | loans:write |
list_equipment_transfers | Traslados entrantes y salientes sin datos de las personas | loans:read |
preview_equipment_import | Validar un CSV de equipos sin guardarlo | loans:write |
find_person | Buscar a alguien en la lista de personas | people:read |
export_people | Exportar la lista de personas como CSV a prueba de fórmulas | people:read |
directory_sync_status | Comprobar la conexión CSV guardada y su última ejecución | people:read |
run_directory_sync | Ejecutar ahora la conexión CSV guardada | people:write |
email_my_vfound | Enviar por correo a una persona su página privada firmada | people:write |
invite_visitor | Invitar a un visitante, que recibe un pase por correo | visitors:write |
approve_visit | Aprobar una solicitud de visita pendiente | visitors:write |
list_free_workplace_spaces | Buscar puestos, salas de reuniones o aparcamiento libres para un horario | visitors:read |
book_workplace_space | Reservar un puesto, una sala de reuniones o una plaza de aparcamiento para una persona | visitors:write |
request_visit_catering | Pedir catering con una visita, entre las opciones que lista el establecimiento | visitors:write |
list_appointment_pages | Listar las páginas de citas del establecimiento y si cada una está abierta a los visitantes | visitors:read |
list_staff_on_site | Listar las personas de la lista del personal con la entrada registrada ahora, en la oficina o a distancia | visitors:read |
sign_staff_in_or_out | Registrar la entrada o la salida de una persona de la lista del personal | visitors:write |
list_visitor_assets_not_returned | Listar los objetos entregados a visitantes que aún no están marcados como devueltos | visitors:read |
issue_visitor_asset | Registrar un objeto entregado a una visita prevista o con entrada registrada | visitors:write |
return_visitor_asset | Marcar como devuelto un objeto entregado a una visita | visitors:write |
start_roll_call | Iniciar o devolver el pase de lista activo | visitors:write |
mark_visitor_safe | Marcar a un visitante a salvo | visitors:write |
create_kiosk_pairing | Crear un código de vinculación de quiosco de diez minutos | visitors:write |
log_parcel | Registrar un paquete y avisar por correo al destinatario | parcels:write |
remind_parcel | Recordar a un destinatario que recoja un paquete | parcels:write |
remind_parcels | Recordar a hasta 200 destinatarios de paquetes seleccionados | parcels:write |
log_outgoing_parcel | Añadir un paquete saliente al registro de mensajeros | parcels:write |
create_parcel_round | Crear una ronda de reparto a partir de paquetes en espera | parcels:write |
extend_loan | Dar más tiempo a una persona | loans:write |
Cada herramienta ejecuta la solicitud de API anterior con las mismas comprobaciones, así que un asistente nunca puede hacer más que su clave o su conexión. No hay herramientas que entreguen nada, registren la entrada o la salida de nadie, decidan una reclamación ni eliminen. Cada respuesta cuenta para las 120 solicitudes por minuto de la clave o de la conexión.
Iniciar sesión con vFound
Añada https://vfound.io/api/mcp como conector en su propio asistente. El asistente averigua por sí mismo cómo iniciar sesión y abre una página de vFound, donde un propietario o responsable inicia sesión en su espacio de trabajo como siempre, elige el establecimiento, ve en lenguaje sencillo lo que el asistente puede hacer y puede desmarcar cualquier cosa. El personal y los miembros de solo lectura no pueden conectar un asistente. El asistente es el propio de su establecimiento: su suscripción con su proveedor paga su IA, y vFound recibe solo las solicitudes de herramientas que envía.
Una conexión actúa como la persona que la autorizó, con las mismas comprobaciones que una clave de API: deja de funcionar si esa persona ya no gestiona el establecimiento o el establecimiento no está activo, no cambia nada mientras la suscripción está en pausa y solo ve herramientas de los productos abiertos. Su token de acceso dura una hora y el asistente lo renueva por sí mismo; una conexión sin usar durante 30 días vuelve a iniciar sesión. Vea cada una, quién la conectó y cuándo se usó por última vez en Ajustes, Para desarrolladores, donde Desconectar la detiene al instante. El token funciona solo en el endpoint de MCP, no en la API REST; una aplicación que necesite la API REST se conecta como indica la sección siguiente.
Para desarrolladores de clientes: OAuth 2.1 tal como lo describe la especificación de autorización de MCP, solo con el flujo de código de autorización y PKCE (S256). Descubrimiento: /.well-known/oauth-protected-resource (RFC 9728, recurso https://vfound.io/api/mcp) y /.well-known/oauth-authorization-server (RFC 8414); una solicitud sin token recibe un encabezado WWW-Authenticate que nombra el primero. Los clientes se registran por sí mismos en /oauth/register (RFC 7591) como clientes públicos sin secreto; las direcciones de redirección deben usar https, o http solo para localhost o 127.0.0.1, y deben coincidir exactamente. Después /oauth/authorize, /oauth/token (los códigos duran 60 segundos y funcionan una vez; los tokens de actualización se sustituyen en cada uso, y reutilizar uno antiguo desconecta al asistente) y /oauth/revoke (RFC 7009). Los alcances usan los nombres de las claves de API anteriores; envíe resource=https://vfound.io/api/mcp (RFC 8707).
Iniciar sesión con vFound para otras aplicaciones
Una aplicación que no es un asistente de IA, como un sistema de inventario, de reservas o de RR. HH., puede conectarse a la API REST del mismo modo en lugar de con una clave de API: envíe resource=https://vfound.io/api/v1 a /oauth/authorize y /oauth/token, con alcances con los nombres de las claves de API, salvo webhooks:manage, que no se puede conceder a una aplicación. Un propietario o responsable inicia sesión, ve en lenguaje sencillo el nombre de la aplicación y lo que puede hacer, puede desmarcar cualquier cosa y lo autoriza. La conexión actúa como esa persona con las mismas comprobaciones que una clave de API: deja de funcionar si ya no gestiona el establecimiento o el establecimiento no está activo, no cambia nada mientras la suscripción está en pausa y puede hacer 120 solicitudes por minuto, como una clave. X-Acting-User funciona solo con una clave de API. Su token de acceso funciona solo en la API REST, nunca en el endpoint de MCP, y un consentimiento mostrado para una nunca aprueba la otra. Figura en Ajustes, Para desarrolladores como una aplicación que usa la API de vFound, donde Desconectar la detiene al instante. Descubrimiento: /.well-known/oauth-protected-resource/api/v1; el resto es el flujo anterior.
Errores
Los errores son JSON con un message; los errores de validación añaden errors por campo. 401 significa que no hay una clave válida, 403 que falta un alcance, que la persona que creó la clave ya no gestiona el establecimiento, que un miembro del equipo en X-Acting-User no es un miembro activo o que su rol no permite el alcance, que el establecimiento no está activo o que se envió un cambio mientras la suscripción está en pausa, 404 que no se encontró en su establecimiento, 422 que los datos no son válidos y 429 que hay demasiadas solicitudes.
Cuando un cambio no puede hacerse por el estado actual del registro, la respuesta es 422 y además incluye un code estable. Los códigos nunca cambian de nombre:
| Código | Qué significa |
|---|---|
parcel_not_waiting | El paquete ya no está en espera: ya se recogió, se devolvió o se entregó. |
tracking_duplicate | Ya hay aquí en espera un paquete con este número de seguimiento. |
no_email | La persona o el visitante no tiene dirección de correo, así que no se puede enviar nada. |
capacity_full | Todos los números de guardarropa están en uso. |
already_checked_in | El ticket de guardarropa ya tiene la entrada registrada. |
already_handed_back | El ticket de guardarropa ya se devolvió. |
nothing_to_hand_back | El ticket de guardarropa no tiene nada que devolver. |
number_in_use | Ese número de guardarropa ya está en uso. |
ticket_closed | Solo se puede enviar por correo un ticket de guardarropa abierto. |
item_out | El equipo está entregado a alguien. Recíbalo de vuelta primero. |
item_in_repair | El equipo está apartado para reparación. |
item_retired | El equipo está retirado, así que no puede entregarse ni reservarse. |
reservation_conflict | Alguien ha reservado el equipo, o el último libre de su categoría, durante este tiempo, o se espera que siga entregado. |
already_back | El equipo ya se recibió de vuelta. |
not_out | El equipo no está entregado, así que no puede recibir más tiempo ni un recordatorio ni marcarse como que no volverá. |
borrower_overdue | La persona tiene equipos con retraso, y el establecimiento o la categoría no permiten nada más hasta que vuelvan. |
borrower_item_limit | Esto daría a la persona más equipos de los que el establecimiento o la categoría permiten a la vez. |
reservation_not_ready | La reserva aún no está aprobada, o ya se recogió o se canceló. |
reservation_item_mismatch | La entrega no incluye el equipo para el que es la reserva. |
reservation_category_mismatch | La entrega incluye un equipo fuera de la categoría reservada. |
reservation_borrower_mismatch | La reserva pertenece a otra persona. |
reservation_too_long | La reserva dura más de lo que la categoría permite. Solo las reservas hechas desde My vFound están limitadas de este modo. |
reservation_daily_limit | La persona ya hizo 5 reservas desde My vFound en las últimas 24 horas. |
booking_notice | La reserva empieza antes de lo que permite el aviso mínimo de la categoría. |
booking_too_far_ahead | La reserva, la entrega o la nueva hora límite termina más tarde de lo que la categoría puede reservarse con antelación. |
desk_closed | La reserva empezaría un día en que el mostrador de equipos está cerrado. |
kit_unavailable | Una parte de un kit o de un carrito no está disponible para este horario, así que no se reservó nada. El campo unavailable lista cada parte y el motivo. |
borrower_not_in_group | El establecimiento solo permite recibir equipos o reservar a las personas con un tipo de usuario, y esta persona no tiene ninguno (o se escribió en lugar de elegirse de la lista de personas). |
category_not_allowed | Ninguno de los tipos de usuario de la persona permite esta categoría. |
borrower_on_hold | Se ha pausado la entrega de equipos a esta persona: el personal puso un bloqueo, el establecimiento pausa las entregas tras devoluciones tardías repetidas, o debe al menos el importe a partir del cual bloquea el establecimiento (kind charges). El campo hold indica su tipo y hasta cuándo. |
space_too_small | Hay más personas de las que admite la sala o el espacio (su capacidad). |
kit_locked | El equipo pertenece a un kit bloqueado, que sale solo completo: incluya todos los equipos con nombre del kit. |
approval_not_yours | El establecimiento fijó aprobadores en orden y esta persona no es la siguiente (o el establecimiento no permite que nadie se salte un paso por ella). |
project_not_approved | La reserva pertenece a un proyecto que aún no está aprobado, así que no se puede recoger nada. |
not_enough_credits | El establecimiento usa créditos de reserva y a esta persona no le quedan. Dele algunos primero. Una reserva que se cancela o nunca se recoge devuelve su crédito. |
risk_assessment_pending | La reserva tiene una evaluación de riesgo que no se ha aprobado, así que no se puede recoger nada. |
series_unavailable | No se pudo hacer una reserva repetitiva porque al menos una de sus fechas está ocupada o va contra una regla de reserva, así que no se reservó nada. El campo skipped lista cada fecha y el motivo. |
time_available | El horario por el que alguien pidió esperar está libre, así que resérvelo en lugar de unirse a la lista de espera. |
space_not_handed_out | Una sala o un espacio se reserva para su horario y nunca se entrega, así que no puede entregarse ni recogerse. |
stock_short | No hay existencias suficientes de este artículo en el lugar (y lote) indicado, así que no cambió nada. El campo available da la cantidad que hay allí. |
stock_issue_closed | Todo lo de esta entrega de existencias ya volvió o se dio de baja. |
order_closed | Un pedido de compra está terminado o cancelado y no puede cambiar. |
order_over_received | Se introdujo más de lo que aún espera una línea del pedido de compra. |
order_not_placed | No se pueden recibir existencias contra un pedido de compra que aún es un borrador. |
fees_off | Las tarifas están desactivadas para este establecimiento. Actívelas primero en la política de mostrador y de entrega. |
entry_closed | Ese apunte de tarifas o esa factura ya no puede cambiar de este modo: el cargo está saldado o condonado, el pago está anulado, el depósito se devolvió o se conservó, o la factura está anulada. |
on_invoice | El cargo está en una factura emitida. Anule primero la factura y después condone el cargo. |
not_late | La entrega no volvió con retraso según las reglas de multas por retraso del establecimiento, o aún está entregada. |
nothing_to_invoice | La persona no tiene ningún cargo abierto en esa moneda que no esté ya en una factura emitida. |
charge_unavailable | Uno de los cargos elegidos no está abierto, está en otra factura o es de otra persona. |
desk_kept | El puesto está reservado para otra persona en uno de los días pedidos. |
desk_has_bookings | Reservar el puesto para esta persona chocaría con reservas abiertas de otras personas en esos días. Cancele primero esas reservas. |
booking_closed | La reserva del puesto, de la sala o del aparcamiento se canceló o se liberó, así que no se puede registrar la llegada. |
check_in_closed | El registro de llegada se abre 15 minutos antes de que empiece una reserva y se cierra cuando termina. |
item_service_due | El establecimiento impide que salgan los equipos que necesitan trabajo, y la fecha de servicio de este equipo ha llegado o uno de sus planes vence. Registre primero el trabajo. |
item_failed_inspection | El establecimiento impide que salgan los equipos que necesitan trabajo, y la última comprobación de este equipo falló. Registre primero una aprobada. |
work_order_closed | Esta orden de trabajo ya está cerrada y no puede cambiarse. |
already_disposed | Este equipo ya se dio de baja. |
not_disposed | Este equipo no se ha dado de baja, así que no hay nada que deshacer. |
item_disposed | Este equipo se dio de baja. Deshaga la baja antes de volver a usarlo. |
training_required | Una regla de categoría o el equipo requiere una formación que la persona no tiene, o que tiene solo pasada su fecha de caducidad. El campo training indica lo que falta. |
stocktake_open | Ya hay un inventario abierto. Finalícelo primero. |
item_unavailable | El equipo no está disponible o está apartado para reparación, así que no puede iniciar un traslado. |
transfer_open | El equipo ya tiene un traslado abierto. |
transfer_not_ready | Solo se puede enviar un traslado preparado. |
transfer_not_in_transit | Solo se puede recibir un equipo en tránsito o marcarlo con un problema. |
transfer_already_sent | Un traslado enviado ya no puede cancelarse ni rechazarse. |
already_signed_in | El visitante ya tiene la entrada registrada. |
visit_closed | La visita está cerrada. Registre la entrada del visitante como una visita nueva. |
not_signed_in | El visitante no tiene la entrada registrada. |
not_expected | Solo se puede cancelar una visita prevista o enviarle un pase. |
approval_required | La visita necesita aprobación antes de que el visitante pueda registrar su entrada. |
visit_not_valid_today | El pase no puede usarse de nuevo hoy, u hoy está fuera de sus fechas. |
plus_one_not_allowed | El pase no admite acompañantes, o ya no está aprobado, previsto o válido. |
plus_one_limit | El visitante ya añadió a todos los acompañantes que admite el pase. |
nobody_to_sign_in | No se espera hoy a nadie del grupo de la visita. |
visitor_capacity_full | Registrar la entrada del visitante superaría el límite del establecimiento o del tipo de visitante de visitantes con la entrada registrada a la vez. |
Registrar la entrada de un visitante en el mostrador responde 409 con un code cuando el visitante necesita antes la comprobación de un miembro del equipo. La respuesta nombra solo el tipo de coincidencia (blocklist, building, restricted_party o answers); la entrada, su nombre y su motivo son para el equipo del establecimiento y nunca aparecen en una respuesta de la API. Envíe de nuevo la solicitud con screening_reviewed en true solo cuando un miembro del equipo haya comprobado la coincidencia. Eso requiere una clave con el alcance visitors:screening (desactivado de forma predeterminada, como el acceso de cualquier otra clave a él), y una clave que nombra a un miembro del equipo en X-Acting-User necesita uno cuyo rol decida sobre las visitas. La confirmación se registra como de la clave, por su nombre, nunca como del miembro del equipo que creó la clave. Sin el alcance, la respuesta es 403 con screening_scope. Lo mismo se aplica a aprobar una visita que retiene una coincidencia:
| Código | Qué significa |
|---|---|
screening_match | El visitante coincide con una de las listas de bloqueo del establecimiento, una comprobación del equipo o la lista de verificación. Un miembro del equipo debe confirmar que comprobó la coincidencia antes de registrar la entrada del visitante. |
screening_scope | La solicitud confirma o aprueba una coincidencia de verificación, y la clave no tiene el alcance visitors:screening (o el miembro del equipo indicado en X-Acting-User no decide sobre las visitas). |
Listas de comprobación del flujo de trabajo
Un establecimiento con vFound Enterprise puede fijar los pasos que su personal confirma en un momento clave: registrar, entregar, donar o dar de baja un objeto encontrado; entregar o devolver un paquete; registrar la entrada o devolver en el guardarropa; entregar un equipo o recibirlo de vuelta; y registrar la entrada o la salida de un visitante. Mientras se aplica una lista, estas solicitudes aceptan un campo checklist: [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}], o un objeto de clave a true o a texto de nota. Lo aceptan POST /items, PATCH /items/{id}, POST /items/{id}/disposition, POST /claims/{id}/handover, POST /claims/{id}/decision, POST /parcels/{id}/collect, POST /parcels/{id}/return, POST /parcels/bulk-return, POST /parcels/rounds/{round}/stops/{stop}/deliver, POST /checkroom/tickets, POST /checkroom/tickets/{id}/hand-back, POST /loans, POST /loans/{id}/return, POST /loans/returns, POST /loans/checkouts, POST /loans/reservations/{id}/pickup, POST /visitors, POST /visitors/{id}/sign-in y POST /visitors/{id}/sign-out. Sin los pasos obligatorios, la respuesta es 422 con el código checklist_incomplete y un objeto checklist que nombra los pasos que aún faltan por confirmar, y no cambia nada. Cuando no se aplica ninguna lista, el campo se ignora. Las listas completadas, con quién las confirmó y cuándo, están en checklists en las respuestas de un solo objeto, reclamación, paquete, ticket, entrega y visita.
| Código | Qué significa |
|---|---|
checklist_incomplete | 422: se aplica una lista de comprobación del flujo de trabajo a este paso y sus pasos obligatorios no están confirmados. |
Los reintentos con un encabezado Idempotency-Key también pueden responder con un code:
| Código | Qué significa |
|---|---|
idempotency_key_invalid | 400: el encabezado no tiene de 1 a 191 caracteres ASCII visibles. |
idempotency_key_reused | 422: esta clave ya se usó para una solicitud distinta. |
idempotency_in_progress | 409: la primera solicitud con esta clave sigue en curso. Inténtelo de nuevo en breve. |
offline_in_progress | La primera copia de esta acción sin conexión aún se está guardando. El dispositivo la envía de nuevo en breve. |
Una solicitud que nombra a un miembro del equipo en X-Acting-User también puede responder con un code:
| Código | Qué significa |
|---|---|
acting_user_refused | 403: el encabezado no nombra exactamente a un miembro activo del equipo de este establecimiento, o la clave es una conexión creada mediante inicio de sesión. |
acting_user_role | 403: el miembro del equipo nombrado no puede usar el alcance de esta operación con su rol en el establecimiento. |