Inicio de vFoundSolicite su prueba gratuita
DESARROLLADORES

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_…"
AlcancePermiteEndpoints
items:readLeer objetos encontrados, categorías y traslados entre establecimientosGET /items, /items/{id}, /categories, /item-transfers
items:writeAñadir y actualizar objetos encontrados, y enviarlos a otros establecimientos o recibirlos de ellosPOST /items, PATCH /items/{id}, POST /item-transfers y sus acciones de cancelar y recibir
claims:writeRegistrar las revisiones humanas de titularidad, las decisiones, la aprobación de entrega y la recogidaPOST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover
lost_reports:writeCrear avisos de pérdida de visitantes para un centro de contactoPOST /lost-reports
claims:readLeer las reclamaciones, con los datos de contacto de quien reclamaGET /claims, /claims/{id}
lost_reports:readLeer los avisos de pérdida de los visitantesGET /lost-reports
analytics:readLeer el resumen de analíticaGET /analytics
parcels:readLeer los paquetes, con el nombre y el correo de cada destinatarioGET /parcels, /parcels/{id}
parcels:writeRegistrar, entregar, devolver y recordarPOST /parcels y sus acciones
checkroom:readLeer tickets, puestos, eventos, la fila de salida y los informesGET bajo /checkroom
checkroom:writeRegistrar la entrada, devolver, marcar como listo y gestionar puestos o eventosPOST y PUT bajo /checkroom
loans:readLeer los equipos y quién los tieneGET /loans, /loans/items y uno de cada
loans:writeAñadir equipos, entregarlos, ampliar el plazo y recibirlos de vueltaPOST y PATCH bajo /loans
visitors:readLeer las visitasGET /visitors, /visitors/{id}
visitors:writeInvitar, registrar la entrada y la salida, cancelar, enviar un pasePOST /visitors y sus acciones
visitors:screeningConfirmar 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 nombrePOST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve
people:readLeer la lista de personasGET /people, /people/{id}
people:writeAñadir, actualizar, sincronizar y eliminar personasPOST, PATCH y DELETE bajo /people
stays:readLeer el contexto privado de las estancias de hotel y su historial de correccionesGET /stays, /stays/{stay}
stays:writeAñadir o actualizar de forma idempotente el contexto de una estancia desde un sistema hoteleroPOST /stays
school:readLeer las llegadas tarde y las salidas anticipadas del alumnado desde la secretaríaGET /school/movements
school:writeAñadir o actualizar alumnos desde el sistema de información escolarPUT /school/pupils
queue:readLeer filas, tickets, horas reservadas, mensajes, cifras de encuestas y el informe de la filaGET bajo /queue
queue:writeAñadir personas a una fila, llamarlas, finalizar sus tickets, reservar y cancelar horas y escribir a las personas en filaPOST bajo /queue
webhooks:manageSuscribir y cancelar la suscripción de las direcciones de webhook propias de la clave, para eventos cuyos datos la clave puede leerGET, 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.

SistemaQué lee vFoundÁreas de vFound
CloudbedsContexto 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 FlexID 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 IDID 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.

Oracle OPERA Cloud no está disponible. El adaptador de servidor con cierre seguro sigue desactivado hasta que se completen el acceso a Oracle, la aprobación del hotel, la configuración exacta del entorno y la aceptación en producción. No se anuncia como certificado ni como validado por clientes.

Objetos

SolicitudQué haceAlcance
GET/itemsObjetos, 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/categoriesLos nombres de categoría que puede usar un objeto.items:read
POST/itemsAñ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-transfersObjetos 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-transfersEnví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}/cancelEl establecimiento emisor recupera el objeto antes de que se reciba.items:write
POST/item-transfers/{id}/receiveEl 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 rutaQué haceAlcance
GET /lost-found/context-schemaLee 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-settingsLee los ajustes opcionales del mostrador.lost_reports:read
PUT /lost-found/desk-settingsSustituye 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-settingsLee los ajustes opcionales del mostrador.checkroom:read
PUT /checkroom/desk-settingsSustituye los ajustes del mostrador; solo propietario o responsable. Los ajustes de correo nuevos están desactivados de forma predeterminada.checkroom:write
GET /lost-found/countsLista las últimas 30 sesiones de recuento por escaneo.items:read
POST /lost-found/countsCaptura 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}/scanRegistra 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}/finishFinaliza un recuento sin modificar objetos.items:write
GET /lost-found/queuesLista 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/queuesGuarda 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-reviewDevuelve indicaciones deterministas de integridad y privacidad; sin IA ni modificaciones.items:read
GET /checkroom/templatesLista 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/templatesGuarda la configuración de puestos de un evento sin visitantes ni tickets; solo responsable.checkroom:write
POST /checkroom/templates/{id}/applyCrea 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 rutaQué haceAlcance
POST /lost-reportsAlta 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}/matchesHasta 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}/matchesIdentificador 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}/verificationRegistre 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}/decisionstatus: 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-approvalUn responsable distinto aprueba la entrega de alto valor ya aceptada, con las mismas comprobaciones que el espacio de trabajo.claims:write
GET /claims/{id}/custodyRevisió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}/handoverRegistra 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}/dispositionkind 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

SolicitudQué haceAlcance
GET/claimsReclamaciones, 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.

SolicitudQué haceAlcance
GET/staysLista 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/staysCrea 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

