L’API et les webhooks de vFound
Connectez la suite vFound aux systèmes que vous utilisez déjà : gestion hôtelière, outils d’assistance, systèmes RH et scolaires, scanners de salle du courrier, entrepôts de données ou vos propres applications. Lisez et modifiez les enregistrements de chaque produit, gardez votre liste de personnes synchronisée, recevez un webhook signé en quelques secondes quand quelque chose se produit, et laissez des assistants IA aider à l’accueil.
Vous souhaitez une configuration guidée ? Consultez les guides d’intégration vFound pour Cloudbeds, OfficeRnD Flex, Microsoft Entra, Slack, Microsoft Teams, Google Chat, les calendriers, Zapier et les clients MCP.
Authentification
Chaque site dispose de l’API. Un propriétaire ou un responsable crée jusqu’à 10 clés dans Réglages, Pour les développeurs, en choisissant ce que chaque clé peut faire. La clé complète s’affiche une seule fois. Envoyez-la comme jeton Bearer :
curl https://vfound.io/api/v1/items \
-H "Authorization: Bearer vf_live_xxxxxxxxxx_…"
| Portée | Autorise | Endpoints |
|---|---|---|
items:read | Lire les objets trouvés, les catégories et les transferts entre sites | GET /items, /items/{id}, /categories, /item-transfers |
items:write | Ajouter et modifier des objets trouvés, et les envoyer ou les recevoir entre sites | POST /items, PATCH /items/{id}, POST /item-transfers et ses actions cancel et receive |
claims:write | Enregistrer les vérifications de propriété faites par une personne, les décisions, l’approbation de restitution et le retrait | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | Créer des déclarations de perte de clients pour un centre de contact | POST /lost-reports |
claims:read | Lire les demandes, avec les coordonnées du demandeur | GET /claims, /claims/{id} |
lost_reports:read | Lire les déclarations de perte des clients | GET /lost-reports |
analytics:read | Lire le résumé des analyses | GET /analytics |
parcels:read | Lire les colis, avec le nom et l’e-mail de chaque destinataire | GET /parcels, /parcels/{id} |
parcels:write | Enregistrer, remettre, retourner et relancer | POST /parcels et ses actions |
checkroom:read | Lire les tickets, les postes, les événements, la file de sortie et les rapports | GET sous /checkroom |
checkroom:write | Enregistrer un dépôt, remettre, marquer comme prêt et gérer les postes ou les événements | POST et PUT sous /checkroom |
loans:read | Lire le matériel et qui l’a | GET /loans, /loans/items et un élément de chaque |
loans:write | Ajouter du matériel, le remettre, prolonger et le reprendre | POST et PATCH sous /loans |
visitors:read | Lire les visites | GET /visitors, /visitors/{id} |
visitors:write | Inviter, enregistrer l’arrivée et le départ, annuler, envoyer un laissez-passer | POST /visitors et ses actions |
visitors:screening | Confirmer qu’une correspondance de contrôle d’un visiteur a été vérifiée : envoyez screening_reviewed, ou approuvez une visite qu’une correspondance retient. Désactivé par défaut ; ce que fait la clé est enregistré comme l’action de la clé, avec son nom | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | Lire la liste de personnes | GET /people, /people/{id} |
people:write | Ajouter, mettre à jour, synchroniser et supprimer des personnes | POST, PATCH et DELETE sous /people |
stays:read | Lire le contexte privé des séjours d’hôtel et son historique de corrections | GET /stays, /stays/{stay} |
stays:write | Ajouter ou mettre à jour de façon idempotente le contexte d’un séjour depuis un système hôtelier | POST /stays |
school:read | Lire les arrivées tardives et les départs anticipés des élèves depuis le secrétariat scolaire | GET /school/movements |
school:write | Ajouter ou mettre à jour des élèves depuis le système d’information de l’école | PUT /school/pupils |
queue:read | Lire les files, les tickets, les créneaux réservés, les messages, les chiffres des enquêtes et le rapport de la file | GET sous /queue |
queue:write | Ajouter des personnes à une file, les appeler, terminer leurs tickets, réserver et annuler des créneaux et écrire aux personnes dans la file | POST sous /queue |
webhooks:manage | Abonner et désabonner les adresses de webhook propres à la clé, pour les événements dont la clé peut lire les données | GET, POST et DELETE /webhooks |
Les objets, les demandes, les déclarations de perte et les analyses exigent vFound Lost & Found ; les colis exigent vFound Parcels ; les tickets exigent vFound Checkroom ; le matériel exige vFound Equipment ; les visites exigent vFound Visitors ; la liste de personnes exige Parcels, Visitors ou Equipment ; les séjours d’hôtel exigent Lost & Found ou Parcels ; le secrétariat scolaire exige Visitors avec le secrétariat scolaire activé (il répond 404 tant qu’il est désactivé) ; les files et les tickets exigent vFound Queue. Un produit qui n’est pas ouvert pour le site répond 403.
Une clé agit au nom de la personne qui l’a créée et cesse de fonctionner si cette personne ne gère plus le site, sauf si la requête nomme un membre de l’équipe dans X-Acting-User (voir Agir pour un membre de l’équipe). Les modifications faites avec une clé suivent les mêmes règles, les mêmes e-mails et la même piste d’audit qu’à l’accueil, et chaque entrée d’audit enregistre la clé qui a fait la modification. Chaque clé peut faire 120 requêtes par minute. Adresse de base : https://vfound.io/api/v1. Les listes renvoient 25 enregistrements par page (jusqu’à 100 avec per_page) et acceptent page ; la plupart se filtrent aussi avec updated_since (ISO 8601) et search, comme indiqué plus bas.
Clés de test
Une clé créée comme clé de test commence par vf_test_ et ne peut détenir que queue:read et queue:write. Elle fonctionne sur une seule file de test étiquetée, Test line (sandbox) (file 1, guichet 1), et nulle part ailleurs : les mêmes adresses Queue qu’une clé réelle pour les files, les créneaux, les tickets, /queue/join, appeler le suivant, appeler, servi, absent et retirer répondent depuis la file de test ; toute autre adresse répond 403 avec code: test_key. Une clé de test ne lit ni ne modifie jamais une vraie file ou un vrai ticket et n’envoie ni e-mail, ni SMS, ni alerte de navigateur, ni webhook. Une clé de test ignore Idempotency-Key : la même requête envoyée deux fois s’exécute deux fois. Les réponses portent "sandbox": true et l’en-tête X-Vfound-Sandbox: 1. Une file de test contient jusqu’à 100 tickets par clé, sans adresse e-mail, et ils sont supprimés avec la clé et après sept jours. Utilisez des noms inventés.
Nouvelles tentatives sans risque
Envoyez un en-tête Idempotency-Key (toute valeur unique d’au plus 191 caractères visibles, comme un UUID) avec un POST, un PATCH ou un DELETE. Si la connexion tombe et que vous renvoyez la même requête avec la même clé dans les 24 heures, vFound ne répète pas la modification : il répond avec la première réponse et l’en-tête Idempotent-Replayed: true. La même clé avec une requête différente est refusée (422, idempotency_key_reused) ; une clé dont la première requête est encore en cours répond 409 (idempotency_in_progress). Une fois effacées les coordonnées de la personne qui a trouvé l’objet ou du demandeur, les réponses enregistrées de ce site renvoient plutôt 410 sans les données effacées ; actualisez l’enregistrement au lieu de réessayer l’ancienne écriture avec une nouvelle clé. Les erreurs du serveur ne sont pas conservées : réessayer après l’une d’elles exécute à nouveau la requête. Une réponse qui contient une donnée affichée une seule fois, comme le secret de signature de POST /webhooks ou un code d’association de borne, n’est jamais conservée non plus : une nouvelle tentative exécute à nouveau la requête, donc vérifiez GET /webhooks avant d’abonner deux fois la même adresse.
Agir pour un membre de l’équipe
Une application que votre équipe utilise à l’accueil, comme une application de poste ou de dépôt, peut indiquer pour quel membre de l’équipe elle agit. Envoyez X-Acting-User avec l’e-mail de connexion de la personne ou son identifiant d’utilisateur. Cette personne doit être un membre actif du site de la clé au moment de la requête. La requête s’exécute alors en son nom : l’historique de l’objet et l’historique de la demande nomment cette personne au lieu du créateur de la clé, et la piste d’audit nomme cette personne, la clé et le responsable qui a créé la clé. Elle ne peut faire que ce que permettent à la fois les portées de la clé et son propre rôle sur le site : un lecteur ne peut que lire, le personnel peut aussi modifier les objets, les demandes, les déclarations de perte, les colis, les tickets de vestiaire, le matériel, les visites et les séjours d’hôtel, et les propriétaires et les responsables peuvent utiliser toutes les portées de la clé. Un nom qui n’est pas celui d’un membre actif du site est refusé avec 403 et acting_user_refused, avec le même message que l’adresse existe ou non ; une portée que le rôle de la personne n’autorise pas est refusée avec 403 et acting_user_role. Les nouvelles tentatives sans risque sont conservées par personne, si bien que la réponse enregistrée d’une personne n’est jamais rejouée pour une autre. L’en-tête fonctionne avec les clés de site uniquement, pas avec un assistant connecté par une connexion, qui agit déjà au nom de la personne qui l’a connecté. vFound vérifie que la personne nommée est un membre actif ; il ne lui demande pas de se connecter, donc ne nommez des personnes que depuis une application où votre équipe se connecte. Sans l’en-tête, une clé fonctionne exactement comme avant.
OpenAPI
L’API entière, chaque événement et chaque objet sont décrits dans un fichier OpenAPI 3.1 : vfound.io/openapi/v1.json. Importez-le dans Postman, Insomnia ou votre propre générateur de code. Un test le garde aligné sur l’API, si bien qu’il ne liste jamais un endpoint qui n’existe pas et n’en oublie jamais un qui existe.
Connexions préconfigurées aux systèmes opérationnels
Les propriétaires et les responsables configurent ces connexions de fournisseurs en lecture seule dans Réglages, Connexions, Systèmes opérationnels. Elles sont distinctes de l’API REST publique : le client crée et contrôle l’identifiant du fournisseur, la connexion doit réussir un test avant l’activation, des échecs répétés ne mettent en pause que cette connexion, et le travail manuel reste possible.
| Système | Ce que vFound lit | Domaines vFound |
|---|---|---|
| Cloudbeds | Le contexte minimal de réservation et de chambre, par une clé d’établissement contrôlée par le client et limitée à read:reservation. Fait partie de vFound Enterprise. | Séjours privés pour Lost & Found et Parcels |
| OfficeRnD Flex | Identifiant du membre, nom, e-mail et état actif, par flex.community.members.read, avec un filtre d’implantation facultatif. | La liste de personnes partagée pour Parcels, Equipment et Visitors |
| Microsoft Entra ID | Identifiant de l’utilisateur, nom d’affichage, e-mail et état actif, par les mises à jour delta de Microsoft Graph et User.Read.All avec consentement de l’administrateur. | La liste de personnes partagée pour Parcels, Equipment et Visitors |
Ce sont des connexions d’API configurées par le client, pas des déclarations de certification d’un fournisseur. Tester, activer et synchroniser une connexion font partie de vFound Enterprise. En particulier, la connexion Entra n’est pas une application de la Microsoft Marketplace.
Objets
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/items | Les objets, le changement le plus récent en premier. Filtres : status, search (mots du titre, de la description, de la marque, de la couleur ou des étiquettes), updated_since (ISO 8601), page, per_page (jusqu’à 100). | items:read |
| GET/items/{id} | Un objet par son identifiant. | items:read |
| GET/categories | Les noms de catégories qu’un objet peut utiliser. | items:read |
| POST/items | Ajoute un objet trouvé. Il est publié sur votre page des clients, déclenche les alertes et la mise en correspondance, et apparaît dans votre piste d’audit comme un objet ajouté à la main. | items:write |
| PATCH/items/{id} | Modifie les détails ou l’état. | items:write |
| GET/item-transfers | Les objets trouvés que ce site a envoyés à un autre site du même groupe de clients, ou qu’il en reçoit, ceux en cours d’acheminement d’abord. Liste aussi les sites vers lesquels vous pouvez envoyer (destinations) et les bacs de rangement de ce site (bins). Filtres : status (in_transit, received ou cancelled), direction (incoming ou outgoing). | items:read |
| POST/item-transfers | Envoie un objet qui attend son propriétaire vers un autre site du groupe : item_id, destination_business_id et un note facultatif. Uniquement pour les clés créées par un propriétaire ou un responsable. L’objet quitte la page des clients du site expéditeur (si ce site affiche ses objets trouvés) et ne peut plus changer avant son arrivée. Un objet qui a une demande reste où il est. | items:write |
| POST/item-transfers/{id}/cancel | Le site expéditeur reprend l’objet avant sa réception. | items:write |
| POST/item-transfers/{id}/receive | Le site destinataire confirme l’arrivée, avec bin_id (obligatoire quand le site a des bacs de rangement) ou location. L’objet appartient alors à ce site avec ses photos, son historique et ses dates, et il est comparé aux déclarations de perte de ce site comme un objet nouvellement enregistré. | items:write |
Outils d’accueil Lost & Found et Checkroom
Les nouveaux réglages d’e-mail sont désactivés par défaut. Les comptages de scans et les écarts de fermeture servent uniquement à la revue. P90 utilise le 90e centile au rang le plus proche des intervalles d’horodatages valides ; les échantillons absents renvoient null. La capacité en pièces physiques avertit mais ne bloque jamais l’enregistrement d’un dépôt. Voir la description OpenAPI pour les champs des requêtes. Les modèles de configuration et les réglages exigent un propriétaire ou un responsable.
| Méthode et chemin | Ce qu’elle fait | Portée |
|---|---|---|
| GET /lost-found/context-schema | Lire les définitions versionnées des champs de contexte privé, sans les valeurs des enregistrements. L’une ou l’autre des portées de lecture listées suffit. | items:read ou lost_reports:read |
| GET /lost-found/desk-settings | Lire les réglages facultatifs de l’accueil. | lost_reports:read |
| PUT /lost-found/desk-settings | Remplacer les réglages de l’accueil ; propriétaire ou responsable uniquement. Les nouveaux réglages d’e-mail sont désactivés par défaut. | lost_reports:write |
| GET /checkroom/desk-settings | Lire les réglages facultatifs de l’accueil. | checkroom:read |
| PUT /checkroom/desk-settings | Remplacer les réglages de l’accueil ; propriétaire ou responsable uniquement. Les nouveaux réglages d’e-mail sont désactivés par défaut. | checkroom:write |
| GET /lost-found/counts | Lister les 30 dernières sessions de comptage par scan. | items:read |
| POST /lost-found/counts | Prendre un instantané des identifiants des objets conservés pour un comptage de revue seule ; aucun changement de garde. | items:write |
| GET /lost-found/counts/{id} | Lire un comptage avec ses chiffres des objets manquants, inattendus et qui ne sont plus là. | items:read |
| POST /lost-found/counts/{id}/scan | Enregistrer le scan d’un QR code ou d’une courte étiquette d’objet ; les objets connus en double comptent une seule fois. | items:write |
| POST /lost-found/counts/{id}/finish | Terminer un comptage sans modifier les objets. | items:write |
| GET /lost-found/queues | Lister les files de travail enregistrées du créateur actuel de la clé dans ce site. | lost_reports:read |
| PUT /lost-found/queues/{id} | Remplacer votre propre file enregistrée ; les objets et les demandes sous-jacents ne changent pas. | lost_reports:write |
| DELETE /lost-found/queues/{id} | Supprimer votre propre file enregistrée ; les objets et les demandes sous-jacents ne changent pas. | lost_reports:write |
| POST /lost-found/queues | Enregistrer un préréglage de file de travail nommé pour le créateur actuel de la clé. | lost_reports:write |
| GET /lost-found/queues/{id} | Lire les enregistrements actuels derrière une file enregistrée. Les transferts entrants ouvrent la vue de transfert existante, soumise aux permissions. | lost_reports:read, items:read, claims:read |
| POST /lost-found/intake-review | Renvoyer des invites déterministes sur l’exhaustivité et la confidentialité ; aucune IA, aucune modification. | items:read |
| GET /checkroom/templates | Lister les modèles de configuration, uniquement de la configuration ; responsable uniquement. | checkroom:read |
| PUT /checkroom/templates/{id} | Remplacer un modèle de configuration en tant que responsable ; les événements, postes et tickets sous-jacents ne changent pas. | checkroom:write |
| DELETE /checkroom/templates/{id} | Supprimer un modèle de configuration en tant que responsable ; les événements, postes et tickets sous-jacents ne changent pas. | checkroom:write |
| POST /checkroom/templates | Enregistrer la configuration des postes d’un événement sans clients ni tickets ; responsable uniquement. | checkroom:write |
| POST /checkroom/templates/{id}/apply | Créer un nouvel événement et des postes ; si des plages de numéros actives se chevauchent, toute l’opération est rejetée. | checkroom:write |
Centre de contact et garde Lost & Found
Des intégrations pilotées par des personnes peuvent créer une déclaration de perte de client, enregistrer une vérification de propriété, décider d’une demande et enregistrer le retrait physique. Les nouvelles portées d’écriture doivent être choisies explicitement ; les clés existantes ne les acquièrent pas. Aucune de ces écritures sur les demandes ou les dispositions n’est proposée comme outil MCP ou Ask vFound. Votre intégration est responsable d’identifier et d’autoriser la personne qui l’utilise : l’audit nomme le responsable qui a créé la clé et, quand l’intégration envoie X-Acting-User, aussi le membre de l’équipe qu’elle a nommé, que vFound n’authentifie pas.
| Méthode et chemin | Ce qu’elle fait | Portée |
|---|---|---|
| POST /lost-reports | Saisie du centre de contact : first_name, last_name, email, title et description ; facultatifs : phone, category id, colour_brand, place_lost, date_lost et language. Envoie la confirmation habituelle au client et le lien privé, et lance la veille de 90 jours. Le consentement téléphonique n’est jamais déduit. Les limites de déclarations ouvertes existantes s’appliquent. | lost_reports:write |
| PUT /lost-reports/{id} | Modifier ce qui a été perdu avec l’empreinte renvoyée par GET /lost-reports. title et description sont obligatoires. Un parcours omis conserve les détails enregistrés ; si la collecte est désactivée, les changements de contexte sont refusés. Les changements de coordonnées exigent le flux distinct de coordonnées vérifiées. | lost_reports:write |
| GET /lost-reports/{id}/matches | Jusqu’à 24 candidats en direct par texte ou catégorie, chacun avec match.label, reason et source. Les verdicts d’IA récents enregistrés utilisent cached_ai ; sinon une suggestion par mots-clés est étiquetée possible. Aucun nouvel appel au modèle ni décision de propriété. | lost_reports:read et items:read |
| GET /items/{id}/matches | L’identifiant et le titre de la déclaration correspondante sans les coordonnées de la personne ; jusqu’à 24 correspondances parmi les 1,000 dernières déclarations ouvertes. Mêmes étiquettes de source et aucun nouvel appel au modèle. | items:read et lost_reports:read |
| POST /claims/{id}/verification | Enregistrer verified (booléen) et method (distinctive_details, purchase_proof ou staff_review). Attestation humaine, pas une authentification automatique de document ; aucune copie de document ni preuve en texte libre. La dernière vérification doit réussir avant l’acceptation par l’API. | claims:write |
| POST /claims/{id}/decision | status : open, accepted, rejected, expired, ready_for_pickup, ready_for_shipment, shipped ou handed_to_courier. La machine à états existante et la seconde approbation s’appliquent. Les champs d’expédition manuelle suivent les règles de l’espace de travail. Avec accepted, un return facultatif (pickup ou shipment) fait passer la demande à cette étape dans la même requête, avec un seul e-mail au demandeur ; quand la restitution d’un objet de grande valeur attend encore sa seconde approbation, la demande reste accepted et return_notice en donne la raison (la même requête une seconde fois ne change rien). Un arranged_by facultatif (site ou owner) indique qui réserve un retour par coursier ou par la poste, et chaque réponse sur une demande l’affiche. Sans arranged_by, une adresse de livraison envoyée dans shipment (ou une que la demande a déjà) signifie que votre équipe l’expédie, comme avant ; sinon le réglage Lost & Found du site décide. owner signifie que le propre coursier du demandeur vient chercher l’objet : aucune adresse n’est demandée, une adresse envoyée avec owner est refusée, et shipped est refusé. Quand son coursier vient chercher l’objet, envoyez handed_to_courier avec la société de coursier dans shipment.carrier et sa référence de réservation dans shipment.tracking_number ; la demande se clôt. Pour changer qui le réserve, remettez la demande à ready_for_pickup puis à ready_for_shipment avec arranged_by. | claims:write |
| POST /claims/{id}/release-approval | Un autre responsable approuve la restitution acceptée d’un objet de grande valeur, selon les mêmes contrôles que dans l’espace de travail. | claims:write |
| GET /claims/{id}/custody | L’historique des vérifications et des étapes, l’approbateur, et le nom et l’heure du retrait. signature_recorded est un booléen ; aucune image de signature ni adresse de fichier privé n’est exposée. | claims:read |
| POST /claims/{id}/handover | Enregistrer le retrait physique depuis ready_for_pickup, avec handover.name et une URL de données PNG dans handover.signature quand elle est exigée. Les appels répétés sur une demande déjà close conservent le premier reçu. | claims:write |
| POST /items/{id}/disposition | kind donated/disposed, recipient pour un don, notes facultatives. La date de conservation et les contrôles des demandes en attente ou acceptées s’appliquent. Renvoie le reçu du lot numéroté. | items:write |
Utilisez une Idempotency-Key pour les nouvelles tentatives d’écriture. Un enregistrement de vérification n’authentifie pas une pièce d’identité et n’approuve pas à lui seul la propriété. La création initiale d’une déclaration suit le parcours des clients, y compris l’IA activée pour le site ; les GET de listes de correspondances utilisent les verdicts enregistrés et la recherche de texte uniquement. Ce sont des opérations REST/OpenAPI génériques ; aucune installation WSO2 ni aucun connecteur natif n’a été certifié.
Ajouter un objet
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}'
Champs : title et category sont obligatoires. Facultatifs : found_date, found_time (HH:MM), keep_until, location, description, colour, brand, tags, value_band (unknown, low, medium, high), notes (personnel uniquement), photo (une URL de données base64 jusqu’à 8 MB) et photo_public. Les photos envoyées par l’API ne sont pas vérifiées par la protection de la vie privée de vFound AI : mettez donc photo_public à false pour toute photo qui montre des données personnelles.
L’objet item
{"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":"…"}
L’état est l’un de in_care, in_transit (en route vers un autre site ; transfer nomme alors les deux sites), claimed, expired, donated, disposed ou trash. Un PATCH peut définir in_care, expired, donated, disposed ou trash ; les restitutions à un client passent par les demandes.
Demandes
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/claims | Les demandes, le changement le plus récent en premier. Filtres : status, updated_since, page, per_page. | claims:read |
| GET/claims/{id} | Une demande par sa référence. | 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":"…"}
État de la demande : unread, open, accepted, awaiting_information, ready_for_pickup, ready_for_shipment, shipped, closed, rejected ou expired (acceptée mais jamais retirée). arranged_by indique qui réserve un retour par coursier ou par la poste : venue (votre équipe l’expédie) ou owner (le propre coursier du demandeur vient le chercher) ; null quand la demande n’a pas un tel retour. Les coordonnées des demandeurs sont des données personnelles : ne les gardez que le temps dont vous avez besoin.
Déclarations de perte
GET/lost-reports liste ce que les clients ont déclaré avoir perdu, avec status (open ou closed), les coordonnées de la personne qui a déclaré, la langue qu’elle a utilisée et tout lien Find My qu’elle a partagé. Portée : lost_reports:read.
Analyses
GET/analytics?days=30 renvoie le même résumé que Rapports : objets enregistrés et restitués, taux de restitution, nombre médian de jours avant la restitution, où les objets ont fini, catégories, points chauds, jours les plus chargés, travail de l’équipe, tendance et retours des clients. days vaut 7, 30, 90 ou 365. Portée : analytics:read.
Séjours à l’hôtel
Le contexte d’un séjour est privé au site et volontairement minimal. Il contient une référence de séjour stable, une référence de client facultative, le nom du client, l’arrivée et le départ, le fuseau horaire de la source, la chambre actuelle, l’état et les horodatages de la source. Il ne contient jamais de tarifs, de données de paiement, de données de fidélité, de pièces d’identité, de préférences ni de notes de réservation sans rapport.
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/stays | Liste les séjours. Filtres : search (client, référence stable ou chambre actuelle), state, source, page et per_page. Une correspondance de chambre aide seulement à naviguer ; elle ne suggère jamais une propriété. | stays:read |
| GET/stays/{stay} | Un séjour et son historique vérifiable de source et de corrections. | stays:read |
| POST/stays | Crée ou met à jour l’enregistrement de source API identifié par external_stay_ref. Envoyez source_updated_at ; les événements retardés ou rejoués qui ne sont pas plus récents que l’événement enregistré sont acquittés sans remplacer des données plus récentes. | 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"}'
Les objets et les colis acceptent stay_id et room_at_event facultatifs. Si la chambre au moment de l’événement est omise, vFound prend un instantané de la chambre actuelle du séjour. Cet instantané ne change pas après un changement de chambre ; l’enregistrement montre aussi la chambre actuelle, si bien que l’accueil voit les deux.
Parcels
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/parcels | Les colis, le changement le plus récent en premier. Filtres : status (waiting, collected ou returned), search (destinataire, logement, numéro de suivi, expéditeur ou code de retrait), updated_since. | parcels:read |
| GET/parcels/{id} | Un colis. | parcels:read |
| POST/parcels | Enregistre un colis pour recipient_email (mis en correspondance avec votre liste de personnes) ou recipient_name, avec unit, carrier, tracking, sender et shelf facultatifs. La personne reçoit par e-mail son code de retrait sauf si notify vaut false. | parcels:write |
| POST/parcels/{id}/collect | Le remettre : collected_by (obligatoire) et un signature facultatif (une URL de données PNG). | parcels:write |
| POST/parcels/{id}/return | Le renvoyer à l’expéditeur, avec un note facultatif. | parcels:write |
| POST/parcels/{id}/remind | Envoie par e-mail au destinataire un rappel pour venir le retirer. | parcels:write |
| POST/parcels/tracking | Normalise un numéro de suivi et détecte UPS, FedEx, USPS, DHL, Amazon ou un transporteur international S10. Un SSCC GS1 valide est accepté comme suivi d’expédition ; un identifiant de produit GS1 est reconnu mais jamais traité comme un numéro de colis. | parcels:read |
| GET/parcels/pickup-queue | Les personnes qui ont dit être à l’accueil, avec leur nombre de colis et leurs étagères. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | Marquer une arrivée à l’accueil comme servie. | parcels:write |
| POST/parcels/bulk-remind | Envoie par e-mail des rappels pour jusqu’à 200 colis en attente sélectionnés. | parcels:write |
| POST/parcels/bulk-return | Renvoie à l’expéditeur jusqu’à 200 colis en attente sélectionnés. | parcels:write |
| GET/parcels/shelves | Les capacités des étagères à colis et leur occupation actuelle. | parcels:read |
| POST/parcels/shelves | Crée une étagère ou change sa capacité. | parcels:write |
| GET/parcels/analytics | Volume, répartition des transporteurs, délai de retrait, taux de colis non retirés et étagères les plus chargées. | parcels:read |
| GET/parcels/outgoing | Les colis sortants prêts pour un coursier ou déjà remis. | parcels:read |
| POST/parcels/outgoing | Enregistre un colis sortant. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | Enregistre le coursier et la signature à la remise. | parcels:write |
| GET/parcels/rounds | Les tournées de livraison et leurs arrêts. | parcels:read |
| POST/parcels/rounds | Crée une tournée de campus ou de bureaux à partir des colis en attente. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | Termine un arrêt avec le nom du destinataire et la signature. | parcels:write |
| GET/parcels/couriers | Les coursiers enregistrés par Visitors, avec status in ou 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":"…"}
Le code de retrait n’est affiché que tant que le colis attend. Les coordonnées des destinataires sont des données personnelles : ne les gardez que le temps dont vous avez besoin.
Checkroom
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/checkroom/tickets | Les tickets, le changement le plus récent en premier, avec status (pending, in, returned, left ou moved), le numéro, ce qui a été déposé, les piece_records étiquetés individuellement, les coordonnées du client si elles sont données, les frais enregistrés à l’accueil et les heures. Filtres : status, search (client, chambre, numéro de ticket, étiquette de pièce ou code de ticket), updated_since. | checkroom:read |
| GET/checkroom/tickets/{id} | Un ticket. | checkroom:read |
| POST/checkroom/tickets | Enregistre un dépôt et donne le prochain numéro libre : kind (coat, bag, luggage ou other, obligatoire), pieces, piece_details facultatif avec un type et un emplacement de rangement pour chaque pièce, guest_name, guest_email, guest_room, collect_by pour les bagages, notes, fee_method (cash ou card), station_id, event_id, storage_location, language et photo. La réponse contient aussi guest_ticket (le code et l’adresse privée du ticket) une seule fois, à afficher en code QR ou à imprimer pour le client ; les lectures, les listes et les webhooks ne l’incluent jamais. | checkroom:write |
| POST/checkroom/tickets/{id}/hand-back | Le remet une fois que votre système a lu le ticket du client, avec collected_by et signature facultatifs. Envoyez piece_ids pour rendre des pièces choisies et laisser les autres ouvertes ; omettez-le pour rendre toutes les pièces ouvertes. without_ticket enregistre que le client a perdu son ticket et exige alors collected_by et signature. | checkroom:write |
| GET/checkroom/stations | Liste les postes de vestiaire du site, leurs plages de numéros et leurs emplacements de rangement. | checkroom:read |
| POST/checkroom/stations | Crée un poste avec une plage de numéros qui n’en chevauche aucune autre. | checkroom:write |
| PUT/checkroom/stations/{id} | Modifie un poste, sa plage de numéros, ses emplacements de rangement ou son état actif. | checkroom:write |
| GET/checkroom/events | Liste les événements de vestiaire récents et à venir. | checkroom:read |
| POST/checkroom/events | Crée un événement avec son volume attendu et ses postes. | checkroom:write |
| PUT/checkroom/events/{id} | Modifie les horaires, la prévision ou les postes d’un événement. | checkroom:write |
| GET/checkroom/exit-queue | Les tickets dont les clients ont demandé à l’accueil de préparer leurs affaires. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | Marque un ticket en attente comme prêt et prévient le client. | checkroom:write |
| GET/checkroom/report | Volume de tickets, heures de pointe, délai de remise et frais par méthode et par membre du personnel. | checkroom:read |
| GET/checkroom/export | Télécharge les lignes du rapport de vestiaire en CSV protégé contre les formules. | checkroom:read |
Queue
Files, personnes qui y attendent et guichets où elles sont appelées. Chaque modification suit les mêmes étapes qu’à l’accueil, avec le même historique, au nom du créateur de la clé ou du membre de l’équipe nommé dans X-Acting-User. Un ticket ne contient jamais l’e-mail du client ni ses réponses aux questions de la file.
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/queue/lines | Les files avec leur état actuel, les personnes en attente et une attente estimée pour quelqu’un qui les rejoint maintenant. | queue:read |
| GET/queue/lines/{id} | Une file. | queue:read |
| GET/queue/tickets | Les tickets d’un jour du site (day, aujourd’hui par défaut), dans l’ordre d’appel ; filtre par line et status. | queue:read |
| GET/queue/tickets/{id} | Un ticket. | queue:read |
| GET/queue/report | Tickets, personnes servies, absences, personnes parties, et minutes médianes d’attente et de service pour les derniers days. | queue:read |
| POST/queue/tickets | Ajoute une personne à une file, comme le fait l’accueil. | queue:write |
| POST/queue/call-next | Appelle la personne suivante à un guichet (counter_id). Deux appelants n’obtiennent jamais la même personne ; data vaut null quand personne n’attend. | queue:write |
| POST/queue/tickets/{id}/call | Appelle une personne choisie à un guichet. | queue:write |
| POST/queue/tickets/{id}/served | Marque la personne au guichet comme servie. | queue:write |
| POST/queue/tickets/{id}/no-show | Marque comme absence une personne appelée qui n’est pas venue. | queue:write |
| POST/queue/tickets/{id}/remove | Retire une personne de la file. | queue:write |
| GET/queue/bookings | Les créneaux réservés, le plus proche en premier, avec from, to, line, status et la pagination. Jamais l’e-mail de la personne. | queue:read |
| POST/queue/bookings | Réserve pour une personne l’un des créneaux libres de la page de créneaux réservés d’une file (line_id, starts_at, email). | queue:write |
| POST/queue/bookings/{id}/cancel | Annule un créneau réservé ; la personne reçoit un e-mail l’informant que l’équipe l’a annulé. | queue:write |
| POST/queue/bookings/{id}/arrived | Enregistre l’arrivée d’une personne qui a réservé ; son ticket est placé selon le créneau réservé. | queue:write |
| POST/queue/tickets/{id}/arrived | Marque comme présente une personne qui a rejoint la file avant d’arriver. | queue:write |
| GET/queue/tickets/{id}/messages | Les messages entre une personne dans la file et l’équipe, les plus anciens d’abord. La lecture marque les messages de la personne comme lus. | queue:read |
| POST/queue/tickets/{id}/messages | Écrit à une personne dans la file (body, de 1 à 500 caractères), au nom du membre de l’équipe de la clé. | queue:write |
| GET/queue/survey | Les chiffres de l’enquête après le service : réponses, moyenne, chaque note, par file, service, guichet et membre de l’équipe (la moyenne d’un membre de l’équipe apparaît à partir de 5 réponses). Jamais les commentaires. | queue:read |
| GET/queue/performance | Des chiffres simples pour chaque membre de l’équipe sur les mêmes jours que le rapport. Ni note ni classement. | queue:read |
| GET/queue/lines/{id}/slots | Les créneaux réservés ouverts d’une file, tels que sa page de réservation les propose. | queue:read |
| POST/queue/join | Prend un numéro pour un client de votre propre site web, selon les règles des clients (file ouverte, limites, réponses obligatoires et cases de consentement). Envoyez-le depuis votre serveur : la clé remplace le captcha. | queue:write |
| GET/queue/tickets/lookup | Trouve des tickets par le numéro que le client détient. | queue:read |
| GET/queue/tickets/{id}/status | Ce que montre la page du ticket du client : place, estimation et phrase. | queue:read |
| GET/queue/tickets/{id}/history | Les étapes d’un ticket. Qui a fait chacune est team, guest, api (une arrivée dans la file par une clé) ou system (fait automatiquement, comme l’absence automatique), jamais un nom. | queue:read |
| GET/queue/customers/history | Les visites d’une personne qui a demandé à être reconnue, trouvées par e-mail, tant que le site a la reconnaissance activée. Indique à la personne qui détient la clé si une adresse e-mail appartient à un visiteur reconnu. | queue:read |
| GET/queue/insights | Des chiffres pour les mêmes jours que le rapport : personnes parties avant d’être appelées, personnes avec rendez-vous et sans rendez-vous, part des personnes appelées dans l’objectif d’attente par file et par semaine, et heures de pointe des semaines passées. Des chiffres seulement ; jamais un nom ni une réponse. | queue:read |
| GET/queue/report-data | Les tickets Queue tels que les lit le générateur de rapports (fields[], limit jusqu’à 1000, offset), pour les outils de BI. Le nom du client n’est jamais inclus. | queue:read |
Equipment
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/loans | Le matériel remis, le changement le plus récent en premier, avec status (out, returned ou lost), s’il est overdue, l’objet, l’utilisateur et les heures. Filtres : status (out, returned, lost ou overdue), search (nom, e-mail ou référence de l’utilisateur), updated_since. | loans:read |
| GET/loans/{id} | Une sortie. | loans:read |
| POST/loans | Remet quelque chose : item_id ou item_code (le code de son étiquette, ou le lien que contient son QR code), borrower_name (obligatoire), person_id facultatif pour lier la liste de personnes, borrower_email pour un reçu, borrower_reference, due_at, note, language et signature. | loans:write |
| POST/loans/{id}/extend | Donne plus de temps : un nouveau due_at. L’utilisateur reçoit par e-mail la nouvelle heure. | loans:write |
| POST/loans/{id}/return | Le reprend, avec condition facultatif (good, damaged ou incomplete), note, et set_aside pour mettre l’objet de côté en vue d’une réparation. | loans:write |
| POST/loans/returns | Reprend plusieurs choses ensemble : loan_ids (1 à 50), avec les mêmes condition, note et set_aside facultatifs pour toutes. Tout ou rien : si l’une est déjà rendue ou introuvable, rien ne change. Un utilisateur qui a une adresse e-mail reçoit un seul reçu pour chaque sortie, qui liste tout ce qui est revenu, et chaque sortie envoie son propre événement loan.returned. | loans:write |
| GET/loans/items | Tout ce que l’accueil remet, par nom. Filtres : status (available, out, repair ou retired), search (nom, étiquette de bien ou code d’étiquette), updated_since. | loans:read |
| GET/loans/items/{id} | Un objet, avec le lien que contient le QR code de son étiquette. | loans:read |
| GET/loans/items/{id}/tickets | Les tickets envoyés au Jira, au Zendesk ou au ServiceNow propre au site pour cet objet (bêta), avec le dernier état relu. | loans:read |
| POST/loans/items | Ajoute du matériel : name (obligatoire), category, tag, location, notes, loan_hours (pour combien d’heures il sort habituellement), photo, product et variant (les unités d’un même produit et d’une même variante peuvent être réservées comme une seule), et copies pour ajouter jusqu’à 50 objets identiques, numérotés. | loans:write |
| PATCH/loans/items/{id} | Modifie ses détails, ou définit status sur available, repair ou retired. product et variant changent sa famille de produits ; cleaning_status needs_cleaning le marque comme en attente de nettoyage et null le marque comme nettoyé. Les objets montrent product, variant, cleaning_status et cleaning_since. | loans:write |
| GET/loans/items/{id}/tag | Indique si une étiquette NFC ou RFID est liée, et les quatre derniers chiffres hexadécimaux de son numéro de série. | loans:read |
| PUT/loans/items/{id}/tag | Lie une étiquette par son numéro de série, tel qu’un téléphone le lit ou qu’un lecteur de type clavier le saisit (hexadécimal, hexadécimal inversé ou décimal) ; elle remplace toute étiquette que l’objet avait. | loans:write |
| DELETE/loans/items/{id}/tag | Retire l’étiquette de l’objet. | loans:write |
| POST/loans/checkouts | Remet de un à 50 objets en une seule sortie atomique, ou remet un kit enregistré. Accepte une personne, une échéance, une note et une signature facultative, ainsi que des lignes de stock (stock) remises sur le même reçu, listées en retour dans stock. custom_values définit les attributs personnalisés du site pour la sortie. | loans:write |
| GET/loans/kits | Les groupes de matériel enregistrés qui sont habituellement remis ensemble. | loans:read |
| POST/loans/kits | Enregistre un kit d’au moins deux éléments au total : item_ids nommés, lines (un nombre d’une catégorie) et child_kit_ids (kits qu’il contient, jusqu’à trois niveaux), stock_lines (stock compté remis avec lui, jamais retenu pour une réservation), avec en option locked pour que ses objets nommés ne sortent qu’ensemble. | loans:write |
| PUT/loans/kits/{id} | Modifie un kit enregistré et ses objets. | loans:write |
| GET/loans/trainings | Les formations qu’une catégorie ou un objet peut exiger avant qu’une personne le sorte (configurées dans Equipment, Politiques, Formation). | loans:read |
| GET/loans/trainings/{id}/holders | Qui détient une formation, depuis quand et jusqu’à quand, et si elle a expiré. | loans:read |
| POST/loans/trainings/{id}/holders | Donne une formation à une personne de la liste de personnes, ou la renouvelle, avec un justificatif facultatif. | loans:write |
| DELETE/loans/trainings/{id}/holders/{person} | Retire une formation à une personne, avec son justificatif. | loans:write |
| GET/loans/borrower-types | Les types d’utilisateurs : pour chacun, sa limite d’objets, sa durée habituelle et les catégories que ses personnes voient et sortent (configurés dans Equipment, Politiques). Une limite ou une durée vide signifie que celle du site s’applique. | loans:read |
| GET/loans/borrower-types/{id}/members | Qui a un type d’utilisateur. | loans:read |
| POST/loans/borrower-types/{id}/members | Donne un type d’utilisateur à des personnes de la liste de personnes (jusqu’à 500 à la fois). | loans:write |
| PUT/loans/borrower-types/{id}/members/{person} | Modifie l’appartenance d’une personne à un type d’utilisateur : son jour de début, son jour de fin (après lequel elle voit encore ce que montre le type, mais ne peut plus le réserver ni le sortir) et une note sur l’endroit où des frais ont été perçus. vFound ne prend aucun paiement. | loans:write |
| DELETE/loans/borrower-types/{id}/members/{person} | Retire un type d’utilisateur à une personne. | loans:write |
| GET/loans/credits | Les crédits de réservation donnés récemment, et le solde d’une personne. Les crédits sont un nombre que les réservations dépensent, jamais de l’argent. | loans:read |
| POST/loans/credits | Donne des crédits de réservation à une personne, ou en reprend avec un nombre négatif (propriétaires et responsables). | loans:write |
| GET/loans/holds | Les blocages actifs sur les sorties : tant que l’un dure, rien ne sort pour la personne et elle ne peut pas réserver. | loans:read |
| POST/loans/holds | Met un blocage sur les sorties d’une personne, avec un motif facultatif (gardé pour l’équipe, jamais dans l’e-mail), une heure de fin et un e-mail à la personne. | loans:write |
| POST/loans/holds/{id}/lift | Lève un blocage. | loans:write |
| GET/loans/spaces | Les salles, bureaux, places de stationnement et autres endroits que le site réserve pour une durée, filtrés en option par type. Chacun est un objet de type space, jamais remis. | loans:read |
| POST/loans/spaces | Ajoute une salle ou un espace avec son type, le nombre de personnes qu’il peut accueillir et son emplacement. | loans:write |
| PUT/loans/spaces/{id} | Modifie une salle ou un espace. | loans:write |
| GET/loans/spaces/availability | Chaque salle ou espace avec ses réservations ouvertes entre from et to (jusqu’à 31 jours), avec le nom de l’utilisateur, le nombre de personnes qui viennent et les consignes d’installation éventuelles. | loans:read |
| POST/loans/spaces/{id}/book | Réserve une salle ou un espace pour une personne et une durée, seul ou avec du matériel (tout ou rien), avec des consignes d’installation pour l’équipe. | loans:write |
| POST/loans/reservation-groups/{id}/parts | Ajoute un objet, ou un objet d’une catégorie, à une réservation de kit ou de panier, vérifié comme une nouvelle réservation. Refusé pour un kit verrouillé. Un élément d’une catégorie que le formulaire de risque du site couvre exige risk_answers, et l’évaluation de la réservation attend un nouvel examen. | loans:write |
| POST/loans/reservations/{id}/remove-part | Retire un élément d’une réservation de kit ou de panier ; le dernier élément est annulé avec la réservation. | loans:write |
| GET/loans/places | Les emplacements imbriqués propres au site : bâtiments, salles, étagères, chantiers et camions. Le place_id d’un objet définit où il se trouve et remplit son location et son sub_location. | loans:read |
| GET/loans/category-tree | Les catégories de matériel regroupées en arbre, les parents d’abord. Les règles et les réservations s’appliquent toujours à la catégorie propre de l’objet. | loans:read |
| GET/loans/asset-models | Les modèles à partir desquels les nouveaux objets sont créés. Envoyez asset_model_id sur POST /loans/items pour remplir chaque détail laissé vide. | loans:read |
| GET/loans/items/{id}/links | Les liens d’un objet avec d’autres objets du même site : fonctionne avec, une alternative, remplace. | loans:read |
| POST/loans/items/{id}/links | Lie un objet à un autre du même site, avec une note. | loans:write |
| DELETE/loans/items/{id}/links/{link} | Retire un lien des deux objets. | loans:write |
| POST/loans/kits/{id}/move | Déplace un kit vers un emplacement du site : chaque objet nommé qu’il contient, et ceux des kits qu’il contient, y va d’un seul coup (propriétaires et responsables). | loans:write |
| GET/loans/items/{id}/meter-readings | Les relevés de compteur saisis pour un objet, les plus récents d’abord. | loans:read |
| POST/loans/items/{id}/meter-readings | Enregistre un relevé de compteur. Un plan d’entretien avec every_meter est dû une fois que le compteur a atteint cette valeur ; les relevés ne font qu’augmenter. | loans:write |
| GET/loans/contracts | Les contrats de fournisseurs liés aux objets qu’ils couvrent (propriétaires et responsables). | loans:read |
| GET/loans/resale | Les objets mis en vente avec leur prix demandé et leur valeur comptable (propriétaires et responsables). Une liste seulement : rien n’est annoncé ni vendu. | loans:read |
| GET/loans/points | Les points de retrait et de dépôt qu’une réservation peut nommer. | loans:read |
| POST/loans/points | Ajoute un point (propriétaires et responsables). Une réservation en nomme un où récupérer et un où rendre avec pickup_point_id et dropoff_point_id. | loans:write |
| PUT/loans/points/{id} | Modifie un point ou le désactive. | loans:write |
| GET/loans/projects | Les projets auxquels une réservation peut appartenir. Rien n’est retiré pour un projet tant qu’il n’est pas approuvé. | loans:read |
| POST/loans/projects | Ajoute un projet (en attente d’approbation). | loans:write |
| POST/loans/projects/{id}/decision | Approuve ou rejette un projet (propriétaires et responsables). | loans:write |
| GET/loans/risk-assessments | Les évaluations de risque en attente d’examen (ou par status), avec les réponses de l’utilisateur. | loans:read |
| POST/loans/risk-assessments/{id}/review | Approuve ou rejette une évaluation de risque (propriétaires et responsables). Un rejet annule la réservation. | loans:write |
| POST/loans/reservation-series | Réserve un objet, une catégorie ou une salle ou un espace chaque jour ou chaque semaine (repeat : frequency, every, weekdays, count ou until, skip_conflicts). Chaque date suit les règles de réservation et compte les dates qui la précèdent ; rien n’est réservé si l’une est prise, sauf si skip_conflicts est activé. Au plus 52 dates, sur un an. | loans:write |
| POST/loans/reservations/{id}/move | Déplace une réservation, avec chaque élément d’un kit ou d’un panier réservés ensemble, vers de nouvelles heures ou vers un autre objet de la même catégorie. Vérifiée à nouveau comme une nouvelle réservation ; tout ou rien. | loans:write |
| GET/loans/waitlist | Les personnes qui attendent un créneau qui a été pris, par status (waiting par défaut). | loans:read |
| POST/loans/waitlist | Ajoute quelqu’un à la liste d’attente d’un objet, d’une catégorie ou d’un espace et d’un créneau. Quand il se libère, la première personne dont le créneau convient désormais est réservée et reçoit un e-mail. | loans:write |
| POST/loans/waitlist/{id}/cancel | Retire quelqu’un de la liste d’attente. | loans:write |
| GET/loans/fees | Le registre des frais, le plus récent d’abord (filtrez par party_key, kind, status, billing_code, from, to), avec les réglages de frais du site et toutes les personnes qui doivent quelque chose ou dont une caution est retenue. Les montants sont des entiers dans la plus petite unité de la devise. vFound enregistre les frais ; il ne traite jamais un paiement. | loans:read |
| GET/loans/fees/party | Un utilisateur (person_id ou party_key) : ce qu’il doit par devise, les cautions retenues, les écritures et les factures. | loans:read |
| GET/loans/fees/billing-codes | Facturé, dispensé, réglé et encore dû par code de facturation et par devise pour une période ; format=csv pour un CSV. | loans:read |
| POST/loans/fees/charges | Enregistre des frais de dommage, de remplacement ou autres, ou des frais tarifés par fee_template_id. La taxe du site s’applique sauf si taxable vaut false. | loans:write |
| POST/loans/fees/payments | Enregistre de l’argent que le site a perçu lui-même (espèces, son propre terminal de carte, un virement). Il règle d’abord les frais ouverts les plus anciens. | loans:write |
| POST/loans/fees/deposits | Enregistre une caution que le site a perçue ; retenue jusqu’à sa restitution ou jusqu’à ce qu’elle soit conservée. | loans:write |
| POST/loans/fees/deposits/{id}/return | Rend une caution retenue. | loans:write |
| POST/loans/fees/deposits/{id}/keep | Conserve une caution retenue ou une partie de celle-ci (propriétaires et responsables, avec un motif) ; la partie conservée compte comme un paiement. | loans:write |
| POST/loans/fees/{id}/waive | Dispense de ce qu’il reste à régler sur des frais (propriétaires et responsables, avec un motif). | loans:write |
| POST/loans/fees/{id}/void | Annule un paiement enregistré par erreur (propriétaires et responsables, avec un motif). Annuler le paiement qu’une caution conservée a généré retient à nouveau ce montant comme caution. | loans:write |
| GET/loans/{id}/fees | Ce qui est proposé à l’accueil pour une sortie rendue : la pénalité de retard pas encore enregistrée, la valeur de remplacement en cas de perte ou de dommage, les cautions retenues. | loans:read |
| POST/loans/{id}/late-fine | Ajoute la pénalité de retard pour une sortie rendue en retard, comptée à partir du moment où elle est revenue. Une fois par sortie. | loans:write |
| GET/loans/invoices | Les factures, le numéro le plus récent d’abord. | loans:read |
| POST/loans/invoices | Émet une facture numérotée pour les frais ouverts d’un utilisateur dans une devise. | loans:write |
| POST/loans/invoices/{id}/void | Annule une facture (propriétaires et responsables, avec un motif) ; reissue met ses frais ouverts sur une nouvelle facture qui la remplace. | loans:write |
| GET/loans/reservations | Les réservations par heure de début, filtrées en option par status ou from. | loans:read |
| POST/loans/reservations | Réserve un objet précis ou un objet d’une catégorie pour une personne et une plage horaire. custom_values définit les attributs personnalisés du site pour la réservation. | loans:write |
| POST/loans/reservations/{id}/approve | Approuve une réservation en attente d’examen. Quand le site a des étapes d’approbation, une clé ne signe une étape que pour le membre de l’équipe qu’elle nomme dans X-Acting-User, une connexion d’assistant n’en signe jamais, et personne ne signe une étape d’une réservation qu’il a faite lui-même (approval_not_yours). Réserver malgré un conflit suit la même règle. | loans:write |
| POST/loans/reservations/{id}/cancel | Annule une réservation en attente, approuvée ou à retirer. | loans:write |
| POST/loans/reservations/{id}/pickup | Remet de façon atomique l’objet réservé et clôt la réservation comme retirée. | loans:write |
| POST/loans/reservation-groups | Réserve un kit (kit_id) ou un panier (items : un objet, ou une catégorie et une quantité, par ligne) pour une personne et une plage horaire : tous les éléments ou aucun. Approuver, annuler ou retirer un élément agit sur chaque élément ouvert. | loans:write |
| GET/loans/downtimes | Les périodes datées pendant lesquelles un objet ne peut pas être réservé ni remis et qui ne sont pas encore terminées (item_id restreint à un objet). | loans:read |
| POST/loans/downtimes | Ajoute une période à un objet : loan_item_id, starts_at, ends_at et reason facultatif. Refusé tant qu’une réservation ou une sortie retient l’objet pendant une partie de ce temps. | loans:write |
| DELETE/loans/downtimes/{id} | Retire une période. | loans:write |
| GET/loans/extra-values/{type}/{id} | Les attributs personnalisés du site pour un utilisateur (person), une reservation ou un checkout, avec les champs définis pour ce type d’enregistrement. | loans:read |
| PUT/loans/extra-values/{type}/{id} | Définit ces attributs, vérifiés selon les champs du site et leurs conditions d’affichage. | loans:write |
| GET/loans/closures | Les jours où l’accueil du matériel est fermé et qui ne sont pas encore terminés. | loans:read |
| POST/loans/closures | Ajoute une fermeture : dates starts_on et ends_on dans le fuseau horaire du site, jusqu’à 366 jours. note facultatif reste interne ; public_message (jusqu’à 300 caractères) est affiché aux utilisateurs. Les notes existantes ne sont jamais copiées dans le message destiné aux utilisateurs. | loans:write |
| DELETE/loans/closures/{id} | Retire une fermeture. | loans:write |
| GET/loans/rules | Les valeurs par défaut du site, les règles par catégorie pour la durée, les limites, les blocages en cas de retard, l’approbation et la réservation (délais entre deux sorties, préavis minimum, combien de temps à l’avance), et les fermetures. | loans:read |
| POST/loans/rules | Crée ou remplace une règle de catégorie. Les champs de règle de réservation omis gardent leurs valeurs enregistrées. | loans:write |
| GET/loans/timeline | Vérifications de capacité par objet ou par catégorie, sur des journées entières. Dates from et until obligatoires, incluses, à l’heure locale du site, au plus 31 jours entre aujourd’hui et l’an prochain ; facultatifs : group=item|category, item_id, category exacte, page (50 lignes). Les cellules valent true, false ou null (incertain). Des jours adjacents ne garantissent pas une réservation continue. | loans:read |
| GET/loans/warranties | Les dates de garantie enregistrées ; filter=soon|expired|all, category exacte, page (50 lignes). Soon inclut d’aujourd’hui jusqu’à 30 jours plus tard. L’inscription personnelle aux rappels se fait dans l’espace de travail. | loans:read |
| GET/loans/utilization | Heures écoulées par bien d’après l’historique d’état enregistré. Dates from et until obligatoires, incluses, à l’heure locale du site, dans les 365 derniers jours, plafonnées à maintenant ; facultatifs : item_id, category exacte, format=csv. Le JSON donne les secondes exactes ; les heures du CSV utilisent six décimales. Disponible inclut ce qui est sorti ; le temps de réparation ou d’entretien et les autres temps d’indisponibilité sont exclus. Les indisponibilités antérieures sont inconnues. Les totaux concordent avec les lignes par bien. | loans:read |
| GET/loans/maintenance | L’historique des entretiens, étalonnages, tests de sécurité, inspections, nettoyages, réparations et notes ; filtrez par objet, par travaux à venir, ou par ordres de travail (ouverts ou tous) et leur technicien. | loans:read |
| POST/loans/maintenance | Enregistre un entretien et la prochaine échéance pour un objet. Avec plan_id, le travail effectué pour un plan récurrent, ce qui démarre son prochain cycle. | loans:write |
| GET/loans/service-plans | Les plans récurrents d’entretien, d’étalonnage, de test de sécurité, d’inspection et de nettoyage, avec pour chacun s’il est dû à une date, après un nombre d’heures de sortie ou un nombre de sorties. | loans:read |
| POST/loans/service-plans | Ajoute un plan récurrent à un objet (propriétaires et responsables). | loans:write |
| PUT/loans/maintenance/{id} | Modifie ou clôt un ordre de travail : état, technicien, fournisseur, coût, et pour done son résultat et si l’objet est remis en service. | loans:write |
| GET/loans/maintenance/costs | Le coût d’entretien, de réparation et de nettoyage par objet, d’après les entrées terminées et les ordres de travail done. | loans:read |
| GET/loans/items/{id}/lifecycle | Le dossier d’achat, d’amortissement, d’assurance et de sortie définitive d’un objet, avec sa valeur d’aujourd’hui (propriétaires et responsables). | loans:read |
| PUT/loans/items/{id}/lifecycle | Enregistre le prix d’achat, la date, le fournisseur et la commande, la méthode d’amortissement (linéaire ou dégressif), la durée d’utilité et la valeur résiduelle, ainsi que l’assurance (propriétaires et responsables). | loans:write |
| POST/loans/items/{id}/dispose | Enregistre comment un objet est parti (vendu, mis au rebut, donné, recyclé, perdu ou volé) ; il est retiré du service et ses réservations et ordres de travail ouverts sont annulés. | loans:write |
| DELETE/loans/items/{id}/dispose | Annule une sortie définitive faite par erreur ; l’objet est à nouveau disponible. | loans:write |
| GET/loans/valuation | La valeur du matériel à une date, au centime près, avec les totaux de ce qui est encore détenu (propriétaires et responsables). | loans:read |
| POST/loans/service-plans/import | Vérifie ou ajoute des plans à partir d’un CSV dans les colonnes documentées, en nommant le matériel par étiquette de bien (propriétaires et responsables). | loans:write |
| POST/loans/maintenance/work-orders/import | Vérifie ou ajoute des ordres de travail ouverts à partir d’un CSV dans les colonnes documentées (propriétaires et responsables). | loans:write |
| GET/loans/maintenance/planner | Les travaux planifiés et les ordres de travail ouverts par jour propre au site, sur jusqu’à 62 jours, en option pour un seul technicien. | loans:read |
| GET/loans/funding | Ce que chaque fonds, subvention ou centre de coûts a acheté et quel travail lui a été imputé, filtrable par fonds et par dates (propriétaires et responsables). Un enregistrement seulement : vFound ne prend aucun paiement. | loans:read |
| GET/loans/substances | Le registre des substances dangereuses : substance, emplacement, classes de danger et dates de revue. Un enregistrement de ce que dit le site ; vFound ne donne aucun conseil de sécurité. | loans:read |
| POST/loans/substances | Ajoute une substance, avec sa fiche de données de sécurité en PDF ou en photo (propriétaires et responsables). | loans:write |
| PUT/loans/substances/{id} | Modifie une substance ou remplace sa fiche de données (propriétaires et responsables). | loans:write |
| DELETE/loans/substances/{id} | Retire une substance et sa fiche de données conservée (propriétaires et responsables). | loans:write |
| GET/loans/licences | Les licences du matériel du site, avec les postes, la date de fin et les objets sur lesquels elles sont installées (propriétaires et responsables). Aucune clé de licence n’est conservée. | loans:read |
| POST/loans/licences | Ajoute une licence (propriétaires et responsables). | loans:write |
| PUT/loans/licences/{id} | Modifie une licence et l’endroit où elle est installée. | loans:write |
| DELETE/loans/licences/{id} | Retire une licence. | loans:write |
| GET/loans/expiries | Les assurances et licences qui se terminent bientôt ou sont déjà terminées (propriétaires et responsables). | loans:read |
| GET/loans/stocktakes | Les inventaires de matériel récents, avec les nombres scannés et manquants. | loans:read |
| POST/loans/stocktakes | Démarre un inventaire ouvert pour le site, pour tout, pour un emplacement, une catégorie ou un kit, ou pour ce qu’une personne détient (custodian_id), en option attribué à un membre de l’équipe (assigned_to). | loans:write |
| POST/loans/stocktakes/{id}/scan | Scanne une étiquette de matériel, une étiquette de bien ou un numéro de série dans l’inventaire ouvert. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | Compte jusqu’à 2,000 codes à la fois (un lecteur RFID de type clavier ou une liste) ; chacun compte une fois et les codes sans correspondance sont renvoyés. | loans:write |
| PUT/loans/stocktakes/{id}/assign | Confie l’inventaire ouvert à un membre de l’équipe pour qu’il le compte (assigned_to), ou à personne (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | Termine l’inventaire et renvoie la liste des objets manquants. | loans:write |
| GET/loans/stocktake-schedules | Les inventaires qui s’ouvrent d’eux-mêmes, une fois ou de façon récurrente. | loans:read |
| POST/loans/stocktake-schedules | Planifie un inventaire, une fois, chaque semaine, chaque mois, tous les trois mois ou chaque année, à l’heure propre au site. | loans:write |
| PATCH/loans/stocktake-schedules/{id} | Modifie, met en pause ou reprend un plan. | loans:write |
| DELETE/loans/stocktake-schedules/{id} | Supprime un plan ; les inventaires qu’il a ouverts restent. | loans:write |
| GET/loans/last-seen | Où chaque objet a été scanné pour la dernière fois, quand le site enregistre les positions de scan (membres de l’équipe qui ont accepté seulement ; jamais depuis une clé). | loans:read |
| GET/loans/transfers | Les transferts de matériel entrants et sortants pour ce site. | loans:read |
| POST/loans/transfers | Prépare du matériel pour un autre site autorisé du même groupe de clients. | loans:write |
| POST/loans/transfers/{id}/send | Enregistre que le matériel préparé a quitté le site d’origine. | loans:write |
| POST/loans/transfers/{id}/receive | Réceptionne le matériel à destination avec son emplacement et son état à l’arrivée. | loans:write |
| POST/loans/transfers/{id}/cancel | Annule un transfert préparé avant l’expédition. | loans:write |
| POST/loans/transfers/{id}/reject | Rejette à destination un transfert préparé avant l’expédition. | loans:write |
| POST/loans/transfers/{id}/exception | Enregistre un problème pendant que le matériel est en transit. | loans:write |
| POST/loans/import | Prévisualise ou importe jusqu’à 5,000 lignes CSV avec les en-têtes de vFound, Snipe-IT, Sortly ou Cheqroom. | loans:write |
Visitors
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/visitors | Les visites, le changement le plus récent en premier, avec status (expected, in, out, cancelled ou missed), le visiteur, l’hôte, le code du laissez-passer tant qu’il est valide, et les heures. Filtres : status, search (visiteur, société, hôte ou code du laissez-passer), updated_since. | visitors:read |
| GET/visitors/{id} | Une visite. | visitors:read |
| POST/visitors | Invite un visiteur ou enregistre son arrivée. Accepte les champs du visiteur, de l’hôte et de l’heure, ainsi que visitor_type_id, des réponses, des dates de validité et une récurrence quotidienne ou en semaine. | visitors:write |
| POST/visitors/{id}/sign-in | Enregistre l’arrivée d’un visiteur attendu ; l’hôte est prévenu. Envoyez answers pour un membre d’un groupe dont le type a des questions obligatoires, et id_expires_on avec identity_checked quand le site enregistre la date d’expiration d’une pièce d’identité physique. La visite porte alors id_expires_on et id_expired. | visitors:write |
| POST/visitors/{id}/group/sign-in | Enregistre l’arrivée de tous les membres du groupe de la visite qui sont attendus aujourd’hui, avec un seul e-mail à l’hôte ; toute personne qui a besoin de sa propre photo, vérification d’identité, signature, réponses ou conditions est listée dans skipped. | visitors:write |
| POST/visitors/{id}/sign-out | Enregistre leur départ. | visitors:write |
| POST/visitors/{id}/cancel | Annule une invitation. | visitors:write |
| POST/visitors/{id}/send-pass | Renvoie le laissez-passer par e-mail. | visitors:write |
| POST/visitors/{id}/approve | Approuve une visite en attente et envoie le laissez-passer. | visitors:write |
| POST/visitors/{id}/deny | Refuse une visite en attente. | visitors:write |
| GET/visitors/{id}/badge | Télécharge le badge imprimable depuis le navigateur. Choisissez size 4x3, brother ou dymo. | visitors:read |
| GET/visitors/{id}/card | Indique si la visite a une carte RFID et ses quatre derniers caractères (jamais le numéro). Désactivé tant que le site n’active pas Cartes et badges. | visitors:read |
| POST/visitors/{id}/card | Donne une carte à une visite attendue ou enregistrée par son numéro ; un numéro n’est actif que sur une visite à la fois. | visitors:write |
| DELETE/visitors/{id}/card | Reprend la carte. | visitors:write |
| GET/visitors/{id}/assets | Les choses remises à la visite, saisies à la main. | visitors:read |
| POST/visitors/{id}/assets | Enregistre une chose remise à la visite, avec une étiquette facultative. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | Marque une chose comme rendue. | visitors:write |
| GET/visitor-assets/not-returned | Les choses remises à des visiteurs et pas encore rendues, les plus récentes d’abord. | visitors:read |
| GET/visitors/{id}/fast-track | Indique si la visite a un code d’accès rapide actif, jusqu’à quand et combien de fois il a été utilisé (jamais le code, que seul le visiteur voit). | visitors:read |
| POST/visitors/{id}/fast-track | Donne à un visiteur qui revient un code d’accès rapide valable days (1 à 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | Reprend le code. | visitors:write |
| GET/visitor-types | Liste les types de visiteurs et leurs questions, conditions, badges, approbations et durée de conservation (retention_days vaut null quand le type suit la valeur par défaut du site). | visitors:read |
| POST/visitor-types | Crée un type de visiteur. | visitors:write |
| PATCH/visitor-types/{id} | Modifie les champs du type de visiteur que vous envoyez. | visitors:write |
| DELETE/visitor-types/{id} | Désactive un type de visiteur sans modifier les visites précédentes. | visitors:write |
| GET/visitor-roll-call | Obtient le dernier appel d’évacuation et ses chiffres en direct. Un appel en cours ajoute toute personne qui s’est enregistrée depuis son début ; un appel laissé en cours pendant 6 heures est clos. | visitors:read |
| POST/visitor-roll-call | Démarre un appel d’évacuation, en incluant en option les visiteurs attendus aujourd’hui et toute personne en attente d’approbation. | visitors:write |
| PATCH/visitor-roll-call/entries/{entry} | Marque une entrée comme en sécurité ou manquante. | visitors:write |
| POST/visitor-roll-call/{id}/finish | Termine l’appel d’évacuation actif et garde son rapport. | visitors:write |
| GET/staff-attendance | Liste la présence du personnel sur une période à l’horloge du site (aujourd’hui par défaut, au plus 366 jours), ou seulement les personnes enregistrées en ce moment avec open=true. N’inclut jamais l’e-mail de la personne. | visitors:read |
| POST/staff-attendance | Enregistre l’arrivée (mode office ou remote) ou le départ d’une personne de la liste du personnel, avec les mêmes règles qu’à l’accueil. Exige que l’enregistrement du personnel soit activé sur le site. | visitors:write |
| POST/staff-presence | Envoie jusqu’à 50 événements de présence (in, out ou muster) depuis votre système de badges, de pointage ou de Wi-Fi, chacun nommant une personne de la liste du personnel par référence, identifiant externe ou e-mail. Exige que l’enregistrement du personnel et le flux de présence soient activés sur le site. Répond ce qui s’est passé pour chaque événement, jamais qui. | visitors:write |
| POST/visitors/{id}/catering | Crée, modifie ou (sans aucun article) supprime la demande de traiteur d’une visite attendue ou enregistrée, parmi les options que le site liste. Envoie un e-mail à la boîte de réception du traiteur du site ; vFound ne commande rien et ne prend aucun paiement. Exige que le traiteur soit activé sur le site. | visitors:write |
| GET/workplace/spaces | Liste les bureaux, salles de réunion et places de stationnement que les personnes peuvent réserver sur le site. | visitors:read |
| GET/workplace/free | Trouve les espaces libres pendant toute une période (au plus 7 jours), en écartant un bureau gardé pour une autre personne. | visitors:read |
| GET/workplace/bookings | Liste les réservations de bureaux, de salles et de stationnement sur une période d’au plus 31 jours. N’inclut jamais l’e-mail de la personne. | visitors:read |
| POST/workplace/bookings | Réserve un espace pour une personne, une fois ou en réservation récurrente (chaque jour ou chaque semaine, jusqu’à 52 fois, toutes ou aucune), selon les règles de réservation d’Equipment. | visitors:write |
| POST/workplace/bookings/{id}/cancel | Annule une réservation, ou avec scope following ou series ses dates suivantes. | visitors:write |
| POST/workplace/bookings/{id}/check-in | Enregistre l’arrivée pour une réservation, de 15 minutes avant son début jusqu’à sa fin. | visitors:write |
| POST/visitors/{id}/room | Réserve une salle de réunion pour une visite, à l’heure de la visite ; la salle suit la visite. | visitors:write |
| GET/appointment-pages | Liste les pages de rendez-vous du site, leurs horaires et si chacune est ouverte aux visiteurs maintenant. | visitors:read |
| GET/visitor-roll-call/archive | Liste les appels d’évacuation terminés (urgences, exercices et avis), le plus récent d’abord. | visitors:read |
| GET/visitor-roll-call/{id} | Un appel d’évacuation avec ses personnes, sa chronologie, ses vérifications de zone et le nombre de messages. | visitors:read |
| POST/visitor-roll-call/{id}/people | Ajoute une personne (un employé, une autre personne ou un prestataire) à l’appel d’évacuation en cours. | visitors:write |
| POST/visitor-roll-call/{id}/scan | Marque un visiteur comme en sécurité à partir du lien ou du code de son laissez-passer, à un point de rassemblement. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | Enregistre qu’une zone a été vérifiée et vide, ou qu’elle contient des personnes. | visitors:write |
| POST/visitor-roll-call/{id}/messages | Envoie un message à tout le monde, aux personnes pas encore en sécurité ou aux personnes qui ont besoin d’aide. Il part par e-mail, alerte du navigateur et, sur le propre fournisseur du site, par SMS ou WhatsApp, avec un lien privé pour répondre en sécurité ou besoin d’aide. | visitors:write |
| GET/visitor-roll-call/{id}/people/{entry}/messages | La conversation avec une personne lors d’un appel d’évacuation : ce que l’équipe lui a envoyé et ce qu’elle a répondu depuis son lien privé, les plus anciens d’abord. Répondez avec l’endpoint des messages et audience entry. | visitors:read |
| POST/visitor-hazard-alerts | Un avertissement qu’un membre de l’équipe rédige et envoie à un groupe choisi : hazard, message et group (on_site, visitor_type, host ou tenant, avec group_ref). Il démarre un appel d’évacuation de type hazard pour ce groupe. vFound ne lit aucun flux de météo, d’actualités ou de menaces : rien n’est envoyé à moins que vous n’envoyiez cette requête. Répond 409 tant qu’un autre appel d’évacuation est en cours. | visitors:write |
| POST/visitor-help-alerts | Demande de l’aide discrètement : les membres de l’équipe choisis pour cela sont prévenus ; aucun visiteur ne voit rien. | visitors:write |
| GET/visitor-kiosks | Liste les bornes associées, en attente et révoquées. | visitors:read |
| POST/visitor-kiosks/pairing | Crée un code d’association de huit caractères valable dix minutes. | visitors:write |
| DELETE/visitor-kiosks/{id} | Révoque une borne. | visitors:write |
| PUT/visitor-kiosks/{id}/settings | Modifie les réglages d’une borne : un e-mail quand elle n’a pas été vue pendant un certain nombre de minutes, le retour à l’écran de départ après un temps d’inactivité, une signature à l’enregistrement et l’impression du badge depuis la tablette. Tout est désactivé au départ. | visitors:write |
| GET/visitor-analytics | Les totaux par jour, heure, type et hôte, plus la durée moyenne de présence sur la dernière année. | visitors:read |
| GET/visitor-registration | Obtient le lien d’inscription préalable du site et s’il est activé. | visitors:read |
| GET/school/movements | Les arrivées tardives et les départs anticipés des élèves, les plus anciens d’abord, à partir de since (par défaut les 24 dernières heures), avec la reference de chaque élève pour le système d’information de l’école. Un membre de l’équipe en lecture seule nommé dans X-Acting-User ne peut pas l’utiliser. | school:read |
| PUT/school/pupils | Ajoute ou met à jour jusqu’à 500 élèves par reference ; envoyez active false pour un élève parti. Rien n’est supprimé ici. | school:write |
Les coordonnées des visiteurs sont des données personnelles : ne les gardez que le temps dont vous avez besoin.
Personnes
La liste de personnes contient les résidents, le personnel ou les étudiants que votre accueil sert. Parcels y trouve les destinataires, Visitors y trouve les hôtes, et Equipment y suggère des utilisateurs. Gardez-la alignée sur votre système RH, étudiant ou immobilier grâce à l’API.
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/people | La liste, par nom. Filtres : search (nom, e-mail, logement ou référence), updated_since. | people:read |
| GET/people/{id} | Une personne. | people:read |
| POST/people | Ajoute quelqu’un : name (obligatoire), email, unit, reference et language pour ses e-mails. | people:write |
| POST/people/upsert | Ajoute ou met à jour jusqu’à 500 personnes en un appel : people est une liste des mêmes champs. Quelqu’un dont l’e-mail est déjà dans la liste est mis à jour. Répond combien ont été ajoutées, mises à jour et ignorées. | people:write |
| PATCH/people/{id} | Modifie seulement les champs que vous envoyez. | people:write |
| DELETE/people/{id} | Supprime quelqu’un. Ses colis, visites et sorties gardent le nom qu’ils avaient. | people:write |
| GET/people/export | Télécharge la liste de personnes complète en CSV protégé contre les formules. | people:read |
| POST/people/{id}/send-my-vfound | Envoie par e-mail à une personne active la page signée de ses colis, visiteurs et matériel liés. | people:write |
| GET/people/sync-source | Affiche le répertoire CSV enregistré et le résultat de la dernière synchronisation. | people:read |
| PUT/people/sync-source | Enregistre une url CSV HTTPS publique et un mode (upsert ou mirror). | people:write |
| DELETE/people/sync-source | Retire la connexion et garde les personnes déjà importées. | people:write |
| POST/people/sync-source/run | Lance la connexion enregistrée maintenant. | people:write |
Les propriétaires et les responsables peuvent aussi connecter un lien CSV HTTPS public depuis Personnes. vFound le vérifie chaque heure, suit au plus trois redirections après avoir vérifié chaque destination, accepte au plus 10 MB et, en mode mirror, s’arrête avant de faire des changements quand le nombre de lignes valides baisse de plus de 30 pour cent. Les champs connectés sont modifiés à leur source.
Provisionnement automatique du répertoire
Microsoft Entra dispose de la connexion toute faite, configurée par le client, décrite plus haut. Les annuaires d’identité, dont Okta, OneLogin et JumpCloud, peuvent plutôt alimenter la liste de personnes à https://vfound.io/api/scim/v2/Users avec une clé d’API vFound qui a people:write. Utilisez la clé Bearer comme jeton secret. La désactivation retire la personne des suggestions ; DELETE anonymise les liens selon les mêmes règles de Personnes. Cet endpoint crée seulement des entrées de la liste de personnes et jamais de connexions d’équipe.
Les listes de formation d’Equipment peuvent venir du même annuaire : liez une formation à un groupe de l’annuaire par son nom (Equipment, Politiques, Formation), puis attribuez ce groupe à l’application vFound. https://vfound.io/api/scim/v2/Groups ne répond que pour les groupes qu’une formation nomme, et refuse tout autre groupe. Ses membres sont les personnes (par leur identifiant d’utilisateur SCIM) qui détiennent la formation ; une personne qui quitte le groupe ne perd la formation que si c’est l’annuaire qui l’a donnée, si bien qu’un enregistrement ajouté par le personnel reste. Un enregistrement donné par l’annuaire qui a expiré est renouvelé à partir de ce jour quand l’annuaire envoie à nouveau le groupe avec la personne toujours dedans. Les groupes ne répondent que pour un site avec Equipment. Comme l’appartenance à un groupe donne une formation, et qu’une formation permet aux personnes de sortir le matériel qui l’exige, une clé avec people:write peut accorder des formations de cette façon : gardez cette clé pour votre fournisseur d’identité.
Webhooks
Ajoutez jusqu’à 25 adresses HTTPS dans Réglages, Pour les développeurs, ou par l’API ci-dessous, et choisissez lesquels des événements ci-dessous chacune reçoit. vFound envoie un POST JSON en quelques secondes, réessaie les échecs pendant environ trois heures et met une adresse en pause après 15 envois échoués d’affilée.
| Événement | Quand | Données |
|---|---|---|
item.created | Un objet trouvé est ajouté | Objet |
item.updated | Son état, son titre, son emplacement, sa catégorie, sa date de conservation ou la visibilité de sa photo change | Objet |
item.transfer_sent | Un objet trouvé est envoyé à un autre site du groupe (les deux sites le reçoivent) | Transfert d’objet |
item.transfer_cancelled | Le site expéditeur le reprend avant son arrivée | Transfert d’objet |
item.transfer_received | Le site destinataire confirme son arrivée | Transfert d’objet |
claim.created | Un client soumet une demande | Demande |
item.disposition_recorded | Un objet est donné ou éliminé | Objet |
item.match_updated | Un verdict de correspondance IA enregistré change ; report_id, item_id, label et reason | Paire de correspondance |
lost_report.match_updated | Un verdict de correspondance IA enregistré change ; report_id, item_id, label et reason | Paire de correspondance |
claim.ownership_reviewed | Un responsable enregistre une vérification de propriété ; récupérez la garde pour l’historique des vérifications | Demande |
claim.decision_recorded | Une demande est acceptée ou rejetée | Demande |
claim.release_approved | Un autre responsable approuve la restitution | Demande |
claim.handover_recorded | Le retrait physique clôt une demande en attente de retrait | Demande |
claim.status_changed | Une demande passe à un nouvel état | Demande |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | Un client déclare une perte | Déclaration de perte |
parcel.logged | Un colis est enregistré à l’accueil ou par l’API | Colis |
parcel.updated | L’un de ses détails change à l’accueil, comme son destinataire, son numéro de suivi ou son étagère | Colis |
parcel.reminded | Le destinataire reçoit un rappel, de l’accueil ou automatiquement | Colis |
parcel.collected | Un colis est remis | Colis |
parcel.returned | Un colis est renvoyé à l’expéditeur | Colis |
parcel.recipient_arrived | Un destinataire dit qu’il est à l’accueil | Entrée de la file de retrait |
parcel.reminders_snoozed | Un destinataire met ses rappels en pause | Personne et nombre de colis |
parcel.held | Un destinataire définit une date de report | Personne, date et nombre de colis |
parcel.proxy_created | Un destinataire envoie par e-mail un code de retrait à un délégué | Personne, délégué et expiration |
parcel.pickup_served | L’accueil marque une arrivée comme servie | Entrée de la file de retrait |
parcel.escalated | Un colis en attente atteint l’ancienneté d’escalade du site | Colis |
parcel.outgoing_logged | Un colis sortant est enregistré | Colis sortant |
parcel.outgoing_handed_over | Un colis sortant est remis à un coursier | Remise sortante |
parcel.round_created | Une tournée de livraison est créée | Résumé de la tournée |
parcel.round_delivered | Un arrêt d’une tournée de livraison est terminé | Identifiants de la tournée, de l’arrêt et des colis |
checkroom.checked_in | Un dépôt est enregistré et reçoit un numéro | Ticket |
checkroom.handed_back | Il est remis | Ticket |
checkroom.left | La soirée est clôturée alors qu’il est encore au vestiaire | Ticket |
checkroom.self_checkin_started | Un client démarre un ticket depuis une borne associée | Ticket |
checkroom.ready_requested | Un client demande à l’accueil de préparer ses affaires | Ticket |
checkroom.ready | L’accueil indique que les affaires d’un client sont à retirer | Ticket |
checkroom.station_created | Un poste de vestiaire est créé | Poste |
checkroom.station_updated | Un poste de vestiaire change | Poste |
checkroom.event_created | Un événement de vestiaire est créé | Événement |
checkroom.event_updated | Un événement de vestiaire change | Événement |
loan.checked_out | Un objet est remis | Sortie |
loan.due_soon | Son échéance est dans moins de deux heures, une fois par échéance | Sortie |
loan.overdue | Son échéance passe et il n’est pas rendu, une fois par échéance | Sortie |
loan.extended | Son échéance change | Sortie |
loan.returned | Il revient à l’accueil | Sortie |
loan.lost | Il est enregistré comme ne revenant pas | Sortie |
loan.checkout_created | Une sortie atomique de plusieurs objets est créée | Sortie, avec tout stock du même reçu dans stock |
loan.self_checkout | Un utilisateur termine une sortie à la borne | Sortie |
loan.kit_created | Un kit de matériel enregistré est créé | Kit |
loan.kit_updated | Un kit de matériel enregistré change | Kit |
loan.reservation_requested | Une réservation attend une approbation | Réservation |
loan.reservation_created | Une réservation est confirmée immédiatement | Réservation |
loan.reservation_approved | Une réservation en attente est approuvée | Réservation |
loan.reservation_ready | Le matériel réservé est prêt à être retiré | Réservation |
loan.reservation_cancelled | Une réservation est annulée | Réservation |
loan.reservation_collected | Le matériel réservé est remis | Sortie |
loan.extension_requested | Un utilisateur demande plus de temps | Sortie |
loan.problem_reported | Un utilisateur signale un problème de matériel | Sortie |
loan.rule_updated | Une règle de sortie d’une catégorie change | Règle |
loan.maintenance_logged | Un entretien est enregistré | Entretien |
loan.maintenance_due | Un entretien planifié arrive à échéance | Entretien |
loan.service_due | Un plan d’entretien récurrent arrive à échéance (à une date, après un nombre d’heures de sortie ou un nombre de sorties), une fois par cycle | Entretien |
loan.work_order_opened | Un ordre de travail est ouvert, par le personnel ou par un retour pour lequel le site demande d’en ouvrir un | Entretien |
loan.work_order_closed | Un ordre de travail est terminé ou annulé | Entretien |
loan.item_disposed | Un objet est sorti de l’inventaire (vendu, mis au rebut, donné, recyclé, perdu ou volé) | Equipment |
loan.stocktake_started | Un inventaire de matériel commence | Inventaire |
loan.stocktake_completed | Un inventaire de matériel se termine | Inventaire |
loan.transfer_prepared | Un site autorisé prépare du matériel à déplacer | Transfert |
loan.transfer_sent | Le matériel préparé quitte son site d’origine | Transfert |
loan.transfer_received | Le site destinataire reçoit le matériel | Transfert |
loan.transfer_rejected | Le site destinataire rejette un transfert préparé | Transfert |
loan.transfer_cancelled | Le site d’origine annule un transfert préparé | Transfert |
loan.transfer_exception | Un transfert en transit demande de l’attention | Transfert |
loan.transfer_lost | Le site d’origine clôt un transfert qui n’est jamais arrivé | Transfert |
loan.charge_recorded | Des frais de pénalité, de dommage, de remplacement, d’utilisation ou autres sont enregistrés | Écriture de frais |
loan.charge_waived | Un responsable dispense de ce qu’il reste à régler sur des frais, avec un motif | Écriture de frais |
loan.payment_recorded | Le personnel enregistre de l’argent que le site a perçu lui-même (vFound ne traite jamais un paiement) | Écriture de frais |
loan.payment_voided | Un responsable annule un paiement enregistré par erreur | Écriture de frais |
loan.deposit_recorded | Le personnel enregistre une caution que le site a perçue | Écriture de frais |
loan.deposit_resolved | Une caution retenue est rendue ou conservée | Écriture de frais |
loan.invoice_issued | Une facture est émise pour les frais d’un utilisateur | Facture |
loan.invoice_voided | Un responsable annule une facture, avec un motif | Facture |
loan.quote_accepted | L’équipe accepte un devis et ses réservations sont créées | Devis |
loan.payment_request_created | L’équipe enregistre une demande de paiement (rien n’est envoyé à la personne) | Demande de paiement |
loan.payment_request_paid | Les paiements enregistrés pour une demande la couvrent entièrement | Demande de paiement |
loan.delivery_done | Une livraison ou une collecte est marquée comme terminée | Livraison |
loan.items_imported | Un import CSV de matériel se termine | Nombres |
visit.expected | Un visiteur est invité | Visite |
visit.signed_in | Un visiteur s’enregistre, à l’accueil ou depuis votre affiche QR | Visite |
visit.host_confirmed | L’accueil confirme qui un visiteur qui s’est enregistré lui-même venait voir | Visite |
visit.signed_out | Il enregistre son départ, à l’accueil, depuis son laissez-passer ou automatiquement après la fin de la journée | Visite |
visit.cancelled | Une invitation est annulée | Visite |
visit.approval_requested | Une visite attend l’approbation du personnel | Visite |
visit.approved | Une visite en attente est approuvée | Visite |
visit.denied | Une visite en attente est refusée | Visite |
visit.host_replied | Un hôte répond depuis son lien privé | Visite |
visit.roll_call_started | Un appel d’évacuation en direct (une urgence, un exercice ou un avis) démarre | Résumé de l’appel d’évacuation |
visit.roll_call_completed | Un appel d’évacuation en direct se termine | Résumé de l’appel d’évacuation |
visitor_type.created | Un type de visiteur est créé | Type de visiteur |
visitor_type.updated | Un type de visiteur change | Type de visiteur |
visitor_type.deactivated | Un type de visiteur est désactivé | Type de visiteur |
visitor_agreement.signed | Un visiteur a signé un document d’accord, avec un lien vers la copie signée qui fonctionne pendant sept jours | Signature d’accord |
kiosk.paired | Une borne de visiteurs est associée | Borne |
kiosk.revoked | Une borne de visiteurs est révoquée | Borne |
courier.signed_in | Un livreur est enregistré dans Parcels | Coursier |
courier.signed_out | Un livreur part | Coursier |
staff.signed_in | Une personne de la liste du personnel s’enregistre, au bureau ou à distance | Présence du personnel |
staff.signed_out | Une personne de la liste du personnel enregistre son départ, ou son départ est enregistré automatiquement | Présence du personnel |
person.created | Une personne est ajoutée | Personne |
person.updated | Une personne est modifiée | Personne |
person.deactivated | Le provisionnement du répertoire désactive une personne | Personne |
person.deleted | Une personne est supprimée | Personne |
people.sync.completed | Une synchronisation CSV connectée se termine | Nombres |
people.sync.failed | Une synchronisation CSV connectée échoue sans risque | Erreur |
report.delivered | Un rapport planifié de Rapports et analyses, partagé avec le site, s’exécute avec envoi aux webhooks choisis (un rapport privé n’est jamais envoyé aux webhooks) ; abonnez-vous dans Réglages, Pour les développeurs (une clé d’API ne peut pas s’y abonner) | Chaque colonne que le rapport nomme et jusqu’à 5,000 lignes, ou chaque groupe |
queue.ticket_joined | Une personne rejoint une file, depuis son téléphone, une borne, l’accueil ou l’API | Ticket de file |
queue.ticket_called | Une personne est appelée à un guichet, ou appelée à nouveau | Ticket de file |
queue.ticket_served | Une personne est marquée comme servie | Ticket de file |
queue.ticket_no_show | Une personne appelée est marquée comme absente, par l’équipe ou après les minutes de la file | Ticket de file |
queue.ticket_left | Une personne quitte la file depuis son ticket, ou l’équipe la retire | Ticket de file |
queue.ticket_transferred | Une personne est déplacée vers une autre file ou un autre guichet | Ticket de file |
queue.ticket_closed | Un ticket encore ouvert à la fin de la journée du site, ou dans une file archivée, est clos | Ticket de file |
queue.booking_created | Une personne réserve un créneau sur la page des créneaux réservés d’une file, ou l’API en réserve un | Réservation de file |
queue.booking_cancelled | Un créneau réservé est annulé par la personne, l’équipe ou l’API | Réservation de file |
queue.ticket_arrived | Une personne qui a rejoint la file avant d’arriver dit qu’elle est là, ou l’équipe la marque comme arrivée | Ticket de file |
queue.message_received | Une personne dans la file écrit à l’équipe depuis la page de son ticket ; l’événement ne contient aucun mot | Message de file |
queue.message_sent | L’équipe écrit à une personne dans la file ; l’événement ne contient aucun mot | Message de file |
queue.survey_answered | Une personne servie répond à l’enquête ; l’événement contient la note et jamais le commentaire | Réponse à l’enquête de file |
{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
"venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}
Vérifier la signature
Chaque envoi porte Vfound-Signature: t=<unix time>,v1=<hex>, où le hex est un HMAC SHA256 de t + "." + raw body avec le secret de votre endpoint. Rejetez les envois de plus de cinq minutes. Après la création d’un nouveau secret de signature, les envois portent deux valeurs v1 pendant 24 heures, une pour chaque secret, donc acceptez l’envoi si l’une d’elles correspond.
// 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;
Les en-têtes incluent aussi Vfound-Event et un identifiant Vfound-Delivery unique que vous pouvez utiliser pour ignorer les répétitions. Les webhooks ne sont envoyés qu’à des adresses HTTPS publiques sur le port 443.
S’abonner par l’API
Des outils comme Zapier peuvent ajouter et retirer leurs propres adresses avec une clé qui a webhooks:manage. Le secret de signature s’affiche une seule fois, dans la réponse au POST. La réponse contient aussi un en-tête Location avec l’adresse à appeler avec DELETE quand l’abonnement est retiré.
Une clé ne peut s’abonner qu’aux événements dont elle pourrait lire les données : chaque événement exige la portée de lecture de son produit (items:read pour les événements d’objets, claims:read pour les événements de demandes, lost_reports:read, parcels:read, checkroom:read, loans:read pour les événements de matériel, visitors:read pour les événements de visites, de types de visiteurs, de bornes et de coursiers, et people:read pour les événements de personnes et de liste de personnes). Une clé ne liste et ne retire que les adresses qu’elle a créées elle-même ; les adresses ajoutées dans Réglages, ou par une autre clé, ne lui sont pas visibles.
| Requête | Ce qu’elle fait | Portée |
|---|---|---|
| GET/webhooks | Les adresses que cette clé a créées, et leurs événements. | webhooks:manage |
| POST/webhooks | Ajoute une adresse : url (HTTPS public sur le port 443) et events, une liste des événements ci-dessus que la clé peut lire. | webhooks:manage |
| DELETE/webhooks/{id} | Retire une adresse que cette clé a créée, et son historique des envois. | webhooks:manage |
Historique des envois
Réglages, Pour les développeurs, liste chaque envoi vers chaque adresse des 30 derniers jours, avec son déroulement, et en renvoie n’importe lequel avec le même identifiant Vfound-Delivery. Vous pouvez aussi y modifier une adresse, réactiver une adresse en pause et créer un nouveau secret de signature. Une adresse qui échoue 15 envois d’affilée est mise en pause, et le propriétaire du site reçoit un e-mail.
Flux de données de rapport (Power BI)
Un propriétaire ou un responsable crée un lien de flux dans Rapports et analyses, sous Flux de données Power BI, pour les produits qu’il choisit. Le lien s’affiche une seule fois. Dans Power BI, choisissez Obtenir les données, puis Web, et collez-le. Chaque lien ne lit qu’un seul site, et s’arrête aussitôt quand il est révoqué, quand la personne qui l’a créé n’est plus propriétaire ou responsable du site, ou quand le site est en pause ou fermé.
GET /api/feeds/reports/{token}/{dataset} répond avec les lignes d’un jeu de données : equipment_loans, equipment_activity, visits ou checkroom_tickets. Choisissez sa période avec days (1 à 366, 90 si omis) ou from et to (YYYY-MM-DD, à l’horloge du site). GET /api/feeds/reports/{token}/saved/{id} répond avec un rapport enregistré partagé avec tout le site, pour la période propre à ce rapport ; days, from et to ne la modifient pas. Vous pouvez aussi envoyer le jeton comme Authorization: Bearer <token> à /api/feeds/reports/{dataset} ou /api/feeds/reports/saved/{id}. Une réponse contient jusqu’à 100,000 lignes dans value, si bien que Obtenir les données, Web lit tout le résultat ; transformez ensuite la liste value en tableau. La réponse se termine par total et truncated : quand plus de lignes correspondent que n’en contient une réponse, truncated vaut true et @odata.nextLink nomme le reste ($top et $skip les parcourent page par page, pour les outils qui le suivent) ; Obtenir les données, Web ne le suit pas, choisissez donc une période plus courte. Quand les lignes d’un rapport exigeraient la lecture de plus de 400,000 lignes ou plus de 20 secondes, la réponse se termine par error, total null et truncated true ; un rapport enregistré groupé répond 422 avec la raison à la place. Les lignes arrivent dans l’ordre où elles ont été enregistrées. Les heures dans les lignes sont en UTC (ISO 8601) ; un rapport enregistré groupé par une date étiquette chaque groupe par jour, semaine, mois, jour de la semaine ou heure à l’horloge du site. Les adresses e-mail et le nom et la chambre d’un client du vestiaire sont omis, sauf si le lien a été créé pour inclure les coordonnées.
Assistants IA (MCP)
vFound est un serveur Model Context Protocol à https://vfound.io/api/mcp, pour que des assistants IA puissent chercher des informations et aider à l’accueil. Connectez-en un de deux façons : se connecter avec vFound, pour les assistants dont les connecteurs se connectent avec OAuth, ou une clé d’API, pour les clients qui envoient un en-tête, comme Claude Code, Cursor et Visual Studio Code. Dans les deux cas, il ne voit que les outils que ses portées permettent, pour les produits que votre site a ouverts. Un client connecté avec une clé d’API peut aussi envoyer X-Acting-User ; chaque outil s’exécute alors au nom de ce membre de l’équipe, dans les limites de son rôle.
# 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_…"}}}}
| Outil | Ce qu’elle fait | Portée |
|---|---|---|
search_found_items | Chercher des objets trouvés par des mots comme « iPhone noir » | items:read |
list_expected_visitors | Les visiteurs invités et pas encore arrivés | visitors:read |
list_visitors_on_site | Les visiteurs enregistrés en ce moment | visitors:read |
list_visitor_types | Les types de visiteurs et leurs règles | visitors:read |
visitor_analytics | Les totaux, tendances et durée moyenne de présence des visiteurs | visitors:read |
visitor_registration_link | Le lien d’inscription préalable du site | visitors:read |
list_couriers_on_site | Les coursiers enregistrés par Visitors | parcels:read |
list_waiting_parcels | Les colis qui attendent d’être retirés | parcels:read |
detect_parcel_tracking | Normaliser un numéro de suivi et détecter son transporteur | parcels:read |
parcel_pickup_queue | Les personnes qui attendent à l’accueil des colis | parcels:read |
parcel_shelves | La capacité et l’occupation des étagères à colis | parcels:read |
parcel_analytics | Le volume de colis, les transporteurs et la performance des retraits | parcels:read |
list_outgoing_parcels | Les colis sortants et leur état de remise | parcels:read |
list_parcel_rounds | Les tournées de livraison de colis et leurs arrêts | parcels:read |
list_checkroom_exit_queue | Les tickets dont les clients attendent à la sortie | checkroom:read |
mark_checkroom_ready | Marquer un ticket en attente comme prêt et prévenir le client | checkroom:write |
list_checkroom_stations | Les postes de vestiaire et les plages de numéros | checkroom:read |
list_checkroom_events | Les événements de vestiaire récents et à venir | checkroom:read |
checkroom_report | Le volume du vestiaire, le délai de remise et les totaux de frais | checkroom:read |
list_queue_lines | Les files, les personnes en attente et l’attente estimée maintenant | queue:read |
list_queue_waiting | Les personnes en attente aujourd’hui, dans l’ordre d’appel | queue:read |
queue_report | Les totaux de la file et les minutes médianes d’attente et de service | queue:read |
call_next_in_queue | Appeler la personne suivante à un guichet | queue:write |
mark_queue_ticket_served | Marquer la personne au guichet comme servie | queue:write |
list_overdue_equipment | Le matériel dont l’échéance est dépassée, et qui l’a | loans:read |
list_equipment_kits | Les groupes de matériel enregistrés | loans:read |
create_equipment_kit | Enregistrer un kit de matériel réutilisable sans le remettre | loans:write |
list_equipment_reservations | Les réservations par heure et par état | loans:read |
reserve_equipment | Réserver un objet ou une catégorie sans le remettre | loans:write |
book_repeating_reservation | Réserver un objet, une catégorie ou un espace chaque jour ou chaque semaine | loans:write |
move_reservation | Déplacer une réservation vers de nouvelles heures ou un autre objet de sa catégorie | loans:write |
list_waitlist | Les personnes qui attendent un créneau qui a été pris | loans:read |
join_waitlist | Ajouter quelqu’un à la liste d’attente | loans:write |
list_space_bookings | Chaque salle, bureau ou place de stationnement et ses réservations entre deux heures | loans:read |
book_space | Réserver une salle ou un espace pour une personne et une heure ; il n’est jamais remis | loans:write |
list_equipment_rules | Les règles de sortie du site et des catégories | loans:read |
save_equipment_rule | Créer ou remplacer une règle de catégorie | loans:write |
list_equipment_maintenance | L’historique d’entretien du matériel et les travaux à venir | loans:read |
list_equipment_service_plans | Les plans récurrents d’entretien, d’étalonnage, de test de sécurité, d’inspection et de nettoyage, et lesquels sont dus | loans:read |
update_equipment_work_order | Modifier ou clore un ordre de travail de matériel | loans:write |
get_equipment_maintenance_costs | Le coût d’entretien, de réparation et de nettoyage par objet | loans:read |
get_equipment_valuation | La valeur du matériel à une date après amortissement (propriétaires et responsables) | loans:read |
list_equipment_substances | Le registre des substances dangereuses : substance, emplacement, classes de danger et dates de revue (un enregistrement, aucun conseil de sécurité) | loans:read |
get_equipment_funding | Ce que chaque fonds, subvention ou centre de coûts a acheté et quel travail lui a été imputé (propriétaires et responsables) | loans:read |
get_equipment_planner | Les travaux planifiés et les ordres de travail ouverts par jour propre au site | loans:read |
list_equipment_licences | Les licences du matériel avec les postes et les dates de fin (propriétaires et responsables) | loans:read |
get_equipment_expiries | Les assurances et licences qui se terminent bientôt ou sont déjà terminées (propriétaires et responsables) | loans:read |
log_equipment_maintenance | Enregistrer un entretien, un étalonnage, un test de sécurité, une inspection, un nettoyage, une réparation ou une note | loans:write |
list_equipment_stocktakes | Les inventaires récents et leurs comptages | loans:read |
start_equipment_stocktake | Démarrer un inventaire | loans:write |
scan_equipment_stocktake | Enregistrer un objet dans un inventaire ouvert | loans:write |
scan_many_equipment_stocktake | Compter de nombreux codes d’un coup dans un inventaire ouvert | loans:write |
finish_equipment_stocktake | Terminer un inventaire et renvoyer ce qui manque | loans:write |
list_equipment_transfers | Les transferts entrants et sortants sans les coordonnées des utilisateurs | loans:read |
preview_equipment_import | Valider un CSV de matériel sans l’enregistrer | loans:write |
find_person | Chercher quelqu’un dans la liste de personnes | people:read |
export_people | Exporter la liste de personnes en CSV protégé contre les formules | people:read |
directory_sync_status | Vérifier la connexion CSV enregistrée et sa dernière exécution | people:read |
run_directory_sync | Lancer la connexion CSV enregistrée maintenant | people:write |
email_my_vfound | Envoyer par e-mail à une personne sa page privée signée | people:write |
invite_visitor | Inviter un visiteur, qui reçoit un laissez-passer par e-mail | visitors:write |
approve_visit | Approuver une demande de visite en attente | visitors:write |
list_free_workplace_spaces | Trouver des bureaux, salles de réunion ou places de stationnement libres pour une période | visitors:read |
book_workplace_space | Réserver un bureau, une salle de réunion ou une place de stationnement pour une personne | visitors:write |
request_visit_catering | Demander un traiteur avec une visite, parmi les options que le site liste | visitors:write |
list_appointment_pages | Lister les pages de rendez-vous du site et si chacune est ouverte aux visiteurs | visitors:read |
list_staff_on_site | Lister les personnes de la liste du personnel enregistrées en ce moment, au bureau ou à distance | visitors:read |
sign_staff_in_or_out | Enregistrer l’arrivée ou le départ d’une personne de la liste du personnel | visitors:write |
list_visitor_assets_not_returned | Lister les choses remises à des visiteurs qui ne sont pas encore marquées comme rendues | visitors:read |
issue_visitor_asset | Enregistrer une chose remise à une visite attendue ou enregistrée | visitors:write |
return_visitor_asset | Marquer une chose remise à une visite comme rendue | visitors:write |
start_roll_call | Démarrer un appel d’évacuation ou renvoyer l’appel en cours | visitors:write |
mark_visitor_safe | Marquer un visiteur comme en sécurité | visitors:write |
create_kiosk_pairing | Créer un code d’association de borne de dix minutes | visitors:write |
log_parcel | Enregistrer un colis et prévenir le destinataire par e-mail | parcels:write |
remind_parcel | Rappeler à un destinataire de retirer un colis | parcels:write |
remind_parcels | Rappeler à jusqu’à 200 destinataires de colis sélectionnés | parcels:write |
log_outgoing_parcel | Ajouter un colis sortant au registre des coursiers | parcels:write |
create_parcel_round | Créer une tournée de livraison à partir des colis en attente | parcels:write |
extend_loan | Donner plus de temps à un utilisateur | loans:write |
Chaque outil exécute la requête d’API ci-dessus avec les mêmes contrôles, si bien qu’un assistant ne peut jamais faire plus que sa clé ou sa connexion. Aucun outil ne remet quoi que ce soit, n’enregistre l’arrivée ou le départ de quiconque, ne décide d’une demande ni ne supprime. Chaque réponse compte dans les 120 requêtes par minute de la clé ou de la connexion.
Se connecter avec vFound
Ajoutez https://vfound.io/api/mcp comme connecteur dans votre propre assistant. L’assistant trouve seul comment se connecter et ouvre une page vFound, où un propriétaire ou un responsable se connecte à son espace de travail comme d’habitude, choisit le site et voit en termes simples ce que l’assistant peut faire, et peut décocher n’importe quoi. Le personnel et les membres en lecture seule ne peuvent pas connecter d’assistant. L’assistant est celui de votre site : votre abonnement chez son fournisseur paie son IA, et vFound ne reçoit que les requêtes d’outils qu’il envoie.
Une connexion agit au nom de la personne qui l’a autorisée, avec les mêmes contrôles qu’une clé d’API : elle cesse de fonctionner si cette personne ne gère plus le site ou si le site n’est pas actif, elle ne change rien tant que l’abonnement est en pause, et elle ne voit des outils que pour les produits ouverts. Son jeton d’accès dure une heure et l’assistant le renouvelle seul ; une connexion inutilisée pendant 30 jours doit se reconnecter. Voyez chacune, qui l’a connectée et quand elle a été utilisée pour la dernière fois dans Réglages, Pour les développeurs, où Déconnecter l’arrête aussitôt. Le jeton ne fonctionne que sur l’endpoint MCP, pas sur l’API REST ; une application qui a besoin de l’API REST se connecte comme l’explique la section suivante.
Pour les développeurs de clients : OAuth 2.1 comme le décrit la spécification d’autorisation MCP, avec uniquement le flux de code d’autorisation et PKCE (S256). Découverte : /.well-known/oauth-protected-resource (RFC 9728, ressource https://vfound.io/api/mcp) et /.well-known/oauth-authorization-server (RFC 8414) ; une requête sans jeton reçoit un en-tête WWW-Authenticate qui nomme la première. Les clients s’enregistrent eux-mêmes à /oauth/register (RFC 7591) comme clients publics sans secret ; les adresses de redirection doivent utiliser https, ou http seulement pour localhost ou 127.0.0.1, et doivent alors correspondre exactement. Puis /oauth/authorize, /oauth/token (les codes durent 60 secondes et ne servent qu’une fois ; les jetons de rafraîchissement sont remplacés à chaque utilisation, et en réutiliser un ancien déconnecte l’assistant) et /oauth/revoke (RFC 7009). Les portées utilisent les noms des clés d’API ci-dessus ; envoyez resource=https://vfound.io/api/mcp (RFC 8707).
Se connecter avec vFound pour d’autres applications
Une application qui n’est pas un assistant IA, comme un système de stock, de réservation ou RH, peut se connecter de la même façon à l’API REST au lieu d’utiliser une clé d’API : envoyez resource=https://vfound.io/api/v1 à /oauth/authorize et /oauth/token, avec des portées dans les noms des clés d’API, sauf webhooks:manage, qu’une application ne peut pas recevoir. Un propriétaire ou un responsable se connecte, voit le nom de l’application et ce qu’elle peut faire en termes simples, peut décocher n’importe quoi et l’autorise. La connexion agit au nom de cette personne avec les mêmes contrôles qu’une clé d’API : elle cesse de fonctionner si elle ne gère plus le site ou si le site n’est pas actif, elle ne change rien tant que l’abonnement est en pause, et elle peut faire 120 requêtes par minute, comme une clé. X-Acting-User ne fonctionne qu’avec une clé d’API. Son jeton d’accès ne fonctionne que sur l’API REST, jamais sur l’endpoint MCP, et un consentement donné pour l’un n’approuve jamais l’autre. Elle figure dans Réglages, Pour les développeurs comme une application qui utilise l’API vFound, où Déconnecter l’arrête aussitôt. Découverte : /.well-known/oauth-protected-resource/api/v1 ; le reste est le flux ci-dessus.
Erreurs
Les erreurs sont du JSON avec un message ; les erreurs de validation ajoutent errors par champ. 401 signifie aucune clé valide, 403 une portée manquante, une clé dont le créateur ne gère plus le site, un membre de l’équipe dans X-Acting-User qui n’est pas un membre actif ou dont le rôle n’autorise pas la portée, un site qui n’est pas actif, ou une modification envoyée alors que l’abonnement est en pause, 404 introuvable dans votre site, 422 une saisie invalide et 429 trop de requêtes.
Quand une modification ne peut pas avoir lieu à cause de l’état actuel de l’enregistrement, la réponse est 422 avec aussi un code stable. Les codes ne changent jamais de nom :
| Code | Ce que cela signifie |
|---|---|
parcel_not_waiting | Le colis n’est plus en attente : il a déjà été retiré, renvoyé ou livré. |
tracking_duplicate | Un colis avec ce numéro de suivi attend déjà ici. |
no_email | La personne ou le visiteur n’a pas d’adresse e-mail, donc rien ne peut être envoyé. |
capacity_full | Tous les numéros du vestiaire sont utilisés. |
already_checked_in | Le ticket de vestiaire est déjà enregistré. |
already_handed_back | Le ticket de vestiaire a déjà été remis. |
nothing_to_hand_back | Le ticket de vestiaire n’a rien à remettre. |
number_in_use | Ce numéro de vestiaire est déjà utilisé. |
ticket_closed | Seul un ticket de vestiaire ouvert peut être envoyé par e-mail. |
item_out | Le matériel est sorti chez quelqu’un. Reprenez-le d’abord. |
item_in_repair | Le matériel est mis de côté pour réparation. |
item_retired | Le matériel est retiré du service, donc il ne peut ni être remis ni être réservé. |
reservation_conflict | Quelqu’un a réservé l’objet, ou le dernier libre de sa catégorie, pendant cette période, ou il devrait encore être sorti. |
already_back | Le matériel a déjà été repris. |
not_out | Le matériel n’est pas sorti, donc il ne peut recevoir ni plus de temps ni un rappel, ni être marqué comme ne revenant pas. |
borrower_overdue | L’utilisateur a du matériel en retard, et le site ou la catégorie n’autorise rien de plus avant son retour. |
borrower_item_limit | Cela donnerait à l’utilisateur plus d’objets que le site ou la catégorie n’en autorise en même temps. |
reservation_not_ready | La réservation n’est pas encore approuvée, ou elle a déjà été retirée ou annulée. |
reservation_item_mismatch | La sortie n’inclut pas l’objet pour lequel la réservation a été faite. |
reservation_category_mismatch | La sortie inclut un objet hors de la catégorie réservée. |
reservation_borrower_mismatch | La réservation appartient à un autre utilisateur. |
reservation_too_long | La réservation est plus longue que ce que la catégorie permet. Seules les réservations faites depuis My vFound sont limitées de cette façon. |
reservation_daily_limit | L’utilisateur a déjà fait 5 réservations depuis My vFound au cours des dernières 24 heures. |
booking_notice | La réservation commence plus tôt que le préavis minimum de la catégorie ne le permet. |
booking_too_far_ahead | La réservation, la sortie ou la nouvelle échéance se termine plus tard que ce que la catégorie permet de réserver à l’avance. |
desk_closed | La réservation commencerait un jour où l’accueil du matériel est fermé. |
kit_unavailable | Une partie d’un kit ou d’un panier n’est pas disponible pour cette période, donc rien n’a été réservé. Le champ unavailable liste chaque partie et pourquoi. |
borrower_not_in_group | Le site ne laisse sortir ou réserver que les personnes qui ont un type d’utilisateur, et cet utilisateur n’en a aucun (ou a été saisi à la main au lieu d’être choisi dans la liste de personnes). |
category_not_allowed | Aucun des types d’utilisateur de cet utilisateur n’autorise cette catégorie. |
borrower_on_hold | Les sorties sont suspendues pour cette personne : le personnel a mis un blocage, le site suspend les sorties après des retours en retard répétés, ou elle doit au moins le montant à partir duquel le site bloque (kind charges). Le champ hold donne son type et jusqu’à quand. |
space_too_small | Plus de personnes que la salle ou l’espace n’en peut accueillir (sa capacité). |
kit_locked | Le matériel appartient à un kit verrouillé, qui ne sort qu’en entier : incluez chaque objet nommé du kit. |
approval_not_yours | Le site a défini des approbateurs dans un ordre et cette personne n’est pas la suivante (ou le site ne laisse personne sauter une étape pour elle). |
project_not_approved | La réservation appartient à un projet qui n’est pas encore approuvé, donc rien ne peut être retiré. |
not_enough_credits | Le site utilise des crédits de réservation et cette personne n’en a plus. Donnez-lui-en d’abord. Une réservation annulée ou jamais retirée rend son crédit. |
risk_assessment_pending | La réservation a une évaluation de risque qui n’a pas été approuvée, donc rien ne peut être retiré. |
series_unavailable | Une réservation récurrente n’a pas pu être faite parce qu’au moins l’une de ses dates est prise ou contraire à une règle de réservation, donc rien n’a été réservé. Le champ skipped liste chaque date et pourquoi. |
time_available | Le créneau que quelqu’un a demandé d’attendre est libre, réservez-le donc au lieu de rejoindre la liste d’attente. |
space_not_handed_out | Une salle ou un espace est réservé pour son créneau et jamais remis, donc il ne peut ni être sorti ni être retiré. |
stock_short | Il n’y a pas assez de cet article en stock dans l’emplacement (et le lot) nommés, donc rien n’a changé. Le champ available donne la quantité qui s’y trouve. |
stock_issue_closed | Tout ce qui a été remis de ce stock est déjà revenu ou passé en perte. |
order_closed | Un bon de commande est terminé ou annulé et ne peut plus changer. |
order_over_received | Une quantité plus grande que ce qu’une ligne de bon de commande attend encore a été saisie. |
order_not_placed | Le stock ne peut pas être réceptionné sur un bon de commande encore à l’état de brouillon. |
fees_off | Les frais sont désactivés pour ce site. Activez-les d’abord dans la politique d’accueil et de sorties. |
entry_closed | Cette écriture de frais ou cette facture ne peut plus changer de cette façon : les frais sont réglés ou dispensés, le paiement est annulé, la caution a été rendue ou conservée, ou la facture est annulée. |
on_invoice | Les frais figurent sur une facture émise. Annulez d’abord la facture, puis dispensez les frais. |
not_late | La sortie n’est pas revenue en retard selon les règles de pénalité de retard du site, ou elle est encore sortie. |
nothing_to_invoice | L’utilisateur n’a aucun frais ouvert dans cette devise qui ne soit pas déjà sur une facture émise. |
charge_unavailable | L’un des frais choisis n’est pas ouvert, figure sur une autre facture ou concerne quelqu’un d’autre. |
desk_kept | Le bureau est gardé pour une autre personne l’un des jours demandés. |
desk_has_bookings | Garder le bureau pour cette personne entrerait en conflit avec des réservations ouvertes d’autres personnes ces jours-là. Annulez-les d’abord. |
booking_closed | La réservation du bureau, de la salle ou du stationnement a été annulée ou libérée, donc l’arrivée ne peut pas être enregistrée. |
check_in_closed | L’enregistrement de l’arrivée ouvre 15 minutes avant le début d’une réservation et se ferme à sa fin. |
item_service_due | Le site empêche de sortir le matériel qui a besoin d’entretien, et la date d’entretien de cet objet est arrivée ou l’un de ses plans est dû. Enregistrez d’abord le travail. |
item_failed_inspection | Le site empêche de sortir le matériel qui a besoin d’entretien, et la dernière vérification de cet objet a échoué. Enregistrez d’abord une réussite. |
work_order_closed | Cet ordre de travail est déjà clos et ne peut pas être modifié. |
already_disposed | Cet objet est déjà sorti de l’inventaire. |
not_disposed | Cet objet n’a pas été sorti de l’inventaire, donc il n’y a rien à annuler. |
item_disposed | Cet objet a été sorti de l’inventaire. Annulez cette sortie définitive avant de l’utiliser à nouveau. |
training_required | Une règle de catégorie ou l’objet exige une formation que l’utilisateur ne détient pas, ou ne détient que passée sa date d’expiration. Le champ training nomme ce qui manque. |
stocktake_open | Un inventaire est déjà ouvert. Terminez-le d’abord. |
item_unavailable | Le matériel n’est pas disponible ou est mis de côté pour réparation, donc il ne peut pas démarrer un transfert. |
transfer_open | Le matériel a déjà un transfert ouvert. |
transfer_not_ready | Seul un transfert préparé peut être envoyé. |
transfer_not_in_transit | Seul du matériel en transit peut être réceptionné ou signalé avec un problème. |
transfer_already_sent | Un transfert envoyé ne peut plus être annulé ni rejeté. |
already_signed_in | Le visiteur est déjà enregistré. |
visit_closed | La visite est close. Enregistrez l’arrivée du visiteur comme une nouvelle visite. |
not_signed_in | Le visiteur n’est pas enregistré. |
not_expected | Seule une visite attendue peut être annulée ou se voir envoyer un laissez-passer. |
approval_required | La visite a besoin d’une approbation avant que le visiteur puisse s’enregistrer. |
visit_not_valid_today | Le laissez-passer ne peut plus être utilisé aujourd’hui, ou aujourd’hui est hors de ses dates. |
plus_one_not_allowed | Le laissez-passer n’autorise pas d’invités, ou il n’est plus approuvé, attendu ou valide. |
plus_one_limit | Le visiteur a ajouté tous les invités que le laissez-passer permet. |
nobody_to_sign_in | Personne dans le groupe de la visite n’est attendu aujourd’hui. |
visitor_capacity_full | Enregistrer le visiteur dépasserait la limite du site ou du type de visiteur pour le nombre de visiteurs enregistrés en même temps. |
Enregistrer l’arrivée d’un visiteur à l’accueil répond 409 avec un code quand le visiteur a d’abord besoin d’une vérification par un membre de l’équipe. La réponse nomme seulement le type de correspondance (blocklist, building, restricted_party ou answers) ; l’entrée, son nom et son motif sont réservés à l’équipe du site et ne figurent jamais dans une réponse d’API. Renvoyez la requête avec screening_reviewed à true seulement une fois qu’un membre de l’équipe a vérifié la correspondance. Cela exige une clé avec la portée visitors:screening (désactivée par défaut, comme l’accès de toute autre clé à celle-ci), et une clé qui nomme un membre de l’équipe dans X-Acting-User en exige un dont le rôle décide des visites. La confirmation est enregistrée comme celle de la clé, par son nom, jamais comme celle du membre de l’équipe qui a créé la clé. Sans la portée, la réponse est 403 avec screening_scope. Il en va de même pour l’approbation d’une visite qu’une correspondance retient :
| Code | Ce que cela signifie |
|---|---|
screening_match | Le visiteur correspond à l’une des listes de blocage du site, à une vérification de l’équipe ou à la liste de contrôle. Un membre de l’équipe doit confirmer qu’il a vérifié la correspondance avant d’enregistrer l’arrivée du visiteur. |
screening_scope | La requête confirme ou approuve une correspondance de contrôle, et la clé n’a pas la portée visitors:screening (ou le membre de l’équipe nommé dans X-Acting-User ne décide pas des visites). |
Listes de contrôle de workflow
Un site sur vFound Enterprise peut définir les étapes que son personnel confirme à un moment clé : enregistrer, remettre, donner ou éliminer un objet trouvé ; remettre ou renvoyer un colis ; enregistrer un dépôt ou remettre au vestiaire ; sortir du matériel ou le reprendre ; et enregistrer l’arrivée ou le départ d’un visiteur. Tant qu’une liste s’applique, ces requêtes acceptent un champ checklist : [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}], ou un objet de clé vers true ou un texte de note. 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 et POST /visitors/{id}/sign-out l’acceptent. Sans les étapes requises, la réponse est 422 avec le code checklist_incomplete et un objet checklist nommant les étapes encore à confirmer, et rien ne change. Quand aucune liste ne s’applique, le champ est ignoré. Les listes complétées, avec qui les a confirmées et quand, figurent dans checklists sur les réponses d’un seul objet, d’une seule demande, d’un seul colis, ticket, sortie et visite.
| Code | Ce que cela signifie |
|---|---|
checklist_incomplete | 422 : une liste de contrôle de workflow s’applique à cette étape et ses étapes requises ne sont pas confirmées. |
Les nouvelles tentatives avec un en-tête Idempotency-Key peuvent aussi répondre avec un code :
| Code | Ce que cela signifie |
|---|---|
idempotency_key_invalid | 400 : l’en-tête ne compte pas de 1 à 191 caractères ASCII visibles. |
idempotency_key_reused | 422 : cette clé a déjà été utilisée pour une requête différente. |
idempotency_in_progress | 409 : la première requête avec cette clé est encore en cours. Réessayez dans un instant. |
offline_in_progress | La première copie de cette action hors ligne est encore en cours d’enregistrement. L’appareil la renvoie dans un instant. |
Une requête qui nomme un membre de l’équipe dans X-Acting-User peut aussi répondre avec un code :
| Code | Ce que cela signifie |
|---|---|
acting_user_refused | 403 : l’en-tête ne nomme pas exactement un membre actif de l’équipe de ce site, ou la clé est une connexion faite en se connectant avec vFound. |
acting_user_role | 403 : le membre de l’équipe nommé ne peut pas utiliser la portée de cette opération avec son rôle sur le site. |