SolicitudQué haceAlcance
GET/parcelsPaquetes, 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/parcelsRegistra 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}/collectLo entrega: collected_by (obligatorio) y una signature opcional (una URL de datos PNG).parcels:write
POST/parcels/{id}/returnLo devuelve al remitente, con una note opcional.parcels:write
POST/parcels/{id}/remindEnvía al destinatario un correo recordándole que lo recoja.parcels:write
POST/parcels/trackingNormaliza 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-queuePersonas que dijeron estar en el mostrador, con su número de paquetes y sus estantes.parcels:read
POST/parcels/pickup-queue/{id}/serveMarca como atendida una llegada al mostrador.parcels:write
POST/parcels/bulk-remindEnvía recordatorios por correo de hasta 200 paquetes en espera seleccionados.parcels:write
POST/parcels/bulk-returnDevuelve al remitente hasta 200 paquetes en espera seleccionados.parcels:write
GET/parcels/shelvesCapacidades de los estantes de paquetes y ocupación actual.parcels:read
POST/parcels/shelvesCrea un estante o cambia su capacidad.parcels:write
GET/parcels/analyticsVolumen, combinación de operadores, tiempo de recogida, tasa de paquetes sin recoger y estantes más ocupados.parcels:read
GET/parcels/outgoingPaquetes salientes listos para un mensajero o ya entregados.parcels:read
POST/parcels/outgoingRegistra un paquete saliente.parcels:write
POST/parcels/outgoing/{id}/handoffRegistra el mensajero y la firma en la entrega.parcels:write
GET/parcels/roundsRondas de reparto y sus paradas.parcels:read
POST/parcels/roundsCrea una ronda de campus u oficina a partir de paquetes en espera.parcels:write
POST/parcels/rounds/{round}/stops/{stop}/deliverCompleta una parada con el nombre del destinatario y la firma.parcels:write
GET/parcels/couriersMensajeros 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

SolicitudQué haceAlcance
GET/checkroom/ticketsTickets, 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/ticketsRegistra 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-backLo 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/stationsLista los puestos de guardarropa del establecimiento, sus rangos de números y sus lugares de almacenamiento.checkroom:read
POST/checkroom/stationsCrea 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/eventsLista los eventos de guardarropa recientes y próximos.checkroom:read
POST/checkroom/eventsCrea 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-queueTickets cuyos clientes pidieron al mostrador que les prepare sus cosas.checkroom:read
POST/checkroom/tickets/{id}/readyMarca un ticket en espera como listo y avisa al cliente.checkroom:write
GET/checkroom/reportVolumen de tickets, horas pico, tiempo de devolución y tarifas por método y por miembro del personal.checkroom:read
GET/checkroom/exportDescarga 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.

SolicitudQué haceAlcance
GET/queue/linesFilas 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/ticketsTickets 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/reportTickets, 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/ticketsAñade a una persona a una fila, como hace el mostrador.queue:write
POST/queue/call-nextLlama 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}/callLlama a una persona elegida a un mostrador.queue:write
POST/queue/tickets/{id}/servedMarca como atendida a la persona que está en un mostrador.queue:write
POST/queue/tickets/{id}/no-showMarca como ausencia a una persona llamada que no vino.queue:write
POST/queue/tickets/{id}/removeSaca a una persona de la fila.queue:write
GET/queue/bookingsHoras 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/bookingsReserva 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}/cancelCancela una hora reservada; se avisa por correo a la persona de que el equipo la canceló.queue:write
POST/queue/bookings/{id}/arrivedRegistra la llegada de una persona con hora reservada; su ticket se coloca según la hora reservada.queue:write
POST/queue/tickets/{id}/arrivedMarca como presente a una persona que se incorporó antes de llegar.queue:write
GET/queue/tickets/{id}/messagesLos 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}/messagesEscribe a una persona en la fila (body, de 1 a 500 caracteres), como el miembro del equipo de la clave.queue:write
GET/queue/surveyCifras 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/performanceCifras 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}/slotsLas horas reservadas abiertas de una fila, tal como las ofrece su página de reservas.queue:read
POST/queue/joinAsigna 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/lookupBusca tickets por el número que tiene el visitante.queue:read
GET/queue/tickets/{id}/statusLo que muestra la página del ticket del propio visitante: lugar, estimación y frase.queue:read
GET/queue/tickets/{id}/historyLos 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/historyVisitas 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/insightsRecuentos 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-dataLos 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

SolicitudQué haceAlcance
GET/loansEquipos 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/loansEntrega 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}/extendDa más tiempo: un nuevo due_at. Se avisa por correo a la persona de la nueva hora.loans:write
POST/loans/{id}/returnLo recibe de vuelta, con condition opcional (good, damaged o incomplete), note y set_aside para apartar el equipo y repararlo.loans:write
POST/loans/returnsRecibe 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/itemsTodo 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}/ticketsTickets 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/itemsAñ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}/tagSi 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}/tagVincula 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}/tagElimina la etiqueta del equipo.loans:write
POST/loans/checkoutsEntrega 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/kitsGrupos guardados de equipos que suelen entregarse juntos.loans:read
POST/loans/kitsGuarda 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/trainingsLas 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}/holdersQuién tiene una formación, desde cuándo y hasta cuándo, y si ha caducado.loans:read
POST/loans/trainings/{id}/holdersDa 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-typesLos 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}/membersQuién tiene un tipo de usuario.loans:read
POST/loans/borrower-types/{id}/membersAsigna 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/creditsCré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/creditsConcede créditos de reserva a una persona, o retira algunos con un número negativo (propietarios y responsables).loans:write
GET/loans/holdsBloqueos activos de entrega: mientras dura uno, no se entrega nada a la persona y no puede reservar.loans:read
POST/loans/holdsPone 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}/liftLevanta un bloqueo.loans:write
GET/loans/spacesSalas, 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/spacesAñ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/availabilityCada 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}/bookReserva 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}/partsAñ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-partQuita 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/placesLos 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-treeLas 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-modelsModelos 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}/linksLos vínculos de un equipo con otros equipos del mismo establecimiento: funciona con, una alternativa, sustituye a.loans:read
POST/loans/items/{id}/linksVincula 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}/moveTraslada 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-readingsLecturas de contador escritas para un equipo, las más recientes primero.loans:read
POST/loans/items/{id}/meter-readingsRegistra 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/contractsContratos de proveedores vinculados con los equipos que cubren (propietarios y responsables).loans:read
GET/loans/resaleEquipos 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/pointsPuntos de recogida y de devolución que una reserva puede indicar.loans:read
POST/loans/pointsAñ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/projectsProyectos a los que puede pertenecer una reserva. No se recoge nada para un proyecto hasta que se aprueba.loans:read
POST/loans/projectsAñade un proyecto (en espera de aprobación).loans:write
POST/loans/projects/{id}/decisionAprueba o rechaza un proyecto (propietarios y responsables).loans:write
GET/loans/risk-assessmentsEvaluaciones de riesgo en espera de revisión (o por status), con las respuestas de la persona.loans:read
POST/loans/risk-assessments/{id}/reviewAprueba o rechaza una evaluación de riesgo (propietarios y responsables). Un rechazo cancela la reserva.loans:write
POST/loans/reservation-seriesReserva 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}/moveTraslada 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/waitlistPersonas que esperan un horario que se ocupó, por status (waiting de forma predeterminada).loans:read
POST/loans/waitlistAñ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}/cancelQuita a alguien de la lista de espera.loans:write
GET/loans/feesEl 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/partyUna persona (person_id o party_key): lo que debe por moneda, depósitos retenidos, apuntes y facturas.loans:read
GET/loans/fees/billing-codesCobrado, 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/chargesRegistra 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/paymentsRegistra 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/depositsRegistra un depósito que cobró el establecimiento; se retiene hasta que se devuelve o se conserva.loans:write
POST/loans/fees/deposits/{id}/returnDevuelve un depósito retenido.loans:write
POST/loans/fees/deposits/{id}/keepConserva 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}/waiveCondona lo que aún necesita un cargo (propietarios y responsables, con un motivo).loans:write
POST/loans/fees/{id}/voidAnula 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}/feesLo 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-fineAñade la multa por retraso de una entrega que volvió con retraso, contada desde que volvió. Una vez por entrega.loans:write
GET/loans/invoicesFacturas, primero el número más reciente.loans:read
POST/loans/invoicesEmite una factura numerada con los cargos abiertos de una persona en una moneda.loans:write
POST/loans/invoices/{id}/voidAnula una factura (propietarios y responsables, con un motivo); reissue pasa sus cargos abiertos a una nueva que la sustituye.loans:write
GET/loans/reservationsReservas por hora de inicio, filtradas opcionalmente por status o from.loans:read
POST/loans/reservationsReserva 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}/approveAprueba 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}/cancelCancela una reserva pendiente, aprobada o lista.loans:write
POST/loans/reservations/{id}/pickupEntrega de forma atómica el equipo reservado y cierra la reserva como recogida.loans:write
POST/loans/reservation-groupsReserva 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/downtimesPeriodos 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/downtimesAñ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/closuresDías en que el mostrador de equipos está cerrado y que aún no han terminado.loans:read
POST/loans/closuresAñ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/rulesValores 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/rulesCrea o sustituye una regla de categoría. Los campos de reglas de reserva que se omiten conservan sus valores guardados.loans:write
GET/loans/timelineComprobaciones 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/warrantiesFechas 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/utilizationHoras 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/maintenanceHistorial 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/maintenanceRegistra 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-plansPlanes 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-plansAñ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/costsCoste de servicio, reparación y limpieza por equipo, a partir de apuntes terminados y órdenes de trabajo hechas.loans:read
GET/loans/items/{id}/lifecycleEl registro de compra, amortización, seguro y baja de un equipo, con su valor actual (propietarios y responsables).loans:read
PUT/loans/items/{id}/lifecycleGuarda 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}/disposeRegistra 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}/disposeDeshace una baja hecha por error; el equipo vuelve a estar disponible.loans:write
GET/loans/valuationEl 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/importComprueba 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/importComprueba o añade órdenes de trabajo abiertas desde un CSV con las columnas documentadas (propietarios y responsables).loans:write
GET/loans/maintenance/plannerTrabajo 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/fundingLo 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/substancesEl 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/substancesAñ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/licencesLicencias 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/licencesAñ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/expiriesSeguros y licencias que terminan pronto o que ya terminaron (propietarios y responsables).loans:read
GET/loans/stocktakesInventarios de equipos recientes con recuentos escaneados y faltantes.loans:read
POST/loans/stocktakesInicia 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}/scanEscanea 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-manyCuenta 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}/assignDa el inventario abierto a un miembro del equipo para que lo cuente (assigned_to), o a nadie (null).loans:write
POST/loans/stocktakes/{id}/finishFinaliza el inventario y devuelve la lista de equipos que faltan.loans:write
GET/loans/stocktake-schedulesInventarios que se abren solos, una vez o de forma repetida.loans:read
POST/loans/stocktake-schedulesPrograma 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-seenDó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/transfersTraslados de equipos entrantes y salientes de este establecimiento.loans:read
POST/loans/transfersPrepara equipos para otro establecimiento autorizado del mismo grupo de clientes.loans:write
POST/loans/transfers/{id}/sendRegistra que los equipos preparados salieron del establecimiento de origen.loans:write
POST/loans/transfers/{id}/receiveRecibe los equipos en el destino con su lugar y su estado de llegada.loans:write
POST/loans/transfers/{id}/cancelCancela un traslado preparado antes del envío.loans:write
POST/loans/transfers/{id}/rejectRechaza un traslado preparado en el destino antes del envío.loans:write
POST/loans/transfers/{id}/exceptionRegistra un problema mientras los equipos están en tránsito.loans:write
POST/loans/importPrevisualiza o importa hasta 5,000 filas de CSV con encabezados de vFound, Snipe-IT, Sortly o Cheqroom.loans:write

Visitors

SolicitudQué haceAlcance
GET/visitorsVisitas, 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/visitorsInvita 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-inRegistra 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-inRegistra 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-outRegistra su salida.visitors:write
POST/visitors/{id}/cancelCancela una invitación.visitors:write
POST/visitors/{id}/send-passVuelve a enviar el pase por correo.visitors:write
POST/visitors/{id}/approveAprueba una visita pendiente y envía el pase.visitors:write
POST/visitors/{id}/denyDeniega una visita pendiente.visitors:write
GET/visitors/{id}/badgeDescarga la acreditación imprimible desde el navegador. Elija size 4x3, brother o dymo.visitors:read
GET/visitors/{id}/cardSi 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}/cardDa 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}/cardRecupera la tarjeta.visitors:write
GET/visitors/{id}/assetsLos objetos entregados a la visita, escritos a mano.visitors:read
POST/visitors/{id}/assetsRegistra un objeto entregado a la visita, con una etiqueta opcional.visitors:write
POST/visitors/{id}/assets/{asset}/returnMarca un objeto como devuelto.visitors:write
GET/visitor-assets/not-returnedObjetos entregados a visitantes y aún no devueltos, los más recientes primero.visitors:read
GET/visitors/{id}/fast-trackSi 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-trackDa 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-trackRecupera el código.visitors:write
GET/visitor-typesLista 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-typesCrea 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-callObtiene 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-callInicia 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}/finishFinaliza el pase de lista activo y conserva su informe.visitors:write
GET/staff-attendanceLista 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-attendanceRegistra 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-presenceEnví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}/cateringCrea, 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/spacesLista 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/freeBusca espacios libres durante todo un periodo (como máximo 7 días), sin contar un puesto reservado para otra persona.visitors:read
GET/workplace/bookingsLista 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/bookingsReserva 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}/cancelCancela una reserva, o con scope following o series sus fechas posteriores.visitors:write
POST/workplace/bookings/{id}/check-inRegistra la llegada a una reserva, desde 15 minutos antes de que empiece hasta que termine.visitors:write
POST/visitors/{id}/roomReserva una sala de reuniones para una visita, a la hora de la visita; la sala sigue a la visita.visitors:write
GET/appointment-pagesLista 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/archiveLista 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}/peopleAñade a una persona (empleado, otra o contratista) al pase de lista en curso.visitors:write
POST/visitor-roll-call/{id}/scanMarca 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}/sweepsRegistra una zona como rastreada y despejada o como con personas dentro.visitors:write
POST/visitor-roll-call/{id}/messagesEnví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}/messagesLa 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-alertsUn 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-alertsPide ayuda con discreción: se avisa a los miembros del equipo elegidos para ello; ningún visitante ve nada.visitors:write
GET/visitor-kiosksLista los quioscos vinculados, pendientes y revocados.visitors:read
POST/visitor-kiosks/pairingCrea 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}/settingsCambia 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-analyticsTotales por día, hora, tipo y anfitrión, además de la estancia media del último año.visitors:read
GET/visitor-registrationObtiene el enlace de autorregistro del establecimiento y si está activado.visitors:read
GET/school/movementsLlegadas 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/pupilsAñ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.

SolicitudQué haceAlcance
GET/peopleLa lista, por nombre. Filtros: search (nombre, correo, unidad o referencia), updated_since.people:read
GET/people/{id}Una persona.people:read
POST/peopleAñade a alguien: name (obligatorio), email, unit, reference y language para sus correos.people:write
POST/people/upsertAñ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/exportDescarga la lista completa de personas como CSV a prueba de fórmulas.people:read
POST/people/{id}/send-my-vfoundEnvía por correo a una persona activa la página firmada con sus paquetes, visitantes y equipos vinculados.people:write
GET/people/sync-sourceMuestra el directorio CSV guardado y el último resultado de sincronización.people:read
PUT/people/sync-sourceGuarda una url de CSV pública por HTTPS y un mode (upsert o mirror).people:write
DELETE/people/sync-sourceQuita la conexión y conserva las personas ya importadas.people:write
POST/people/sync-source/runEjecuta 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.

EventoCuándoDatos
item.createdSe añade un objeto encontradoObjeto
item.updatedCambia su estado, título, lugar, categoría, fecha de conservación o visibilidad de la fotoObjeto
item.transfer_sentSe envía un objeto encontrado a otro establecimiento del grupo (ambos establecimientos lo reciben)Traslado de objeto
item.transfer_cancelledEl establecimiento emisor lo recupera antes de que llegueTraslado de objeto
item.transfer_receivedEl establecimiento receptor confirma que llegóTraslado de objeto
claim.createdUn visitante envía una reclamaciónReclamación
item.disposition_recordedSe dona o se elimina un objetoObjeto
item.match_updatedCambia un veredicto de coincidencia de IA guardado; report_id, item_id, label y reasonPar de coincidencia
lost_report.match_updatedCambia un veredicto de coincidencia de IA guardado; report_id, item_id, label y reasonPar de coincidencia
claim.ownership_reviewedUn responsable registra una revisión de titularidad; consulte la custodia para ver el historial de revisionesReclamación
claim.decision_recordedSe acepta o se rechaza una reclamaciónReclamación
claim.release_approvedUn responsable distinto aprueba la entregaReclamación
claim.handover_recordedLa recogida física cierra una reclamación lista para recogerReclamación
claim.status_changedUna reclamación pasa a un estado nuevoReclamación
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.createdUn visitante comunica una pérdidaAviso de pérdida
parcel.loggedSe registra un paquete en el mostrador o mediante la APIPaquete
parcel.updatedCambia cualquiera de sus datos en el mostrador, como el destinatario, el número de seguimiento o el estantePaquete
parcel.remindedSe envía un recordatorio al destinatario, desde el mostrador o de forma automáticaPaquete
parcel.collectedSe entrega un paquetePaquete
parcel.returnedSe devuelve un paquete al remitentePaquete
parcel.recipient_arrivedUn destinatario dice que está en el mostradorEntrada de la fila de recogida
parcel.reminders_snoozedUn destinatario pausa sus recordatoriosPersona y número de paquetes
parcel.heldUn destinatario fija una fecha de retenciónPersona, fecha y número de paquetes
parcel.proxy_createdUn destinatario envía por correo un código de recogida a un delegadoPersona, delegado y caducidad
parcel.pickup_servedEl mostrador marca una llegada como atendidaEntrada de la fila de recogida
parcel.escalatedUn paquete en espera alcanza la antigüedad de escalado del establecimientoPaquete
parcel.outgoing_loggedSe registra un paquete salientePaquete saliente
parcel.outgoing_handed_overUn paquete saliente se entrega a un mensajeroEntrega del paquete saliente
parcel.round_createdSe crea una ronda de repartoResumen de la ronda
parcel.round_deliveredSe completa una parada de una ronda de repartoIdentificadores de la ronda, la parada y el paquete
checkroom.checked_inSe registra la entrada de algo y se le asigna un númeroTicket
checkroom.handed_backSe devuelveTicket
checkroom.leftSe cierra la noche con ello todavía en el guardarropaTicket
checkroom.self_checkin_startedUn cliente inicia un ticket desde un quiosco vinculadoTicket
checkroom.ready_requestedUn cliente pide al mostrador que le prepare sus cosasTicket
checkroom.readyEl mostrador marca como listas las cosas de un clienteTicket
checkroom.station_createdSe crea un puesto de guardarropaPuesto
checkroom.station_updatedCambia un puesto de guardarropaPuesto
checkroom.event_createdSe crea un evento de guardarropaEvento
checkroom.event_updatedCambia un evento de guardarropaEvento
loan.checked_outSe entrega un equipoEntrega
loan.due_soonSu hora límite está a menos de dos horas, una vez por hora límiteEntrega
loan.overduePasa su hora límite y no ha vuelto, una vez por hora límiteEntrega
loan.extendedCambia su hora límiteEntrega
loan.returnedVuelve al mostradorEntrega
loan.lostSe registra que no volveráEntrega
loan.checkout_createdSe crea una entrega atómica de varios equiposEntrega, con las existencias del mismo recibo en stock
loan.self_checkoutUna persona completa la entrega en el quioscoEntrega
loan.kit_createdSe crea un kit de equipos guardadoKit
loan.kit_updatedCambia un kit de equipos guardadoKit
loan.reservation_requestedUna reserva espera aprobaciónReserva
loan.reservation_createdUna reserva se confirma de inmediatoReserva
loan.reservation_approvedSe aprueba una reserva pendienteReserva
loan.reservation_readyEl equipo reservado está listo para recogerReserva
loan.reservation_cancelledSe cancela una reservaReserva
loan.reservation_collectedSe entrega el equipo reservadoEntrega
loan.extension_requestedUna persona pide más tiempoEntrega
loan.problem_reportedUna persona comunica un problema con un equipoEntrega
loan.rule_updatedCambia una regla de entrega de una categoríaRegla
loan.maintenance_loggedSe registra un mantenimientoMantenimiento
loan.maintenance_dueUn mantenimiento programado llega a su fechaMantenimiento
loan.service_dueUn plan de servicio repetitivo llega a su fecha (por fecha, horas de entrega o número de entregas), una vez por rondaMantenimiento
loan.work_order_openedSe abre una orden de trabajo, por el personal o por una devolución para la que el establecimiento pide abrir unaMantenimiento
loan.work_order_closedUna orden de trabajo se completa o se cancelaMantenimiento
loan.item_disposedSe da de baja un equipo (vendido, desechado, donado, reciclado, perdido o robado)Equipment
loan.stocktake_startedEmpieza un inventario de equiposInventario
loan.stocktake_completedTermina un inventario de equiposInventario
loan.transfer_preparedUn establecimiento autorizado prepara equipos para trasladarlosTraslado
loan.transfer_sentLos equipos preparados salen de su establecimiento de origenTraslado
loan.transfer_receivedEl destino recibe los equiposTraslado
loan.transfer_rejectedEl destino rechaza un traslado preparadoTraslado
loan.transfer_cancelledEl origen cancela un traslado preparadoTraslado
loan.transfer_exceptionUn traslado en tránsito necesita atenciónTraslado
loan.transfer_lostEl origen cierra un traslado que nunca llegóTraslado
loan.charge_recordedSe registra un cargo por multa, daño, reposición, uso u otro conceptoApunte de tarifas
loan.charge_waivedUn responsable condona lo que aún necesita un cargo, con un motivoApunte de tarifas
loan.payment_recordedEl personal registra dinero que el establecimiento cobró por su cuenta (vFound nunca procesa un pago)Apunte de tarifas
loan.payment_voidedUn responsable anula un pago registrado por errorApunte de tarifas
loan.deposit_recordedEl personal registra un depósito que cobró el establecimientoApunte de tarifas
loan.deposit_resolvedSe devuelve o se conserva un depósito retenidoApunte de tarifas
loan.invoice_issuedSe emite una factura por los cargos de una personaFactura
loan.invoice_voidedUn responsable anula una factura, con un motivoFactura
loan.quote_acceptedEl equipo acepta un presupuesto y se crean sus reservasPresupuesto
loan.payment_request_createdEl equipo registra una solicitud de pago (no se envía nada a la persona)Solicitud de pago
loan.payment_request_paidLos pagos registrados contra una solicitud la cubren por completoSolicitud de pago
loan.delivery_doneSe marca como hecha una entrega o una recogidaEntrega
loan.items_importedSe completa una importación de equipos desde CSVRecuentos
visit.expectedSe invita a un visitanteVisita
visit.signed_inUn visitante registra su entrada, en el mostrador o desde su cartel con QRVisita
visit.host_confirmedEl mostrador confirma a quién venía a ver un visitante que registró su propia entradaVisita
visit.signed_outRegistra su salida, en el mostrador, desde su pase o automáticamente al terminar el díaVisita
visit.cancelledSe cancela una invitaciónVisita
visit.approval_requestedUna visita espera la aprobación del personalVisita
visit.approvedSe aprueba una visita pendienteVisita
visit.deniedSe deniega una visita pendienteVisita
visit.host_repliedUn anfitrión responde desde su enlace privadoVisita
visit.roll_call_startedEmpieza un pase de lista en vivo (una emergencia, un simulacro o un aviso)Resumen del pase de lista
visit.roll_call_completedTermina un pase de lista en vivoResumen del pase de lista
visitor_type.createdSe crea un tipo de visitanteTipo de visitante
visitor_type.updatedCambia un tipo de visitanteTipo de visitante
visitor_type.deactivatedSe desactiva un tipo de visitanteTipo de visitante
visitor_agreement.signedUn visitante firmó un documento de acuerdo, con un enlace a la copia firmada que funciona durante siete díasFirma de acuerdo
kiosk.pairedSe vincula un quiosco de visitantesQuiosco
kiosk.revokedSe revoca un quiosco de visitantesQuiosco
courier.signed_inSe registra en Parcels a un visitante de repartoMensajero
courier.signed_outSe va un visitante de repartoMensajero
staff.signed_inUna persona de la lista del personal registra su entrada, en la oficina o a distanciaAsistencia del personal
staff.signed_outUna persona de la lista del personal registra su salida, o se registra su salida automáticamenteAsistencia del personal
person.createdSe añade una personaPersona
person.updatedSe cambia una personaPersona
person.deactivatedEl aprovisionamiento desde el directorio desactiva a una personaPersona
person.deletedSe elimina una personaPersona
people.sync.completedSe completa una sincronización de CSV conectadoRecuentos
people.sync.failedUna sincronización de CSV conectado falla de forma seguraError
report.deliveredSe 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_joinedUna persona se incorpora a una fila, desde su teléfono, un quiosco, el mostrador o la APITicket de la fila
queue.ticket_calledSe llama a una persona a un mostrador, o se la vuelve a llamarTicket de la fila
queue.ticket_servedSe marca a una persona como atendidaTicket de la fila
queue.ticket_no_showSe marca como ausencia a una persona llamada, por el equipo o pasados los minutos de la filaTicket de la fila
queue.ticket_leftUna persona sale de la fila desde su ticket, o el equipo la sacaTicket de la fila
queue.ticket_transferredSe traslada a una persona a otra fila o a otro mostradorTicket de la fila
queue.ticket_closedSe cierra un ticket que sigue abierto al terminar el día del establecimiento, o en una fila archivadaTicket de la fila
queue.booking_createdUna persona reserva una hora en la página de horas reservadas de una fila, o la API reserva unaReserva de la fila
queue.booking_cancelledLa persona, el equipo o la API cancelan una hora reservadaReserva de la fila
queue.ticket_arrivedUna persona que se incorporó antes de llegar dice que ya está aquí, o el equipo la marca como llegadaTicket de la fila
queue.message_receivedUna persona en la fila escribe al equipo desde la página de su ticket; el evento no incluye las palabrasMensaje de la fila
queue.message_sentEl equipo escribe a una persona en la fila; el evento no incluye las palabrasMensaje de la fila
queue.survey_answeredUna persona atendida responde a la encuesta; el evento incluye la valoración y nunca el comentarioRespuesta 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.

SolicitudQué haceAlcance
GET/webhooksLas direcciones que creó esta clave y sus eventos.webhooks:manage
POST/webhooksAñ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_…"}}}}
HerramientaQué haceAlcance
search_found_itemsBuscar objetos encontrados por palabras como “iPhone negro”items:read
list_expected_visitorsVisitantes invitados que aún no han llegadovisitors:read
list_visitors_on_siteVisitantes con la entrada registrada ahoravisitors:read
list_visitor_typesTipos de visitante y sus reglasvisitors:read
visitor_analyticsTotales, patrones y estancia media de visitantesvisitors:read
visitor_registration_linkEl enlace de autorregistro del establecimientovisitors:read
list_couriers_on_siteMensajeros con la entrada registrada mediante Visitorsparcels:read
list_waiting_parcelsPaquetes que esperan a ser recogidosparcels:read
detect_parcel_trackingNormalizar un número de seguimiento y detectar su operadorparcels:read
parcel_pickup_queuePersonas que esperan en el mostrador de paquetesparcels:read
parcel_shelvesCapacidad y ocupación de los estantes de paquetesparcels:read
parcel_analyticsVolumen de paquetes, operadores y rendimiento de recogidaparcels:read
list_outgoing_parcelsPaquetes salientes y su estado de entregaparcels:read
list_parcel_roundsRondas de reparto de paquetes y paradasparcels:read
list_checkroom_exit_queueTickets cuyos clientes esperan en la salidacheckroom:read
mark_checkroom_readyMarcar un ticket en espera como listo y avisar al clientecheckroom:write
list_checkroom_stationsPuestos de guardarropa y rangos de númeroscheckroom:read
list_checkroom_eventsEventos de guardarropa recientes y próximoscheckroom:read
checkroom_reportVolumen de guardarropa, tiempo de devolución y totales de tarifascheckroom:read
list_queue_linesFilas, personas que esperan y espera estimada ahoraqueue:read
list_queue_waitingPersonas que esperan hoy, en orden de llamadaqueue:read
queue_reportTotales de Queue y mediana de la espera y de los minutos de atenciónqueue:read
call_next_in_queueLlamar a la siguiente persona a un mostradorqueue:write
mark_queue_ticket_servedMarcar como atendida a la persona que está en un mostradorqueue:write
list_overdue_equipmentEquipos con retraso, y quién los tieneloans:read
list_equipment_kitsGrupos de equipos guardadosloans:read
create_equipment_kitGuardar un kit de equipos reutilizable sin entregarloloans:write
list_equipment_reservationsReservas por hora y estadoloans:read
reserve_equipmentReservar un equipo o una categoría sin entregarloloans:write
book_repeating_reservationReservar un equipo, una categoría o un espacio cada día o cada semanaloans:write
move_reservationTrasladar una reserva a nuevas horas o a otro equipo de su categoríaloans:write
list_waitlistLas personas que esperan una hora que se ocupóloans:read
join_waitlistAñadir a alguien a la lista de esperaloans:write
list_space_bookingsCada sala, puesto o plaza de aparcamiento y sus reservas entre dos horasloans:read
book_spaceReservar una sala o un espacio para una persona y una hora; nunca se entregaloans:write
list_equipment_rulesReglas de entrega del establecimiento y de las categoríasloans:read
save_equipment_ruleCrear o sustituir una regla de categoríaloans:write
list_equipment_maintenanceHistorial de mantenimiento de equipos y trabajo próximoloans:read
list_equipment_service_plansPlanes repetitivos de servicio, calibración, pruebas de seguridad, inspección y limpieza, y cuáles vencenloans:read
update_equipment_work_orderCambiar o cerrar una orden de trabajo de equiposloans:write
get_equipment_maintenance_costsCoste de servicio, reparación y limpieza por equipoloans:read
get_equipment_valuationEl valor de los equipos en una fecha tras la amortización (propietarios y responsables)loans:read
list_equipment_substancesEl registro de sustancias peligrosas: sustancia, lugar, clases de peligro y fechas de revisión (un registro, sin consejos de seguridad)loans:read
get_equipment_fundingLo que compró cada fondo, subvención o centro de coste y qué trabajo se le cargó (propietarios y responsables)loans:read
get_equipment_plannerTrabajo programado y órdenes de trabajo abiertas por día propio del establecimientoloans:read
list_equipment_licencesLicencias de los equipos con puestos y fechas de fin (propietarios y responsables)loans:read
get_equipment_expiriesSeguros y licencias que terminan pronto o que ya terminaron (propietarios y responsables)loans:read
log_equipment_maintenanceRegistrar un servicio, una calibración, una prueba de seguridad, una inspección, una limpieza, una reparación o una notaloans:write
list_equipment_stocktakesInventarios recientes y sus recuentosloans:read
start_equipment_stocktakeIniciar un inventarioloans:write
scan_equipment_stocktakeRegistrar un equipo en un inventario abiertoloans:write
scan_many_equipment_stocktakeContar muchos códigos a la vez en un inventario abiertoloans:write
finish_equipment_stocktakeFinalizar un inventario y devolver lo que faltaloans:write
list_equipment_transfersTraslados entrantes y salientes sin datos de las personasloans:read
preview_equipment_importValidar un CSV de equipos sin guardarloloans:write
find_personBuscar a alguien en la lista de personaspeople:read
export_peopleExportar la lista de personas como CSV a prueba de fórmulaspeople:read
directory_sync_statusComprobar la conexión CSV guardada y su última ejecuciónpeople:read
run_directory_syncEjecutar ahora la conexión CSV guardadapeople:write
email_my_vfoundEnviar por correo a una persona su página privada firmadapeople:write
invite_visitorInvitar a un visitante, que recibe un pase por correovisitors:write
approve_visitAprobar una solicitud de visita pendientevisitors:write
list_free_workplace_spacesBuscar puestos, salas de reuniones o aparcamiento libres para un horariovisitors:read
book_workplace_spaceReservar un puesto, una sala de reuniones o una plaza de aparcamiento para una personavisitors:write
request_visit_cateringPedir catering con una visita, entre las opciones que lista el establecimientovisitors:write
list_appointment_pagesListar las páginas de citas del establecimiento y si cada una está abierta a los visitantesvisitors:read
list_staff_on_siteListar las personas de la lista del personal con la entrada registrada ahora, en la oficina o a distanciavisitors:read
sign_staff_in_or_outRegistrar la entrada o la salida de una persona de la lista del personalvisitors:write
list_visitor_assets_not_returnedListar los objetos entregados a visitantes que aún no están marcados como devueltosvisitors:read
issue_visitor_assetRegistrar un objeto entregado a una visita prevista o con entrada registradavisitors:write
return_visitor_assetMarcar como devuelto un objeto entregado a una visitavisitors:write
start_roll_callIniciar o devolver el pase de lista activovisitors:write
mark_visitor_safeMarcar a un visitante a salvovisitors:write
create_kiosk_pairingCrear un código de vinculación de quiosco de diez minutosvisitors:write
log_parcelRegistrar un paquete y avisar por correo al destinatarioparcels:write
remind_parcelRecordar a un destinatario que recoja un paqueteparcels:write
remind_parcelsRecordar a hasta 200 destinatarios de paquetes seleccionadosparcels:write
log_outgoing_parcelAñadir un paquete saliente al registro de mensajerosparcels:write
create_parcel_roundCrear una ronda de reparto a partir de paquetes en esperaparcels:write
extend_loanDar más tiempo a una personaloans: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ódigoQué significa
parcel_not_waitingEl paquete ya no está en espera: ya se recogió, se devolvió o se entregó.
tracking_duplicateYa hay aquí en espera un paquete con este número de seguimiento.
no_emailLa persona o el visitante no tiene dirección de correo, así que no se puede enviar nada.
capacity_fullTodos los números de guardarropa están en uso.
already_checked_inEl ticket de guardarropa ya tiene la entrada registrada.
already_handed_backEl ticket de guardarropa ya se devolvió.
nothing_to_hand_backEl ticket de guardarropa no tiene nada que devolver.
number_in_useEse número de guardarropa ya está en uso.
ticket_closedSolo se puede enviar por correo un ticket de guardarropa abierto.
item_outEl equipo está entregado a alguien. Recíbalo de vuelta primero.
item_in_repairEl equipo está apartado para reparación.
item_retiredEl equipo está retirado, así que no puede entregarse ni reservarse.
reservation_conflictAlguien ha reservado el equipo, o el último libre de su categoría, durante este tiempo, o se espera que siga entregado.
already_backEl equipo ya se recibió de vuelta.
not_outEl equipo no está entregado, así que no puede recibir más tiempo ni un recordatorio ni marcarse como que no volverá.
borrower_overdueLa persona tiene equipos con retraso, y el establecimiento o la categoría no permiten nada más hasta que vuelvan.
borrower_item_limitEsto daría a la persona más equipos de los que el establecimiento o la categoría permiten a la vez.
reservation_not_readyLa reserva aún no está aprobada, o ya se recogió o se canceló.
reservation_item_mismatchLa entrega no incluye el equipo para el que es la reserva.
reservation_category_mismatchLa entrega incluye un equipo fuera de la categoría reservada.
reservation_borrower_mismatchLa reserva pertenece a otra persona.
reservation_too_longLa 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_limitLa persona ya hizo 5 reservas desde My vFound en las últimas 24 horas.
booking_noticeLa reserva empieza antes de lo que permite el aviso mínimo de la categoría.
booking_too_far_aheadLa 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_closedLa reserva empezaría un día en que el mostrador de equipos está cerrado.
kit_unavailableUna 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_groupEl 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_allowedNinguno de los tipos de usuario de la persona permite esta categoría.
borrower_on_holdSe 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_smallHay más personas de las que admite la sala o el espacio (su capacidad).
kit_lockedEl equipo pertenece a un kit bloqueado, que sale solo completo: incluya todos los equipos con nombre del kit.
approval_not_yoursEl 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_approvedLa reserva pertenece a un proyecto que aún no está aprobado, así que no se puede recoger nada.
not_enough_creditsEl 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_pendingLa reserva tiene una evaluación de riesgo que no se ha aprobado, así que no se puede recoger nada.
series_unavailableNo 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_availableEl 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_outUna sala o un espacio se reserva para su horario y nunca se entrega, así que no puede entregarse ni recogerse.
stock_shortNo 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_closedTodo lo de esta entrega de existencias ya volvió o se dio de baja.
order_closedUn pedido de compra está terminado o cancelado y no puede cambiar.
order_over_receivedSe introdujo más de lo que aún espera una línea del pedido de compra.
order_not_placedNo se pueden recibir existencias contra un pedido de compra que aún es un borrador.
fees_offLas tarifas están desactivadas para este establecimiento. Actívelas primero en la política de mostrador y de entrega.
entry_closedEse 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_invoiceEl cargo está en una factura emitida. Anule primero la factura y después condone el cargo.
not_lateLa entrega no volvió con retraso según las reglas de multas por retraso del establecimiento, o aún está entregada.
nothing_to_invoiceLa persona no tiene ningún cargo abierto en esa moneda que no esté ya en una factura emitida.
charge_unavailableUno de los cargos elegidos no está abierto, está en otra factura o es de otra persona.
desk_keptEl puesto está reservado para otra persona en uno de los días pedidos.
desk_has_bookingsReservar el puesto para esta persona chocaría con reservas abiertas de otras personas en esos días. Cancele primero esas reservas.
booking_closedLa reserva del puesto, de la sala o del aparcamiento se canceló o se liberó, así que no se puede registrar la llegada.
check_in_closedEl registro de llegada se abre 15 minutos antes de que empiece una reserva y se cierra cuando termina.
item_service_dueEl 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_inspectionEl establecimiento impide que salgan los equipos que necesitan trabajo, y la última comprobación de este equipo falló. Registre primero una aprobada.
work_order_closedEsta orden de trabajo ya está cerrada y no puede cambiarse.
already_disposedEste equipo ya se dio de baja.
not_disposedEste equipo no se ha dado de baja, así que no hay nada que deshacer.
item_disposedEste equipo se dio de baja. Deshaga la baja antes de volver a usarlo.
training_requiredUna 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_openYa hay un inventario abierto. Finalícelo primero.
item_unavailableEl equipo no está disponible o está apartado para reparación, así que no puede iniciar un traslado.
transfer_openEl equipo ya tiene un traslado abierto.
transfer_not_readySolo se puede enviar un traslado preparado.
transfer_not_in_transitSolo se puede recibir un equipo en tránsito o marcarlo con un problema.
transfer_already_sentUn traslado enviado ya no puede cancelarse ni rechazarse.
already_signed_inEl visitante ya tiene la entrada registrada.
visit_closedLa visita está cerrada. Registre la entrada del visitante como una visita nueva.
not_signed_inEl visitante no tiene la entrada registrada.
not_expectedSolo se puede cancelar una visita prevista o enviarle un pase.
approval_requiredLa visita necesita aprobación antes de que el visitante pueda registrar su entrada.
visit_not_valid_todayEl pase no puede usarse de nuevo hoy, u hoy está fuera de sus fechas.
plus_one_not_allowedEl pase no admite acompañantes, o ya no está aprobado, previsto o válido.
plus_one_limitEl visitante ya añadió a todos los acompañantes que admite el pase.
nobody_to_sign_inNo se espera hoy a nadie del grupo de la visita.
visitor_capacity_fullRegistrar 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ódigoQué significa
screening_matchEl 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_scopeLa 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ódigoQué significa
checklist_incomplete422: 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ódigoQué significa
idempotency_key_invalid400: el encabezado no tiene de 1 a 191 caracteres ASCII visibles.
idempotency_key_reused422: esta clave ya se usó para una solicitud distinta.
idempotency_in_progress409: la primera solicitud con esta clave sigue en curso. Inténtelo de nuevo en breve.
offline_in_progressLa 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ódigoQué significa
acting_user_refused403: 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_role403: el miembro del equipo nombrado no puede usar el alcance de esta operación con su rol en el establecimiento.
¿Tiene preguntas o un caso de uso que debamos admitir? Escríbanos. Leemos todos los mensajes.