Home di vFoundRichiedi la prova gratuita
SVILUPPATORI

L’API e i webhook di vFound

Collega la suite vFound ai sistemi che già usi: gestione delle strutture, service desk, sistemi per le risorse umane e per gli studenti, scanner dell’ufficio posta, data warehouse o le tue app. Leggi e modifica i record di ogni prodotto, tieni sincronizzato l’elenco delle persone, ricevi un webhook firmato entro pochi secondi quando succede qualcosa e lascia che gli assistenti IA ti aiutino al banco.

Preferisci una configurazione guidata? Guarda le guide di integrazione di vFound per Cloudbeds, OfficeRnD Flex, Microsoft Entra, Slack, Microsoft Teams, Google Chat, calendari, Zapier e client MCP.

Autenticazione

Ogni sede ha l’API. Un titolare o un responsabile crea fino a 10 chiavi in Impostazioni, Per sviluppatori, scegliendo che cosa può fare ciascuna chiave. La chiave completa viene mostrata una sola volta. Inviala come token Bearer:

curl https://vfound.io/api/v1/items \
  -H "Authorization: Bearer vf_live_xxxxxxxxxx_…"
AmbitoConsenteEndpoint
items:readLeggere gli oggetti ritrovati, le categorie e i trasferimenti tra sediGET /items, /items/{id}, /categories, /item-transfers
items:writeAggiungere e aggiornare gli oggetti ritrovati, e inviarli o riceverli tra sediPOST /items, PATCH /items/{id}, POST /item-transfers e le relative azioni cancel e receive
claims:writeRegistrare le verifiche di proprietà fatte da persone, le decisioni, l’approvazione del rilascio e il ritiroPOST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover
lost_reports:writeCreare segnalazioni degli ospiti per un contact centerPOST /lost-reports
claims:readLeggere le richieste, con i dati di contatto del richiedenteGET /claims, /claims/{id}
lost_reports:readLeggere le segnalazioni di smarrimento degli ospitiGET /lost-reports
analytics:readLeggere il riepilogo delle analisiGET /analytics
parcels:readLeggere i pacchi, con nome ed e-mail di ogni destinatarioGET /parcels, /parcels/{id}
parcels:writeRegistrare, consegnare, restituire e inviare promemoriaPOST /parcels e le relative azioni
checkroom:readLeggere ticket, postazioni, eventi, la coda d’uscita e i reportGET sotto /checkroom
checkroom:writeRegistrare il deposito, riconsegnare, segnare come pronto e gestire postazioni o eventiPOST e PUT sotto /checkroom
loans:readLeggere le attrezzature e chi le haGET /loans, /loans/items e una singola voce di ciascuno
loans:writeAggiungere attrezzature, consegnarle, prorogare e riprenderePOST e PATCH sotto /loans
visitors:readLeggere le visiteGET /visitors, /visitors/{id}
visitors:writeInvitare, registrare ingresso e uscita, annullare, inviare un passPOST /visitors e le relative azioni
visitors:screeningConfermare che la corrispondenza di un controllo su un visitatore è stata verificata: invia screening_reviewed, oppure approva una visita trattenuta da una corrispondenza. Disattivato per impostazione predefinita; ciò che fa la chiave viene registrato come azione della chiave, con il suo nomePOST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve
people:readLeggere l’elenco delle personeGET /people, /people/{id}
people:writeAggiungere, aggiornare, sincronizzare e rimuovere personePOST, PATCH e DELETE sotto /people
stays:readLeggere il contesto privato dei soggiorni in hotel e la cronologia delle correzioniGET /stays, /stays/{stay}
stays:writeAggiungere o aggiornare in modo idempotente il contesto di un soggiorno da un sistema alberghieroPOST /stays
school:readLeggere dalla segreteria scolastica gli ingressi in ritardo e le uscite anticipate degli alunniGET /school/movements
school:writeAggiungere o aggiornare gli alunni dal sistema informativo della scuolaPUT /school/pupils
queue:readLeggere le code, i ticket, gli orari prenotati, i messaggi, i dati dei sondaggi e il report di QueueGET sotto /queue
queue:writeAggiungere persone a una coda, chiamarle, chiudere i loro ticket, prenotare e annullare orari e scrivere alle persone in codaPOST sotto /queue
webhooks:manageIscrivere e rimuovere gli indirizzi webhook propri della chiave, per gli eventi i cui dati la chiave può leggereGET, POST e DELETE /webhooks

Gli oggetti, le richieste, le segnalazioni di smarrimento e le analisi richiedono vFound Lost & Found; i pacchi richiedono vFound Parcels; i ticket richiedono vFound Checkroom; le attrezzature richiedono vFound Equipment; le visite richiedono vFound Visitors; l’elenco delle persone richiede Parcels, Visitors o Equipment; i soggiorni in hotel richiedono Lost & Found o Parcels; la segreteria scolastica richiede Visitors con la segreteria scolastica attivata (risponde 404 finché è disattivata); le code e i ticket di coda richiedono vFound Queue. Un prodotto non aperto per la sede risponde 403.

Una chiave agisce come la persona che l’ha creata e smette di funzionare se quella persona non gestisce più la sede, a meno che la richiesta indichi un membro del team in X-Acting-User (vedi Agire per un membro del team). Le modifiche fatte con una chiave seguono le stesse regole, le stesse e-mail e lo stesso registro di controllo del banco, e ogni voce del registro di controllo riporta la chiave che ha fatto la modifica. Ogni chiave può fare 120 richieste al minuto. Indirizzo di base: https://vfound.io/api/v1. Gli elenchi restituiscono 25 record per pagina (fino a 100 con per_page) e accettano page; la maggior parte si filtra anche con updated_since (ISO 8601) e search, come indicato sotto.

Chiavi di prova

Una chiave creata come chiave di prova inizia con vf_test_ e può contenere solo queue:read e queue:write. Funziona su un’unica coda di prova con etichetta, Test line (sandbox) (coda 1, sportello 1), e in nessun altro posto: gli stessi indirizzi Queue di una chiave live per code, orari prenotabili, ticket, /queue/join, chiama il prossimo, chiama, servito, assente e rimuovi rispondono dalla coda di prova; ogni altro indirizzo risponde 403 con code: test_key. Una chiave di prova non legge né modifica mai una coda o un ticket reali e non invia e-mail, SMS, avvisi del browser né webhook. Una chiave di prova ignora Idempotency-Key: la stessa richiesta inviata due volte viene eseguita due volte. Le risposte contengono "sandbox": true e l’intestazione X-Vfound-Sandbox: 1. Una coda di prova contiene fino a 100 ticket per chiave, senza indirizzo e-mail, che vengono eliminati insieme alla chiave e dopo sette giorni. Usa nomi inventati.

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (qualsiasi valore univoco fino a 191 caratteri visibili, come un UUID) con una richiesta POST, PATCH o DELETE. Se la connessione cade e invii di nuovo la stessa richiesta con la stessa chiave entro 24 ore, vFound non ripete la modifica: risponde con la prima risposta e l’intestazione Idempotent-Replayed: true. La stessa chiave con una richiesta diversa viene rifiutata (422, idempotency_key_reused); una chiave la cui prima richiesta è ancora in corso risponde 409 (idempotency_in_progress). Dopo la cancellazione dei dati personali di chi ha trovato un oggetto o di chi ha fatto una richiesta, le risposte memorizzate per quella sede restituiscono invece 410, senza i dati cancellati; aggiorna il record invece di ripetere la vecchia scrittura con una nuova chiave. Gli errori del server non vengono conservati, quindi riprovare dopo uno di essi esegue di nuovo la richiesta. Anche una risposta che contiene qualcosa mostrato una sola volta, come il segreto di firma di POST /webhooks o un codice di abbinamento del chiosco, non viene mai memorizzata: un nuovo tentativo esegue di nuovo la richiesta, quindi controlla GET /webhooks prima di iscrivere due volte lo stesso indirizzo.

Agire per un membro del team

Un’app che il tuo team usa al banco, come un’app di postazione o di magazzino, può indicare per quale membro del team sta agendo. Invia X-Acting-User con l’e-mail di accesso della persona o il suo id utente. La persona deve essere, in questo momento, un membro attivo della sede della chiave. La richiesta viene poi eseguita come lei: la cronologia dell’oggetto e quella della richiesta riportano il nome di quella persona al posto del creatore della chiave, e il registro di controllo riporta il nome della persona, la chiave e il responsabile che ha creato la chiave. La persona può fare solo ciò che consentono sia gli ambiti della chiave sia il suo ruolo nella sede: chi ha il ruolo di visualizzatore può solo leggere, il personale può anche modificare oggetti, richieste, segnalazioni di smarrimento, pacchi, ticket di Checkroom, attrezzature, visite e soggiorni in hotel, e i titolari e i responsabili possono usare ogni ambito della chiave. Un nome che non è un membro attivo della sede viene rifiutato con 403 e acting_user_refused, con lo stesso messaggio che l’indirizzo esista o no; un ambito che il ruolo della persona non consente viene rifiutato con 403 e acting_user_role. I nuovi tentativi sicuri sono conservati per persona, quindi la risposta salvata di una persona non viene mai riproposta a un’altra. L’intestazione funziona solo con le chiavi della sede, non con un assistente collegato tramite accesso, che agisce già come la persona che l’ha collegato. vFound controlla che la persona indicata sia un membro attivo; non le chiede di accedere, quindi indica persone solo da un’app a cui il tuo team accede. Senza l’intestazione una chiave funziona esattamente come prima.

OpenAPI

L’intera API, ogni evento e ogni oggetto sono descritti in un file OpenAPI 3.1: vfound.io/openapi/v1.json. Importalo in Postman, Insomnia o nel tuo generatore di codice. Un test lo tiene allineato con l’API, quindi non elenca mai un endpoint che non esiste né ne omette uno che esiste.

Collegamenti già pronti con i sistemi operativi

I titolari e i responsabili configurano questi collegamenti con i fornitori, in sola lettura, in Impostazioni, Collegamenti, Sistemi operativi. Sono separati dall’API REST pubblica: il cliente crea e controlla la credenziale del fornitore, il collegamento deve superare una prova prima dell’attivazione, errori ripetuti mettono in pausa solo quel collegamento e il lavoro manuale resta disponibile.

SistemaChe cosa legge vFoundAree di vFound
CloudbedsContesto minimo di prenotazione e camera tramite una chiave della struttura controllata dal cliente e limitata a read:reservation. Fa parte di vFound Enterprise.Soggiorni privati per Lost & Found e Parcels
OfficeRnD FlexID del membro, nome, e-mail e stato attivo tramite flex.community.members.read, con un filtro facoltativo per sede.L’elenco condiviso delle persone per Parcels, Equipment e Visitors
Microsoft Entra IDID utente, nome visualizzato, e-mail e stato attivo tramite gli aggiornamenti delta di Microsoft Graph e User.Read.All, con il consenso dell’amministratore.L’elenco condiviso delle persone per Parcels, Equipment e Visitors

Sono collegamenti API configurati dal cliente, non dichiarazioni di certificazione del fornitore. Provare, attivare e sincronizzare un collegamento fanno parte di vFound Enterprise. In particolare, il collegamento con Entra non è un’app del Microsoft Marketplace.

Oracle OPERA Cloud non è disponibile. L’adattatore lato server, che in caso di dubbio resta chiuso, rimane disattivato finché non sono completati l’accesso a Oracle, l’approvazione dell’hotel, la configurazione esatta dell’ambiente e il collaudo in produzione. Non viene presentato come certificato né come validato dal cliente.

Oggetti

RichiestaChe cosa faAmbito
GET/itemsOggetti, prima quelli modificati più di recente. Filtri: status, search (parole nel titolo, nella descrizione, nella marca, nel colore o nei tag), updated_since (ISO 8601), page, per_page (fino a 100).items:read
GET/items/{id}Un oggetto in base al suo id.items:read
GET/categoriesI nomi delle categorie che un oggetto può usare.items:read
POST/itemsAggiunge un oggetto ritrovato. Viene pubblicato nella tua pagina per gli ospiti, attiva avvisi e abbinamento e compare nel tuo registro di controllo come uno aggiunto a mano.items:write
PATCH/items/{id}Modifica i dettagli o lo stato.items:write
GET/item-transfersOggetti ritrovati che questa sede ha inviato a un’altra sede dello stesso gruppo di clienti, o che riceve da essa, prima quelli in viaggio. Elenca anche le sedi a cui puoi inviare (destinations) e i contenitori di questa sede (bins). Filtri: status (in_transit, received o cancelled), direction (incoming o outgoing).items:read
POST/item-transfersInvia un oggetto in attesa del suo proprietario a un’altra sede del gruppo: item_id, destination_business_id e un note facoltativo. Solo per le chiavi create da un titolare o da un responsabile. L’oggetto esce dalla pagina per gli ospiti della sede che lo invia (se quella sede mostra i suoi oggetti ritrovati) e non può cambiare finché non arriva. Un oggetto con una richiesta qualsiasi resta dov’è.items:write
POST/item-transfers/{id}/cancelLa sede che invia riprende l’oggetto prima che venga ricevuto.items:write
POST/item-transfers/{id}/receiveLa sede ricevente conferma che è arrivato, con bin_id (obbligatorio quando la sede ha contenitori) o location. L’oggetto appartiene poi a questa sede, con le sue foto, la sua cronologia e le sue date, e viene confrontato con le segnalazioni di smarrimento di questa sede come un oggetto appena registrato.items:write

Strumenti del banco per Lost & Found e Checkroom

Le nuove impostazioni e-mail sono disattivate per impostazione predefinita. I conteggi delle scansioni e le differenze di chiusura servono solo alla verifica. P90 usa il 90° percentile con il metodo del rango più vicino sugli intervalli validi tra orari; i campioni assenti restituiscono null. La capacità in pezzi fisici avvisa ma non blocca mai la registrazione del deposito. Per i campi delle richieste vedi la descrizione OpenAPI. I modelli di configurazione e le impostazioni richiedono un titolare o un responsabile.

Metodo e percorsoChe cosa faAmbito
GET /lost-found/context-schemaLegge le definizioni dei campi di contesto privato con versione, senza i valori dei record. Basta uno qualsiasi degli ambiti di lettura elencati.items:read o lost_reports:read
GET /lost-found/desk-settingsLegge le impostazioni facoltative del banco.lost_reports:read
PUT /lost-found/desk-settingsSostituisce le impostazioni del banco; solo titolare o responsabile. Le nuove impostazioni di posta sono disattivate per impostazione predefinita.lost_reports:write
GET /checkroom/desk-settingsLegge le impostazioni facoltative del banco.checkroom:read
PUT /checkroom/desk-settingsSostituisce le impostazioni del banco; solo titolare o responsabile. Le nuove impostazioni di posta sono disattivate per impostazione predefinita.checkroom:write
GET /lost-found/countsElenca le ultime 30 sessioni di conteggio con scansione.items:read
POST /lost-found/countsRegistra gli identificativi degli oggetti in custodia per un conteggio solo di verifica; nessuna modifica della custodia.items:write
GET /lost-found/counts/{id}Legge un conteggio con i dati su oggetti mancanti, inattesi e non più presenti.items:read
POST /lost-found/counts/{id}/scanRegistra la scansione di un QR o di un’etichetta breve dell’oggetto; gli oggetti noti duplicati contano una sola volta.items:write
POST /lost-found/counts/{id}/finishTermina un conteggio senza modificare gli oggetti.items:write
GET /lost-found/queuesElenca le code di lavoro salvate dal creatore della chiave in questa sede.lost_reports:read
PUT /lost-found/queues/{id}Sostituisce una tua coda salvata; gli oggetti e le richieste sottostanti non cambiano.lost_reports:write
DELETE /lost-found/queues/{id}Elimina una tua coda salvata; gli oggetti e le richieste sottostanti non cambiano.lost_reports:write
POST /lost-found/queuesSalva una coda di lavoro predefinita con nome per il creatore della chiave.lost_reports:write
GET /lost-found/queues/{id}Legge i record attuali dietro una coda salvata. I trasferimenti in arrivo aprono la vista dei trasferimenti con permessi già esistente.lost_reports:read, items:read, claims:read
POST /lost-found/intake-reviewRestituisce suggerimenti deterministici su completezza e privacy; nessuna IA e nessuna modifica.items:read
GET /checkroom/templatesElenca i modelli di configurazione, che contengono solo impostazioni; solo responsabile.checkroom:read
PUT /checkroom/templates/{id}Sostituisce un modello di configurazione come responsabile; gli eventi, le postazioni e i ticket sottostanti non cambiano.checkroom:write
DELETE /checkroom/templates/{id}Elimina un modello di configurazione come responsabile; gli eventi, le postazioni e i ticket sottostanti non cambiano.checkroom:write
POST /checkroom/templatesSalva la configurazione delle postazioni di un evento senza ospiti né ticket; solo responsabile.checkroom:write
POST /checkroom/templates/{id}/applyCrea un nuovo evento e le postazioni; se ci sono conflitti con intervalli di numeri attivi, l’intera operazione viene rifiutata.checkroom:write

Contact center e custodia di Lost & Found

Le integrazioni gestite da persone possono creare una segnalazione di un ospite, registrare una verifica di proprietà, decidere su una richiesta e registrare il ritiro fisico. I nuovi ambiti di scrittura vanno selezionati in modo esplicito; le chiavi esistenti non li ottengono. Nessuna di queste scritture su richieste o sul destino degli oggetti è offerta come strumento MCP o di Ask vFound. La tua integrazione è responsabile di identificare e autorizzare il proprio operatore umano: il registro di controllo riporta il responsabile che ha creato la chiave e, quando l’integrazione invia X-Acting-User, anche il membro del team indicato, che vFound non autentica.

Metodo e percorsoChe cosa faAmbito
POST /lost-reportsInserimento da contact center: first_name, last_name, email, title e description; facoltativi phone, category id, colour_brand, place_lost, date_lost e language. Invia la normale conferma all’ospite con il link privato e avvia il monitoraggio di 90 giorni. Il consenso per il telefono non viene mai dedotto. Si applicano i limiti esistenti sulle segnalazioni aperte.lost_reports:write
PUT /lost-reports/{id}Modifica ciò che è stato smarrito usando l’impronta restituita da GET /lost-reports. Titolo e descrizione sono obbligatori. Se il percorso viene omesso, i dettagli salvati restano; se la raccolta è disattivata, le modifiche al contesto vengono rifiutate. Le modifiche ai contatti richiedono il flusso separato di contatto verificato.lost_reports:write
GET /lost-reports/{id}/matchesFino a 24 candidati attuali per testo e categoria, ciascuno con match.label, reason e source. I verdetti IA salvati e ancora validi usano cached_ai; altrimenti un suggerimento per parole chiave è etichettato come possible. Nessuna nuova chiamata al modello e nessuna decisione di proprietà.lost_reports:read e items:read
GET /items/{id}/matchesId e titolo delle segnalazioni corrispondenti, senza i dati di contatto di chi le ha fatte; fino a 24 corrispondenze tra le ultime 1,000 segnalazioni aperte. Stesse etichette di origine e nessuna nuova chiamata al modello.items:read e lost_reports:read
POST /claims/{id}/verificationRegistra verified (booleano) e method (distinctive_details, purchase_proof o staff_review). Attestazione umana, non autenticazione automatica di documenti; nessuna copia del documento né prove in testo libero. L’ultima verifica deve essere superata prima dell’accettazione tramite API.claims:write
POST /claims/{id}/decisionstatus: open, accepted, rejected, expired, ready_for_pickup, ready_for_shipment, shipped o handed_to_courier. Si applicano la sequenza di stati esistente e la seconda approvazione. I campi manuali della spedizione seguono le regole dell’area di lavoro. Con accepted, un return facoltativo (pickup o shipment) porta la richiesta a quella fase nella stessa chiamata, con un’unica e-mail al richiedente; quando un rilascio di alto valore richiede ancora la seconda approvazione, la richiesta resta accepted e return_notice ne indica il motivo (ripetere la stessa chiamata non cambia nulla). Un arranged_by facoltativo (site o owner) indica chi prenota un ritiro con corriere o una spedizione postale, e ogni risposta sulla richiesta lo mostra. Senza arranged_by, un indirizzo di consegna inviato in shipment (o uno che la richiesta ha già) significa che il tuo team la spedisce, come prima; altrimenti decide l’impostazione Lost & Found della sede. owner significa che il corriere del richiedente ritira l’oggetto: non viene chiesto alcun indirizzo, un indirizzo inviato con owner viene rifiutato e shipped viene rifiutato. Quando il suo corriere lo ritira, invia handed_to_courier con la società di corriere in shipment.carrier e il suo riferimento di prenotazione in shipment.tracking_number; la richiesta si chiude. Per cambiare chi lo prenota, sposta la richiesta a ready_for_pickup e poi di nuovo a ready_for_shipment con arranged_by.claims:write
POST /claims/{id}/release-approvalUn altro responsabile approva un rilascio accettato di alto valore, con gli stessi controlli dell’area di lavoro.claims:write
GET /claims/{id}/custodyVerifica e cronologia delle fasi, approvatore e nome e orario del ritiro. signature_recorded è un booleano; non vengono esposti né l’immagine della firma né l’indirizzo di file privati.claims:read
POST /claims/{id}/handoverRegistra il ritiro fisico da ready_for_pickup, con handover.name e un data URL PNG in handover.signature quando richiesto. Le chiamate ripetute su una richiesta già chiusa conservano la prima ricevuta.claims:write
POST /items/{id}/dispositionkind donated/disposed, recipient per una donazione, notes facoltativo. Si applicano la data di conservazione e i controlli sulle richieste in attesa o accettate. Restituisce la ricevuta numerata del lotto.items:write

Usa una Idempotency-Key per i nuovi tentativi di scrittura. Un record di verifica non autentica un documento d’identità né approva da solo la proprietà. La creazione iniziale di una segnalazione segue il flusso per gli ospiti, compresa l’IA attivata dalla sede; i GET dell’elenco delle corrispondenze usano solo verdetti memorizzati e ricerca testuale. Sono operazioni REST/OpenAPI generiche; nessuna installazione WSO2 né connettore nativo è stato certificato.

Aggiungere un oggetto

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}'

Campi: title e category sono obbligatori. Facoltativi: found_date, found_time (HH:MM), keep_until, location, description, colour, brand, tags, value_band (unknown, low, medium, high), notes (solo per il personale), photo (un data URL base64 fino a 8 MB) e photo_public. Le foto inviate tramite l’API non sono controllate dalla protezione della privacy di vFound AI, quindi imposta photo_public su false per ogni foto che mostra dati personali.

L’oggetto 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":"…"}

Lo stato è uno tra in_care, in_transit (in viaggio verso un’altra sede; transfer indica allora entrambe le sedi), claimed, expired, donated, disposed o trash. Un PATCH può impostare in_care, expired, donated, disposed o trash; le restituzioni a un ospite avvengono tramite le richieste.

Richieste

RichiestaChe cosa faAmbito
GET/claimsRichieste, prima quelle modificate più di recente. Filtri: status, updated_since, page, per_page.claims:read
GET/claims/{id}Una richiesta in base al suo riferimento.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":"…"}

Stato della richiesta: unread, open, accepted, awaiting_information, ready_for_pickup, ready_for_shipment, shipped, closed, rejected o expired (accettata ma mai ritirata). arranged_by indica chi prenota un ritiro con corriere o una spedizione postale: venue (il tuo team la spedisce) o owner (il corriere del richiedente la ritira); null quando la richiesta non ha una restituzione di questo tipo. I dati dei richiedenti sono dati personali: conservali solo per il tempo che ti serve.

Segnalazioni di smarrimento

GET/lost-reports elenca ciò che gli ospiti hanno segnalato di aver smarrito, con status (open o closed), i dati di contatto di chi ha segnalato, la lingua usata e l’eventuale link Find My condiviso. Ambito: lost_reports:read.

Analisi

GET/analytics?days=30 restituisce lo stesso riepilogo di Report: oggetti registrati e restituiti, tasso di restituzione, mediana dei giorni per la restituzione, dove sono finiti gli oggetti, categorie, punti critici, giorni più affollati, lavoro del team, l’andamento e i commenti degli ospiti. days è 7, 30, 90 o 365. Ambito: analytics:read.

Soggiorni in hotel

Il contesto del soggiorno è privato per la sede e volutamente minimo. Contiene un riferimento stabile del soggiorno, un riferimento facoltativo dell’ospite, il nome dell’ospite, arrivo e partenza, il fuso orario della fonte, la camera attuale, lo stato e gli orari della fonte. Non contiene mai tariffe, dati di pagamento, dati di fedeltà, documenti d’identità, preferenze o note di prenotazione non correlate.

RichiestaChe cosa faAmbito
GET/staysElenca i soggiorni. Filtri: search (ospite, riferimento stabile o camera attuale), state, source, page e per_page. Una corrispondenza di camera aiuta solo la navigazione; non suggerisce mai la proprietà.stays:read
GET/stays/{stay}Un soggiorno e la sua cronologia verificabile di fonte e correzioni.stays:read
POST/staysCrea o aggiorna il record della fonte API identificato da external_stay_ref. Invia source_updated_at; gli eventi in ritardo o ripetuti non più recenti di quello salvato vengono confermati senza sostituire i dati più recenti.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"}'

Oggetti e pacchi accettano stay_id e room_at_event facoltativi. Se la camera all’evento è omessa, vFound salva un’istantanea della camera attuale del soggiorno. Quell’istantanea non cambia dopo un cambio di camera; il record mostra anche la camera attuale, così il banco vede entrambe.

Parcels

RichiestaChe cosa faAmbito
GET/parcelsPacchi, prima quelli modificati più di recente. Filtri: status (waiting, collected o returned), search (destinatario, unità, numero di tracciamento, mittente o codice di ritiro), updated_since.parcels:read
GET/parcels/{id}Un pacco.parcels:read
POST/parcelsRegistra un pacco per recipient_email (abbinato al tuo elenco di persone) o recipient_name, con unit, carrier, tracking, sender e shelf facoltativi. La persona riceve per e-mail il suo codice di ritiro, a meno che notify sia false.parcels:write
POST/parcels/{id}/collectLo consegna: collected_by (obbligatorio) e una signature facoltativa (un data URL PNG).parcels:write
POST/parcels/{id}/returnLo restituisce al mittente, con una note facoltativa.parcels:write
POST/parcels/{id}/remindInvia al destinatario un promemoria per ritirarlo.parcels:write
POST/parcels/trackingNormalizza un numero di tracciamento e rileva UPS, FedEx, USPS, DHL, Amazon o un corriere internazionale S10. Un SSCC GS1 valido è accettato come tracciamento della spedizione; un identificativo di prodotto GS1 viene riconosciuto ma mai trattato come numero di pacco.parcels:read
GET/parcels/pickup-queuePersone che hanno dichiarato di essere al banco, con il numero dei loro pacchi e gli scaffali.parcels:read
POST/parcels/pickup-queue/{id}/serveSegna come servito un arrivo al banco.parcels:write
POST/parcels/bulk-remindInvia promemoria e-mail per un massimo di 200 pacchi in attesa selezionati.parcels:write
POST/parcels/bulk-returnRestituisce al mittente fino a 200 pacchi in attesa selezionati.parcels:write
GET/parcels/shelvesCapacità degli scaffali dei pacchi e occupazione attuale.parcels:read
POST/parcels/shelvesCrea uno scaffale o ne cambia la capacità.parcels:write
GET/parcels/analyticsVolume, mix di corrieri, tempo di ritiro, tasso di pacchi non ritirati e scaffali più occupati.parcels:read
GET/parcels/outgoingPacchi in uscita pronti per un corriere o già consegnati.parcels:read
POST/parcels/outgoingRegistra un pacco in uscita.parcels:write
POST/parcels/outgoing/{id}/handoffRegistra il corriere e la firma alla consegna.parcels:write
GET/parcels/roundsGiri di consegna e le loro fermate.parcels:read
POST/parcels/roundsCrea un giro per il campus o l’ufficio dai pacchi in attesa.parcels:write
POST/parcels/rounds/{round}/stops/{stop}/deliverCompleta una fermata con il nome del destinatario e la firma.parcels:write
GET/parcels/couriersCorrieri registrati tramite Visitors, con status in o 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":"…"}

Il codice di ritiro viene mostrato solo finché il pacco è in attesa. I dati dei destinatari sono dati personali: conservali solo per il tempo che ti serve.

Checkroom

RichiestaChe cosa faAmbito
GET/checkroom/ticketsTicket, prima quelli modificati più di recente, con status (pending, in, returned, left o moved), il numero, ciò che è stato consegnato, i piece_records etichettati singolarmente, i dati dell’ospite se forniti, la tariffa registrata al banco e gli orari. Filtri: status, search (ospite, camera, numero del ticket, etichetta del pezzo o codice del ticket), updated_since.checkroom:read
GET/checkroom/tickets/{id}Un ticket.checkroom:read
POST/checkroom/ticketsRegistra qualcosa in deposito e assegna il prossimo numero libero: kind (coat, bag, luggage o other, obbligatorio), pieces, piece_details facoltativo con un tipo e un luogo di conservazione per ogni pezzo, guest_name, guest_email, guest_room, collect_by per i bagagli, notes, fee_method (cash o card), station_id, event_id, storage_location, language e photo. La risposta contiene anche, una sola volta, guest_ticket (il codice e l’indirizzo privato del ticket), da mostrare come QR code o stampare per l’ospite; letture, elenchi e webhook non lo includono mai.checkroom:write
POST/checkroom/tickets/{id}/hand-backLo riconsegna dopo che il tuo sistema ha letto il ticket dell’ospite, con collected_by e signature facoltativi. Invia piece_ids per restituire i pezzi selezionati e lasciare aperti gli altri; omettilo per restituire ogni pezzo aperto. without_ticket registra che l’ospite ha perso il ticket e richiede allora collected_by e signature.checkroom:write
GET/checkroom/stationsElenca le postazioni di Checkroom della sede, gli intervalli di numeri e i luoghi di conservazione.checkroom:read
POST/checkroom/stationsCrea una postazione con un intervallo di numeri che non si sovrappone.checkroom:write
PUT/checkroom/stations/{id}Modifica una postazione, il suo intervallo di numeri, i luoghi di conservazione o lo stato attivo.checkroom:write
GET/checkroom/eventsElenca gli eventi di Checkroom recenti e futuri.checkroom:read
POST/checkroom/eventsCrea un evento con il volume previsto e le postazioni.checkroom:write
PUT/checkroom/events/{id}Modifica gli orari, la previsione o le postazioni di un evento.checkroom:write
GET/checkroom/exit-queueTicket i cui ospiti hanno chiesto al banco di preparare le loro cose.checkroom:read
POST/checkroom/tickets/{id}/readySegna come pronto un ticket in attesa e avvisa l’ospite.checkroom:write
GET/checkroom/reportVolume dei ticket, ore di punta, tempo di restituzione e tariffe per metodo e per personale.checkroom:read
GET/checkroom/exportScarica le righe del report di Checkroom come CSV a prova di formule.checkroom:read

Queue

Code, persone che aspettano al loro interno e sportelli a cui vengono chiamate. Ogni modifica esegue gli stessi passaggi del banco, con la stessa cronologia, come il creatore della chiave o il membro del team indicato in X-Acting-User. Un ticket non contiene mai l’e-mail dell’ospite né le sue risposte alle domande della coda.

RichiestaChe cosa faAmbito
GET/queue/linesCode con il loro stato attuale, persone in attesa e un’attesa stimata per chi si mette in coda adesso.queue:read
GET/queue/lines/{id}Una coda.queue:read
GET/queue/ticketsTicket di un giorno della sede (day, oggi per impostazione predefinita), in ordine di chiamata; filtra per line e status.queue:read
GET/queue/tickets/{id}Un ticket.queue:read
GET/queue/reportTicket, persone servite, assenze, persone che se ne sono andate, e mediana dei minuti di attesa e di servizio per gli ultimi days.queue:read
POST/queue/ticketsAggiunge una persona a una coda, come fa il banco.queue:write
POST/queue/call-nextChiama la persona successiva a uno sportello (counter_id). Due chiamanti non ricevono mai la stessa persona; data è null quando nessuno è in attesa.queue:write
POST/queue/tickets/{id}/callChiama una persona scelta a uno sportello.queue:write
POST/queue/tickets/{id}/servedSegna come servita la persona allo sportello.queue:write
POST/queue/tickets/{id}/no-showSegna come assente una persona chiamata che non si è presentata.queue:write
POST/queue/tickets/{id}/removeToglie una persona dalla coda.queue:write
GET/queue/bookingsOrari prenotati, i più vicini per primi, con from, to, line, status e paginazione. Mai l’e-mail della persona.queue:read
POST/queue/bookingsPrenota per una persona uno degli orari liberi della pagina degli orari prenotati di una coda (line_id, starts_at, email).queue:write
POST/queue/bookings/{id}/cancelAnnulla un orario prenotato; la persona riceve un’e-mail che le dice che il team l’ha annullato.queue:write
POST/queue/bookings/{id}/arrivedRegistra l’arrivo di una persona con orario prenotato; il suo ticket viene collocato in base all’orario prenotato.queue:write
POST/queue/tickets/{id}/arrivedSegna come presente una persona che si è messa in coda prima di arrivare.queue:write
GET/queue/tickets/{id}/messagesI messaggi tra una persona in coda e il team, dal più vecchio. La lettura segna come letti i messaggi della persona.queue:read
POST/queue/tickets/{id}/messagesScrive a una persona in coda (body, da 1 a 500 caratteri), come il membro del team della chiave.queue:write
GET/queue/surveyDati del sondaggio dopo il servizio: risposte, media, ogni valutazione, per coda, servizio, sportello e membro del team (la media di un membro del team compare a partire da 5 risposte). Mai i commenti.queue:read
GET/queue/performanceDati semplici per ogni membro del team negli stessi giorni del report. Nessun punteggio e nessuna classifica.queue:read
GET/queue/lines/{id}/slotsGli orari prenotabili aperti di una coda, come li offre la sua pagina di prenotazione.queue:read
POST/queue/joinPrende un numero per un ospite del tuo sito web, secondo le regole per gli ospiti (coda aperta, limiti, risposte obbligatorie e caselle di consenso). Invialo dal tuo server: la chiave sostituisce il captcha.queue:write
GET/queue/tickets/lookupTrova i ticket dal numero che l’ospite ha.queue:read
GET/queue/tickets/{id}/statusChe cosa mostra la pagina del ticket dell’ospite: posizione, stima e frase.queue:read
GET/queue/tickets/{id}/historyI passaggi di un ticket. Chi ha fatto ciascuno è team, guest, api (un ingresso in coda tramite chiave) o system (fatto automaticamente, come l’assenza automatica), mai un nome.queue:read
GET/queue/customers/historyVisite di chi ha chiesto di essere ricordato, trovato tramite e-mail, finché la sede ha il riconoscimento attivo. Dice a chi ha la chiave se un indirizzo e-mail appartiene a un visitatore ricordato.queue:read
GET/queue/insightsConteggi per gli stessi giorni del report: persone che se ne sono andate prima di essere chiamate, persone con prenotazione e senza appuntamento, quota chiamata entro l’obiettivo di attesa per coda e settimana, e ore di punta delle settimane passate. Solo conteggi; mai un nome né una risposta.queue:read
GET/queue/report-dataI ticket di Queue come li legge il generatore di report (fields[], limit fino a 1000, offset), per strumenti di BI. Il nome dell’ospite non è mai incluso.queue:read

Equipment

RichiestaChe cosa faAmbito
GET/loansAttrezzature consegnate, prima quelle modificate più di recente, con status (out, returned o lost), se è overdue, l’articolo, l’utilizzatore e gli orari. Filtri: status (out, returned, lost o overdue), search (nome dell’utilizzatore, e-mail o riferimento), updated_since.loans:read
GET/loans/{id}Una consegna.loans:read
POST/loansConsegna qualcosa: item_id o item_code (il codice sulla sua etichetta, o il link contenuto nel suo QR code), borrower_name (obbligatorio), person_id facoltativo per collegare l’elenco delle persone, borrower_email per una ricevuta, borrower_reference, due_at, note, language e signature.loans:write
POST/loans/{id}/extendDà più tempo: un nuovo due_at. L’utilizzatore riceve per e-mail il nuovo orario.loans:write
POST/loans/{id}/returnLo riprende, con condition facoltativa (good, damaged o incomplete), note e set_aside per mettere da parte l’articolo per la riparazione.loans:write
POST/loans/returnsRiprende più articoli insieme: loan_ids (da 1 a 50), con gli stessi condition, note e set_aside facoltativi per tutti. Tutto o niente: se uno è già rientrato o non viene trovato, non cambia nulla. Un utilizzatore con un indirizzo e-mail riceve una ricevuta per ogni consegna, con l’elenco di tutto ciò che è rientrato, e ogni consegna invia il proprio evento loan.returned.loans:write
GET/loans/itemsTutto ciò che il banco consegna, per nome. Filtri: status (available, out, repair o retired), search (nome, codice inventario o codice etichetta), updated_since.loans:read
GET/loans/items/{id}Un articolo, con il link contenuto nel QR code della sua etichetta.loans:read
GET/loans/items/{id}/ticketsTicket inviati al Jira, Zendesk o ServiceNow della sede per questo articolo (beta), con lo stato letto per ultimo.loans:read
POST/loans/itemsAggiunge attrezzature: name (obbligatorio), category, tag, location, notes, loan_hours (per quante ore di solito viene consegnato), photo, product e variant (le unità dello stesso prodotto e variante possono essere prenotate come una sola) e copies per aggiungere fino a 50 articoli identici, numerati.loans:write
PATCH/loans/items/{id}Ne modifica i dettagli, oppure imposta status su available, repair o retired. product e variant ne cambiano la famiglia di prodotti; cleaning_status needs_cleaning lo segna come in attesa di pulizia e null lo segna come pulito. Gli articoli mostrano product, variant, cleaning_status e cleaning_since.loans:write
GET/loans/items/{id}/tagSe un tag NFC o RFID è collegato e le ultime quattro cifre esadecimali del suo numero di serie.loans:read
PUT/loans/items/{id}/tagCollega un tag tramite il suo numero di serie, come lo legge un telefono o come lo digita un lettore tipo tastiera (esadecimale, esadecimale invertito o decimale); sostituisce l’eventuale tag che l’articolo aveva.loans:write
DELETE/loans/items/{id}/tagRimuove il tag dell’articolo.loans:write
POST/loans/checkoutsConsegna da uno a 50 articoli in un’unica consegna atomica, oppure consegna un kit salvato. Accetta una persona, un orario di scadenza, una nota e una firma facoltativa, e righe di scorta (stock) consegnate con la stessa ricevuta, elencate di nuovo in stock. custom_values imposta gli attributi personalizzati della sede per la consegna.loans:write
GET/loans/kitsGruppi salvati di attrezzature che di solito vengono consegnate insieme.loans:read
POST/loans/kitsSalva un kit di almeno due parti in tutto: item_ids indicati per nome, lines (un numero di una categoria) e child_kit_ids (kit al suo interno, fino a tre livelli), stock_lines (scorta contata consegnata insieme, mai riservata per una prenotazione) e, facoltativamente, locked perché i suoi articoli indicati escano solo insieme.loans:write
PUT/loans/kits/{id}Modifica un kit salvato e i suoi articoli.loans:write
GET/loans/trainingsLe formazioni che una categoria o un articolo può richiedere prima che qualcuno lo ritiri (da impostare in Equipment, Criteri, Formazione).loans:read
GET/loans/trainings/{id}/holdersChi ha una formazione, da quando e fino a quando, e se è scaduta.loans:read
POST/loans/trainings/{id}/holdersAssegna una formazione a una persona dell’elenco delle persone, o la rinnova, con un documento di prova facoltativo.loans:write
DELETE/loans/trainings/{id}/holders/{person}Toglie una formazione a una persona, insieme al suo documento di prova.loans:write
GET/loans/borrower-typesI tipi di utilizzatore: il limite di articoli di ciascuno, la durata abituale e le categorie che le sue persone vedono e ritirano (da impostare in Equipment, Criteri, «Tipi di utente»). Un limite o una durata vuoti significano che vale quello della sede.loans:read
GET/loans/borrower-types/{id}/membersChi ha un tipo di utilizzatore.loans:read
POST/loans/borrower-types/{id}/membersAssegna un tipo di utilizzatore a persone dell’elenco delle persone (fino a 500 alla volta).loans:write
PUT/loans/borrower-types/{id}/members/{person}Modifica l’appartenenza di una persona a un tipo di utilizzatore: il giorno di inizio, il giorno di fine (dopo il quale vede ancora ciò che il tipo mostra ma non può riservarlo né ritirarlo) e una nota su dove è stato incassato un addebito. vFound non incassa alcun pagamento.loans:write
DELETE/loans/borrower-types/{id}/members/{person}Toglie un tipo di utilizzatore a una persona.loans:write
GET/loans/creditsCrediti di prenotazione assegnati di recente e il saldo di una persona. I crediti sono un conteggio che le prenotazioni consumano, mai denaro.loans:read
POST/loans/creditsAssegna crediti di prenotazione a una persona, o ne toglie con un numero negativo (titolari e responsabili).loans:write
GET/loans/holdsBlocchi attivi sul ritiro: finché uno dura, alla persona non viene consegnato nulla e non può prenotare.loans:read
POST/loans/holdsMette un blocco sul ritiro di una persona, con un motivo facoltativo (conservato per il team, mai nell’e-mail), un orario di fine e un’e-mail alla persona.loans:write
POST/loans/holds/{id}/liftToglie un blocco.loans:write
GET/loans/spacesStanze, scrivanie, posti auto e altri spazi che la sede prenota per un certo tempo, filtrabili facoltativamente per type. Ognuno è un articolo di tipo space, mai consegnato.loans:read
POST/loans/spacesAggiunge una stanza o uno spazio con il suo tipo, quante persone può ospitare e dove si trova.loans:write
PUT/loans/spaces/{id}Modifica una stanza o uno spazio.loans:write
GET/loans/spaces/availabilityOgni stanza o spazio con le sue prenotazioni aperte tra from e to (fino a 31 giorni), con il nome dell’utilizzatore, quante persone vengono e le eventuali istruzioni di allestimento.loans:read
POST/loans/spaces/{id}/bookPrenota una stanza o uno spazio per una persona e un orario, da solo o con attrezzature (tutto o niente), con istruzioni di allestimento per il team.loans:write
POST/loans/reservation-groups/{id}/partsAggiunge un articolo, o uno di una categoria, a una prenotazione di kit o carrello, controllato come una nuova prenotazione. Rifiutato per un kit bloccato. Una parte di una categoria coperta dal modulo di rischio della sede richiede risk_answers, e la valutazione della prenotazione attende una nuova revisione.loans:write
POST/loans/reservations/{id}/remove-partToglie una parte da una prenotazione di kit o carrello; l’ultima parte viene annullata insieme alla prenotazione.loans:write
GET/loans/placesI luoghi annidati della sede: edifici, stanze, scaffali, cantieri e camion. Il place_id di un articolo stabilisce dove si trova e riempie i suoi location e sub_location.loans:read
GET/loans/category-treeLe categorie di attrezzature raggruppate in un albero, prima le categorie genitore. Le regole e le prenotazioni si applicano ancora alla categoria propria dell’articolo.loans:read
GET/loans/asset-modelsModelli da cui si creano i nuovi articoli. Invia asset_model_id in POST /loans/items per riempire ogni dettaglio lasciato vuoto.loans:read
GET/loans/items/{id}/linksI collegamenti di un articolo con altri articoli della stessa sede: funziona con, un’alternativa, sostituisce.loans:read
POST/loans/items/{id}/linksCollega un articolo a un altro della stessa sede, con una nota.loans:write
DELETE/loans/items/{id}/links/{link}Rimuove un collegamento da entrambi gli articoli.loans:write
POST/loans/kits/{id}/moveSposta un kit in un luogo della sede: ogni articolo indicato al suo interno, e nei kit al suo interno, va lì in una volta sola (titolari e responsabili).loans:write
GET/loans/items/{id}/meter-readingsLetture del contatore inserite per un articolo, le più recenti per prime.loans:read
POST/loans/items/{id}/meter-readingsRegistra una lettura del contatore. Un piano di manutenzione con every_meter scade quando il contatore ha percorso quel valore; le letture possono solo salire.loans:write
GET/loans/contractsContratti con i fornitori collegati agli articoli che coprono (titolari e responsabili).loans:read
GET/loans/resaleArticoli messi in vendita con il prezzo richiesto e il valore contabile (titolari e responsabili). Solo un elenco: nulla viene pubblicizzato né venduto.loans:read
GET/loans/pointsPunti di ritiro e di riconsegna che una prenotazione può indicare.loans:read
POST/loans/pointsAggiunge un punto (titolari e responsabili). Una prenotazione ne indica uno da cui ritirare e uno a cui restituire con pickup_point_id e dropoff_point_id.loans:write
PUT/loans/points/{id}Modifica un punto o lo disattiva.loans:write
GET/loans/projectsProgetti a cui può appartenere una prenotazione. Nulla viene ritirato per un progetto finché non è approvato.loans:read
POST/loans/projectsAggiunge un progetto (in attesa di approvazione).loans:write
POST/loans/projects/{id}/decisionApprova o rifiuta un progetto (titolari e responsabili).loans:write
GET/loans/risk-assessmentsValutazioni dei rischi in attesa di revisione (o per status), con le risposte dell’utilizzatore.loans:read
POST/loans/risk-assessments/{id}/reviewApprova o rifiuta una valutazione dei rischi (titolari e responsabili). Un rifiuto annulla la prenotazione.loans:write
POST/loans/reservation-seriesPrenota un articolo, una categoria o una stanza o uno spazio ogni giorno o ogni settimana (repeat: frequency, every, weekdays, count o until, skip_conflicts). Ogni volta segue le regole di prenotazione e conta le volte precedenti; non viene prenotato nulla se una è occupata, a meno che skip_conflicts sia attivo. Al massimo 52 volte, entro un anno.loans:write
POST/loans/reservations/{id}/moveSposta una prenotazione, con ogni parte di un kit o carrello prenotata insieme, a nuovi orari o a un altro articolo della stessa categoria. Controllata di nuovo come una nuova prenotazione; tutto o niente.loans:write
GET/loans/waitlistPersone in attesa di un orario che è stato preso, per status (waiting per impostazione predefinita).loans:read
POST/loans/waitlistAggiunge una persona alla lista d’attesa per un articolo, una categoria o uno spazio e un orario. Quando si libera, la prima persona il cui orario ora combacia viene prenotata e riceve un’e-mail.loans:write
POST/loans/waitlist/{id}/cancelToglie una persona dalla lista d’attesa.loans:write
GET/loans/feesIl registro degli addebiti, i più recenti per primi (filtra per party_key, kind, status, billing_code, from, to), con le impostazioni degli addebiti della sede e tutti quelli che devono qualcosa o hanno una cauzione custodita. Gli importi sono interi nell’unità minore della valuta. vFound registra gli addebiti; non elabora mai un pagamento.loans:read
GET/loans/fees/partyUn utilizzatore (person_id o party_key): quanto deve per valuta, cauzioni custodite, voci e fatture.loans:read
GET/loans/fees/billing-codesAddebitato, condonato, saldato e ancora dovuto per codice di fatturazione e valuta in un periodo; format=csv per un CSV.loans:read
POST/loans/fees/chargesRegistra un addebito per danni, sostituzione o altro, oppure un addebito con prezzo tramite fee_template_id. Si applica l’imposta della sede, a meno che taxable sia false.loans:write
POST/loans/fees/paymentsRegistra denaro che la sede ha incassato direttamente (contanti, il proprio terminale per carte, un bonifico). Salda per primi gli addebiti aperti più vecchi.loans:write
POST/loans/fees/depositsRegistra una cauzione incassata dalla sede; custodita finché non viene restituita o incamerata.loans:write
POST/loans/fees/deposits/{id}/returnRestituisce una cauzione custodita.loans:write
POST/loans/fees/deposits/{id}/keepIncamera una cauzione custodita, o parte di essa (titolari e responsabili, con un motivo); la parte incamerata conta come pagamento.loans:write
POST/loans/fees/{id}/waiveCondona ciò che un addebito richiede ancora (titolari e responsabili, con un motivo).loans:write
POST/loans/fees/{id}/voidAnnulla un pagamento registrato per errore (titolari e responsabili, con un motivo). Annullare il pagamento generato da una cauzione incamerata rimette quell’importo in custodia come cauzione.loans:write
GET/loans/{id}/feesCiò che viene proposto al banco per una consegna rientrata: la multa per ritardo non ancora registrata, il valore di sostituzione se perso o danneggiato, le cauzioni custodite.loans:read
POST/loans/{id}/late-fineAggiunge la multa per ritardo per una consegna rientrata in ritardo, calcolata da quando è rientrata. Una volta per consegna.loans:write
GET/loans/invoicesFatture, prima il numero più recente.loans:read
POST/loans/invoicesEmette una fattura numerata per gli addebiti aperti di un utilizzatore in una valuta.loans:write
POST/loans/invoices/{id}/voidAnnulla una fattura (titolari e responsabili, con un motivo); reissue mette i suoi addebiti aperti su una nuova che la sostituisce.loans:write
GET/loans/reservationsPrenotazioni per orario di inizio, filtrabili facoltativamente per status o from.loans:read
POST/loans/reservationsRiserva un articolo specifico o un articolo di una categoria per una persona e una fascia oraria. custom_values imposta gli attributi personalizzati della sede per la prenotazione.loans:write
POST/loans/reservations/{id}/approveApprova una prenotazione in attesa di revisione. Quando la sede ha fasi di approvazione, una chiave firma una fase solo per il membro del team indicato in X-Acting-User, un collegamento con un assistente non ne firma mai una e nessuno firma una fase di una prenotazione fatta da sé (approval_not_yours). La prenotazione in presenza di un conflitto segue la stessa regola.loans:write
POST/loans/reservations/{id}/cancelAnnulla una prenotazione in attesa, approvata o pronta.loans:write
POST/loans/reservations/{id}/pickupConsegna in modo atomico l’articolo riservato e chiude la prenotazione come ritirata.loans:write
POST/loans/reservation-groupsRiserva un kit (kit_id) o un carrello (items: un articolo, o una categoria e una quantità, per riga) per una persona e una fascia oraria: tutte le parti o nessuna. Approvare, annullare o ritirare una parte qualsiasi agisce su ogni parte aperta.loans:write
GET/loans/downtimesFinestre con data in cui un articolo non può essere prenotato né consegnato e che non sono ancora finite (item_id limita a un solo articolo).loans:read
POST/loans/downtimesAggiunge una finestra a un articolo: loan_item_id, starts_at, ends_at e un reason facoltativo. Rifiutata finché una prenotazione o una consegna tiene l’articolo per una parte di quel tempo.loans:write
DELETE/loans/downtimes/{id}Rimuove una finestra.loans:write
GET/loans/extra-values/{type}/{id}Gli attributi personalizzati della sede per un utilizzatore (person), una reservation o un checkout, con i campi definiti per quel tipo di record.loans:read
PUT/loans/extra-values/{type}/{id}Imposta quegli attributi, controllati rispetto ai campi della sede e alle loro condizioni di visualizzazione.loans:write
GET/loans/closuresGiorni in cui il banco delle attrezzature è chiuso e che non sono ancora finiti.loans:read
POST/loans/closuresAggiunge una chiusura: date starts_on e ends_on nel fuso orario della sede, fino a 366 giorni. note facoltativa resta interna; public_message (fino a 300 caratteri) viene mostrato agli utilizzatori. Le note esistenti non vengono mai copiate nel messaggio per gli utilizzatori.loans:write
DELETE/loans/closures/{id}Rimuove una chiusura.loans:write
GET/loans/rulesImpostazioni predefinite della sede, regole per categoria su durata, limiti, blocchi per ritardo, approvazione e regole di prenotazione (intervalli tra una prenotazione e l’altra, preavviso minimo, quanto in anticipo) e chiusure.loans:read
POST/loans/rulesCrea o sostituisce la regola di una categoria. I campi delle regole di prenotazione omessi mantengono i valori salvati.loans:write
GET/loans/timelineControlli della capacità di articoli e categorie a giornata intera. Date from e until obbligatorie, inclusive e nell’ora locale della sede, al massimo 31 giorni da oggi fino al prossimo anno; facoltativi group=item|category, item_id, category esatta, page (50 righe). Le celle sono true, false o null (incerto). Giorni adiacenti non garantiscono una prenotazione continua.loans:read
GET/loans/warrantiesDate di garanzia registrate; filter=soon|expired|all, category esatta, page (50 righe). Soon comprende da oggi fino a 30 giorni avanti. L’adesione ai promemoria personali si trova nell’area di lavoro.loans:read
GET/loans/utilizationOre trascorse per ogni bene dalla cronologia di stato registrata. Date from e until obbligatorie, inclusive e nell’ora locale della sede, entro gli ultimi 365 giorni, limitate a ora; facoltativi item_id, category esatta, format=csv. Il JSON dà i secondi esatti; le ore del CSV usano sei decimali. Disponibile comprende il tempo in uso; il tempo in riparazione, in manutenzione e altro tempo non disponibile sono esclusi. L’inattività precedente è sconosciuta. I totali tornano con le righe dei beni.loans:read
GET/loans/maintenanceCronologia di manutenzione, taratura, prova di sicurezza, ispezione, pulizia, riparazione e note; filtra per articolo, lavori in arrivo o ordini di lavoro (aperti o tutti) e il loro tecnico.loans:read
POST/loans/maintenanceRegistra la manutenzione e la prossima scadenza per un articolo. Con plan_id, il lavoro svolto per un piano ripetuto, che avvia il suo prossimo ciclo.loans:write
GET/loans/service-plansPiani ricorrenti di manutenzione, taratura, prova di sicurezza, ispezione e pulizia, con l’indicazione se ciascuno scade per data, per ore di consegna o per numero di consegne.loans:read
POST/loans/service-plansAggiunge un piano ricorrente a un articolo (titolari e responsabili).loans:write
PUT/loans/maintenance/{id}Modifica o chiude un ordine di lavoro: stato, tecnico, fornitore, costo e, per done, il risultato e se l’articolo torna in servizio.loans:write
GET/loans/maintenance/costsCosto di manutenzione, riparazione e pulizia per articolo, dalle voci concluse e dagli ordini di lavoro completati.loans:read
GET/loans/items/{id}/lifecycleIl record di acquisto, ammortamento, assicurazione e dismissione di un articolo, con il suo valore di oggi (titolari e responsabili).loans:read
PUT/loans/items/{id}/lifecycleSalva il prezzo, la data, il fornitore e l’ordine di acquisto, il metodo di ammortamento (a quote costanti o a quote decrescenti), la vita utile e il valore residuo, e l’assicurazione (titolari e responsabili).loans:write
POST/loans/items/{id}/disposeRegistra come è uscito un articolo (venduto, rottamato, donato, riciclato, perso o rubato); viene dismesso e le sue prenotazioni aperte e i suoi ordini di lavoro vengono annullati.loans:write
DELETE/loans/items/{id}/disposeAnnulla una dismissione fatta per errore; l’articolo torna disponibile.loans:write
GET/loans/valuationIl valore delle attrezzature a una data, al centesimo, con i totali di ciò che è ancora in possesso (titolari e responsabili).loans:read
POST/loans/service-plans/importControlla o aggiunge piani da un CSV con le colonne documentate, indicando le attrezzature con il codice inventario (titolari e responsabili).loans:write
POST/loans/maintenance/work-orders/importControlla o aggiunge ordini di lavoro aperti da un CSV con le colonne documentate (titolari e responsabili).loans:write
GET/loans/maintenance/plannerLavori programmati e ordini di lavoro aperti per giorno della sede fino a 62 giorni, facoltativamente per un solo tecnico.loans:read
GET/loans/fundingChe cosa ha acquistato ciascun fondo, contributo o centro di costo e quale lavoro gli è stato addebitato, filtrabile per fondo e date (titolari e responsabili). Solo un record: vFound non incassa alcun pagamento.loans:read
GET/loans/substancesIl registro delle sostanze pericolose: sostanza, luogo, classi di pericolo e date di revisione. Un record di ciò che dichiara la sede; vFound non dà alcun consiglio sulla sicurezza.loans:read
POST/loans/substancesAggiunge una sostanza, con la sua scheda di sicurezza in PDF o foto (titolari e responsabili).loans:write
PUT/loans/substances/{id}Modifica una sostanza o ne sostituisce la scheda (titolari e responsabili).loans:write
DELETE/loans/substances/{id}Rimuove una sostanza e la scheda di sicurezza conservata (titolari e responsabili).loans:write
GET/loans/licencesLicenze delle attrezzature della sede con utenze, data di fine e articoli su cui sono installate (titolari e responsabili). Non viene conservata alcuna chiave di licenza.loans:read
POST/loans/licencesAggiunge una licenza (titolari e responsabili).loans:write
PUT/loans/licences/{id}Modifica una licenza e dove è installata.loans:write
DELETE/loans/licences/{id}Rimuove una licenza.loans:write
GET/loans/expiriesAssicurazioni e licenze in scadenza o già scadute (titolari e responsabili).loans:read
GET/loans/stocktakesInventari recenti delle attrezzature con i conteggi di scansioni e di mancanti.loans:read
POST/loans/stocktakesAvvia un inventario aperto per la sede, per tutto, per un luogo, una categoria o un kit, o per ciò che ha in custodia una persona (custodian_id), facoltativamente assegnato a un membro del team (assigned_to).loans:write
POST/loans/stocktakes/{id}/scanScansiona un’etichetta di attrezzatura, un codice inventario o un numero di serie nell’inventario aperto.loans:write
POST/loans/stocktakes/{id}/scan-manyConta fino a 2,000 codici in una volta (un lettore RFID di tipo tastiera o un elenco); ognuno conta una volta e i codici senza corrispondenza vengono restituiti.loans:write
PUT/loans/stocktakes/{id}/assignAssegna l’inventario aperto a un membro del team perché lo conti (assigned_to), o a nessuno (null).loans:write
POST/loans/stocktakes/{id}/finishTermina l’inventario e restituisce l’elenco degli articoli mancanti.loans:write
GET/loans/stocktake-schedulesInventari che si aprono da soli, una volta o ripetuti.loans:read
POST/loans/stocktake-schedulesProgramma un inventario, una volta, ogni settimana, ogni mese, ogni tre mesi o ogni anno, all’ora del giorno della sede.loans:write
PATCH/loans/stocktake-schedules/{id}Modifica, sospende o riprende un programma.loans:write
DELETE/loans/stocktake-schedules/{id}Elimina un programma; gli inventari che ha aperto restano.loans:write
GET/loans/last-seenDove ogni articolo è stato scansionato per ultimo, quando la sede salva le posizioni delle scansioni (solo membri del team che hanno accettato; mai da una chiave).loans:read
GET/loans/transfersTrasferimenti di attrezzature in entrata e in uscita per questa sede.loans:read
POST/loans/transfersPrepara le attrezzature per un’altra sede autorizzata dello stesso gruppo di clienti.loans:write
POST/loans/transfers/{id}/sendRegistra che le attrezzature preparate hanno lasciato la sede di origine.loans:write
POST/loans/transfers/{id}/receiveRiceve le attrezzature nella sede di destinazione con il loro luogo e il loro stato all’arrivo.loans:write
POST/loans/transfers/{id}/cancelAnnulla un trasferimento preparato prima della spedizione.loans:write
POST/loans/transfers/{id}/rejectRifiuta un trasferimento preparato nella sede di destinazione prima della spedizione.loans:write
POST/loans/transfers/{id}/exceptionRegistra un problema mentre le attrezzature sono in transito.loans:write
POST/loans/importAnteprima o importazione fino a 5,000 righe CSV con le intestazioni di vFound, Snipe-IT, Sortly o Cheqroom.loans:write

Visitors

RichiestaChe cosa faAmbito
GET/visitorsVisite, prima quelle modificate più di recente, con status (expected, in, out, cancelled o missed), il visitatore, il referente, il codice del pass finché è valido e gli orari. Filtri: status, search (visitatore, azienda, referente o codice del pass), updated_since.visitors:read
GET/visitors/{id}Una visita.visitors:read
POST/visitorsInvita un visitatore o ne registra l’ingresso. Accetta i campi del visitatore, del referente e dell’orario più visitor_type_id, le risposte, le date di validità e una ricorrenza giornaliera o nei giorni feriali.visitors:write
POST/visitors/{id}/sign-inRegistra l’ingresso di un visitatore atteso; il referente viene avvisato. Invia answers per un membro del gruppo il cui tipo ha domande obbligatorie, e id_expires_on con identity_checked quando la sede registra la data di scadenza di un documento fisico. La visita contiene poi id_expires_on e id_expired.visitors:write
POST/visitors/{id}/group/sign-inRegistra l’ingresso di tutte le persone del gruppo della visita attese oggi, con un’unica e-mail al referente; chi ha bisogno di una propria foto, di un controllo del documento, di una firma, di risposte o di condizioni è elencato in skipped.visitors:write
POST/visitors/{id}/sign-outNe registra l’uscita.visitors:write
POST/visitors/{id}/cancelAnnulla un invito.visitors:write
POST/visitors/{id}/send-passInvia di nuovo il pass per e-mail.visitors:write
POST/visitors/{id}/approveApprova una visita in attesa e invia il pass.visitors:write
POST/visitors/{id}/denyRifiuta una visita in attesa.visitors:write
GET/visitors/{id}/badgeScarica il badge stampabile dal browser. Scegli size 4x3, brother o dymo.visitors:read
GET/visitors/{id}/cardSe la visita ha una tessera RFID e gli ultimi quattro caratteri (mai il numero). Disattivato finché la sede non attiva Tessere e portachiavi.visitors:read
POST/visitors/{id}/cardAssegna a una visita attesa o già registrata una tessera tramite il suo numero; un numero è attivo su una sola visita alla volta.visitors:write
DELETE/visitors/{id}/cardRitira la tessera.visitors:write
GET/visitors/{id}/assetsGli oggetti consegnati alla visita, digitati a mano.visitors:read
POST/visitors/{id}/assetsRegistra un oggetto consegnato alla visita, con un tag facoltativo.visitors:write
POST/visitors/{id}/assets/{asset}/returnSegna un oggetto come restituito.visitors:write
GET/visitor-assets/not-returnedOggetti consegnati ai visitatori e non ancora restituiti, i più recenti per primi.visitors:read
GET/visitors/{id}/fast-trackSe la visita ha un codice di accesso rapido attivo, fino a quando e quante volte è stato usato (mai il codice, che vede solo il visitatore).visitors:read
POST/visitors/{id}/fast-trackAssegna a un visitatore che torna un codice di accesso rapido che dura days (da 1 a 365).visitors:write
DELETE/visitors/{id}/fast-trackRitira il codice.visitors:write
GET/visitor-typesElenca i tipi di visitatore con le loro domande, condizioni, badge, approvazioni e conservazione dei dati (retention_days è null quando il tipo segue l’impostazione predefinita della sede).visitors:read
POST/visitor-typesCrea un tipo di visitatore.visitors:write
PATCH/visitor-types/{id}Modifica i campi del tipo di visitatore che invii.visitors:write
DELETE/visitor-types/{id}Disattiva un tipo di visitatore senza modificare le visite precedenti.visitors:write
GET/visitor-roll-callOttiene l’ultimo appello e i suoi conteggi in tempo reale. Un appello in corso aggiunge chiunque abbia registrato l’ingresso dopo il suo inizio; uno lasciato in corso per 6 ore viene chiuso.visitors:read
POST/visitor-roll-callAvvia un appello, includendo facoltativamente i visitatori attesi oggi e chi è in attesa di approvazione.visitors:write
PATCH/visitor-roll-call/entries/{entry}Segna una voce come al sicuro o mancante.visitors:write
POST/visitor-roll-call/{id}/finishTermina l’appello attivo e ne conserva il report.visitors:write
GET/staff-attendanceElenca le presenze del personale in un intervallo di date secondo l’orologio della sede (oggi per impostazione predefinita, al massimo 366 giorni), oppure, con open=true, solo le persone presenti in questo momento. Non include mai l’e-mail della persona.visitors:read
POST/staff-attendanceRegistra l’ingresso (mode office o remote) o l’uscita di una persona dell’elenco del personale, con le stesse regole del banco. Richiede che la registrazione dei dipendenti sia attiva nella sede.visitors:write
POST/staff-presenceInvia fino a 50 eventi di presenza (in, out o muster) dal tuo sistema di badge, di timbratura o Wi-Fi, ciascuno con una persona dell’elenco del personale indicata per riferimento, ID esterno o e-mail. Richiede che la registrazione dei dipendenti e il flusso delle presenze siano attivi nella sede. Risponde che cosa è successo per ogni evento, mai a chi.visitors:write
POST/visitors/{id}/cateringCrea, modifica o (senza voci) rimuove la richiesta di catering di una visita attesa o già registrata, tra le opzioni elencate dalla sede. Invia un’e-mail alla casella catering della sede; vFound non ordina nulla e non incassa alcun pagamento. Richiede che il catering sia attivo nella sede.visitors:write
GET/workplace/spacesElenca le scrivanie, le sale riunioni e i posti auto che le persone possono prenotare nella sede.visitors:read
GET/workplace/freeTrova gli spazi liberi per un intero periodo (al massimo 7 giorni), escludendo una scrivania riservata a un’altra persona.visitors:read
GET/workplace/bookingsElenca le prenotazioni di scrivanie, sale e posti auto in un intervallo di al massimo 31 giorni. Non include mai l’e-mail della persona.visitors:read
POST/workplace/bookingsPrenota uno spazio per una persona, una volta o come prenotazione ripetuta (ogni giorno o ogni settimana, fino a 52 volte, tutte o nessuna), con le regole di prenotazione di Equipment.visitors:write
POST/workplace/bookings/{id}/cancelAnnulla una prenotazione, oppure con scope following o series i suoi orari successivi.visitors:write
POST/workplace/bookings/{id}/check-inRegistra la presenza per una prenotazione, da 15 minuti prima dell’inizio fino alla fine.visitors:write
POST/visitors/{id}/roomPrenota una sala riunioni per una visita, dall’orario della visita; la sala segue la visita.visitors:write
GET/appointment-pagesElenca le pagine di appuntamento della sede, i loro orari e se ciascuna è aperta ai visitatori adesso.visitors:read
GET/visitor-roll-call/archiveElenca gli appelli terminati (emergenze, esercitazioni e avvisi), i più recenti per primi.visitors:read
GET/visitor-roll-call/{id}Un appello con le sue persone, la cronologia, i controlli di zona e i conteggi dei messaggi.visitors:read
POST/visitor-roll-call/{id}/peopleAggiunge una persona (un dipendente, altro o un appaltatore) all’appello in corso.visitors:write
POST/visitor-roll-call/{id}/scanSegna un visitatore al sicuro dal suo link o codice del pass, in un punto di raccolta.visitors:write
POST/visitor-roll-call/{id}/sweepsRegistra una zona come controllata e libera o come con persone al suo interno.visitors:write
POST/visitor-roll-call/{id}/messagesInvia un messaggio a tutti, alle persone non ancora al sicuro o alle persone che hanno bisogno di aiuto. Parte per e-mail, avviso del browser e, con il provider della sede, SMS o WhatsApp, con un link privato per rispondere che si è al sicuro o che si ha bisogno di aiuto.visitors:write
GET/visitor-roll-call/{id}/people/{entry}/messagesLa conversazione con una persona in un appello: che cosa le ha inviato il team e che cosa ha risposto dal suo link privato, dal più vecchio. Rispondi con l’endpoint dei messaggi e audience entry.visitors:read
POST/visitor-hazard-alertsUn avviso che un membro del team scrive e invia a un gruppo scelto: hazard, message e group (on_site, visitor_type, host o tenant, con group_ref). Avvia un appello di tipo hazard per quel gruppo. vFound non legge alcun flusso di meteo, notizie o minacce: non viene inviato nulla a meno che tu non invii questa richiesta. Risponde 409 finché è in corso un altro appello.visitors:write
POST/visitor-help-alertsChiedi aiuto in modo discreto: i membri del team scelti per questo vengono avvisati; nessun visitatore vede nulla.visitors:write
GET/visitor-kiosksElenca i dispositivi chiosco abbinati, in attesa e revocati.visitors:read
POST/visitor-kiosks/pairingCrea un codice di abbinamento di otto caratteri che dura dieci minuti.visitors:write
DELETE/visitor-kiosks/{id}Revoca un dispositivo chiosco.visitors:write
PUT/visitor-kiosks/{id}/settingsModifica le impostazioni di un chiosco: un’e-mail quando non viene visto per un certo numero di minuti, il ritorno alla schermata iniziale dopo un periodo di inattività, una firma alla registrazione e la stampa del badge dal tablet. Tutto parte disattivato.visitors:write
GET/visitor-analyticsTotali per giorno, ora, tipo e referente, più la permanenza media dell’ultimo anno.visitors:read
GET/visitor-registrationOttiene il link di auto-registrazione della sede e se è attivo.visitors:read
GET/school/movementsIngressi in ritardo e uscite anticipate degli alunni, dal più vecchio, a partire da since (per impostazione predefinita le ultime 24 ore), con il reference di ogni alunno per il sistema informativo della scuola. Un membro del team con sola visualizzazione indicato in X-Acting-User non può usarlo.school:read
PUT/school/pupilsAggiunge o aggiorna fino a 500 alunni per reference; invia active false per un alunno che se n’è andato. Qui non viene eliminato nulla.school:write

I dati dei visitatori sono dati personali: conservali solo per il tempo che ti serve.

Persone

L’elenco delle persone contiene i residenti, il personale o gli studenti che il tuo banco serve. Parcels vi trova i destinatari, Visitors vi trova i referenti ed Equipment propone gli utilizzatori. Tienilo allineato con il tuo sistema HR, di gestione degli studenti o delle strutture tramite l’API.

RichiestaChe cosa faAmbito
GET/peopleL’elenco, per nome. Filtri: search (nome, e-mail, unità o riferimento), updated_since.people:read
GET/people/{id}Una persona.people:read
POST/peopleAggiunge qualcuno: name (obbligatorio), email, unit, reference e language per le sue e-mail.people:write
POST/people/upsertAggiunge o aggiorna fino a 500 persone in una chiamata: people è un elenco degli stessi campi. Una persona la cui e-mail è già nell’elenco viene aggiornata. Risponde quante sono state aggiunte, aggiornate e saltate.people:write
PATCH/people/{id}Modifica solo i campi che invii.people:write
DELETE/people/{id}Rimuove una persona. I suoi pacchi, le sue visite e le sue consegne mantengono il nome che aveva.people:write
GET/people/exportScarica l’elenco completo delle persone come CSV a prova di formule.people:read
POST/people/{id}/send-my-vfoundInvia per e-mail a una persona attiva la pagina firmata con i suoi pacchi, visitatori e attrezzature collegati.people:write
GET/people/sync-sourceMostra la directory CSV salvata e l’ultimo risultato di sincronizzazione.people:read
PUT/people/sync-sourceSalva un url CSV HTTPS pubblico e mode (upsert o mirror).people:write
DELETE/people/sync-sourceRimuove il collegamento e mantiene le persone già importate.people:write
POST/people/sync-source/runEsegue subito il collegamento salvato.people:write

I titolari e i responsabili possono anche collegare un link CSV HTTPS pubblico da Persone. vFound lo controlla ogni ora, segue al massimo tre reindirizzamenti dopo aver controllato ogni destinazione, accetta al massimo 10 MB e, in modalità mirror, si ferma prima di fare modifiche quando il numero di righe valide cala di oltre il 30 per cento. I campi collegati si modificano alla loro fonte.

Provisioning automatico della directory

Microsoft Entra ha il collegamento già pronto, configurato dal cliente, descritto sopra. Le directory di identità, tra cui Okta, OneLogin e JumpCloud, possono invece alimentare l’elenco delle persone a https://vfound.io/api/scim/v2/Users con una chiave API di vFound che ha people:write. Usa la chiave bearer come token segreto. La disattivazione toglie la persona dai suggerimenti; DELETE rende anonimi i collegamenti con le stesse regole di Persone. Questo endpoint crea solo voci dell’elenco delle persone e mai accessi del team.

Gli elenchi dei partecipanti alle formazioni di Equipment possono arrivare dalla stessa directory: collega una formazione a un gruppo della directory tramite il suo nome (Equipment, Criteri, Formazione), poi assegna quel gruppo all’applicazione vFound. https://vfound.io/api/scim/v2/Groups risponde solo per i gruppi che una formazione indica e rifiuta qualsiasi altro gruppo. I suoi membri sono le persone (per id utente SCIM) che hanno la formazione; una persona che esce dal gruppo perde la formazione solo se l’ha data la directory, quindi un record aggiunto dal personale resta. Un record dato dalla directory e scaduto viene rinnovato da quel giorno quando la directory invia di nuovo il gruppo con la persona ancora dentro. I gruppi rispondono solo per una sede con Equipment. Poiché l’appartenenza a un gruppo dà una formazione, e una formazione permette di ritirare le attrezzature che la richiedono, una chiave con people:write può concedere formazioni in questo modo: tieni quella chiave per il tuo provider di identità.

Webhook

Aggiungi fino a 25 indirizzi HTTPS in Impostazioni, Per sviluppatori, o tramite l’API qui sotto, e scegli quali degli eventi qui sotto riceve ciascuno. vFound invia un POST JSON entro pochi secondi, riprova gli invii non riusciti per circa tre ore e mette in pausa un indirizzo dopo 15 invii falliti di fila.

EventoQuandoDati
item.createdViene aggiunto un oggetto ritrovatoOggetto
item.updatedCambiano il suo stato, titolo, luogo, categoria, data di conservazione o visibilità della fotoOggetto
item.transfer_sentUn oggetto ritrovato viene inviato a un’altra sede del gruppo (entrambe le sedi lo ricevono)Trasferimento di oggetto
item.transfer_cancelledLa sede che invia lo riprende prima che arriviTrasferimento di oggetto
item.transfer_receivedLa sede ricevente conferma che è arrivatoTrasferimento di oggetto
claim.createdUn ospite invia una richiestaRichiesta
item.disposition_recordedUn oggetto viene donato o smaltitoOggetto
item.match_updatedCambia un verdetto di abbinamento IA salvato; report_id, item_id, label e reasonCoppia di corrispondenza
lost_report.match_updatedCambia un verdetto di abbinamento IA salvato; report_id, item_id, label e reasonCoppia di corrispondenza
claim.ownership_reviewedUn responsabile registra una verifica di proprietà; recupera la custodia per la cronologia delle verificheRichiesta
claim.decision_recordedUna richiesta viene accettata o rifiutataRichiesta
claim.release_approvedUn altro responsabile approva il rilascioRichiesta
claim.handover_recordedIl ritiro fisico chiude una richiesta pronta per il ritiroRichiesta
claim.status_changedUna richiesta passa a un nuovo statoRichiesta
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.createdUn ospite segnala uno smarrimentoSegnalazione di smarrimento
parcel.loggedUn pacco viene registrato al banco o tramite l’APIPacco
parcel.updatedCambia uno qualsiasi dei suoi dettagli al banco, come il destinatario, il numero di tracciamento o lo scaffalePacco
parcel.remindedAl destinatario viene inviato un promemoria, dal banco o automaticamentePacco
parcel.collectedUn pacco viene consegnatoPacco
parcel.returnedUn pacco viene restituito al mittentePacco
parcel.recipient_arrivedUn destinatario dice di essere al bancoVoce della coda di ritiro
parcel.reminders_snoozedUn destinatario mette in pausa i suoi promemoriaPersona e numero di pacchi
parcel.heldUn destinatario imposta una data di sospensionePersona, data e numero di pacchi
parcel.proxy_createdUn destinatario invia per e-mail a un delegato un codice di ritiroPersona, delegato e scadenza
parcel.pickup_servedIl banco segna un arrivo come servitoVoce della coda di ritiro
parcel.escalatedUn pacco in attesa raggiunge l’anzianità di escalation della sedePacco
parcel.outgoing_loggedUn pacco in uscita viene registratoPacco in uscita
parcel.outgoing_handed_overUn pacco in uscita viene consegnato a un corriereConsegna in uscita
parcel.round_createdViene creato un giro di consegnaRiepilogo del giro
parcel.round_deliveredViene completata una fermata di un giro di consegnaId del giro, della fermata e dei pacchi
checkroom.checked_inQualcosa viene registrato in deposito e riceve un numeroTicket
checkroom.handed_backViene riconsegnatoTicket
checkroom.leftLa serata viene chiusa con l’oggetto ancora in CheckroomTicket
checkroom.self_checkin_startedUn ospite avvia un ticket da un chiosco abbinatoTicket
checkroom.ready_requestedUn ospite chiede al banco di preparare le sue coseTicket
checkroom.readyIl banco segna come pronte le cose di un ospiteTicket
checkroom.station_createdViene creata una postazione di CheckroomPostazione
checkroom.station_updatedCambia una postazione di CheckroomPostazione
checkroom.event_createdViene creato un evento di CheckroomEvento
checkroom.event_updatedCambia un evento di CheckroomEvento
loan.checked_outUn articolo viene consegnatoConsegna
loan.due_soonL’orario di scadenza è a meno di due ore, una volta per orario di scadenzaConsegna
loan.overdueL’orario di scadenza passa e l’articolo non è rientrato, una volta per orario di scadenzaConsegna
loan.extendedCambia il suo orario di scadenzaConsegna
loan.returnedRientra al bancoConsegna
loan.lostViene registrato come non restituitoConsegna
loan.checkout_createdViene creata una consegna atomica di più articoliConsegna, con l’eventuale scorta sulla stessa ricevuta in stock
loan.self_checkoutUn utilizzatore completa la consegna al chioscoConsegna
loan.kit_createdViene creato un kit di attrezzature salvatoKit
loan.kit_updatedCambia un kit di attrezzature salvatoKit
loan.reservation_requestedUna prenotazione attende l’approvazionePrenotazione
loan.reservation_createdUna prenotazione viene confermata subitoPrenotazione
loan.reservation_approvedUna prenotazione in attesa viene approvataPrenotazione
loan.reservation_readyLe attrezzature prenotate sono pronte per il ritiroPrenotazione
loan.reservation_cancelledUna prenotazione viene annullataPrenotazione
loan.reservation_collectedLe attrezzature prenotate vengono consegnateConsegna
loan.extension_requestedUn utilizzatore chiede più tempoConsegna
loan.problem_reportedUn utilizzatore segnala un problema a un’attrezzaturaConsegna
loan.rule_updatedCambia la regola di consegna di una categoriaRegola
loan.maintenance_loggedViene registrata una manutenzioneManutenzione
loan.maintenance_dueUna manutenzione programmata scadeManutenzione
loan.service_dueUn piano di manutenzione ricorrente scade (per data, ore di consegna o numero di consegne), una volta per cicloManutenzione
loan.work_order_openedViene aperto un ordine di lavoro, dal personale o da una restituzione per cui la sede chiede di aprirne unoManutenzione
loan.work_order_closedUn ordine di lavoro viene completato o annullatoManutenzione
loan.item_disposedUn articolo viene dismesso (venduto, rottamato, donato, riciclato, perso o rubato)Equipment
loan.stocktake_startedParte un inventario delle attrezzatureInventario
loan.stocktake_completedTermina un inventario delle attrezzatureInventario
loan.transfer_preparedUna sede autorizzata prepara le attrezzature da spostareTrasferimento
loan.transfer_sentLe attrezzature preparate lasciano la sede di origineTrasferimento
loan.transfer_receivedLa sede di destinazione riceve le attrezzatureTrasferimento
loan.transfer_rejectedLa sede di destinazione rifiuta un trasferimento preparatoTrasferimento
loan.transfer_cancelledLa sede di origine annulla un trasferimento preparatoTrasferimento
loan.transfer_exceptionUn trasferimento in transito richiede attenzioneTrasferimento
loan.transfer_lostLa sede di origine chiude un trasferimento mai arrivatoTrasferimento
loan.charge_recordedViene registrata una multa, un danno, una sostituzione, un uso o un altro addebitoVoce di addebito
loan.charge_waivedUn responsabile condona ciò che un addebito richiede ancora, con un motivoVoce di addebito
loan.payment_recordedIl personale registra denaro che la sede ha incassato direttamente (vFound non elabora mai un pagamento)Voce di addebito
loan.payment_voidedUn responsabile annulla un pagamento registrato per erroreVoce di addebito
loan.deposit_recordedIl personale registra una cauzione incassata dalla sedeVoce di addebito
loan.deposit_resolvedUna cauzione custodita viene restituita o incamerataVoce di addebito
loan.invoice_issuedViene emessa una fattura per gli addebiti di un utilizzatoreFattura
loan.invoice_voidedUn responsabile annulla una fattura, con un motivoFattura
loan.quote_acceptedIl team accetta un preventivo e le sue prenotazioni vengono fattePreventivo
loan.payment_request_createdIl team registra una richiesta di pagamento (non viene inviato nulla alla persona)Richiesta di pagamento
loan.payment_request_paidI pagamenti registrati rispetto a una richiesta la coprono per interoRichiesta di pagamento
loan.delivery_doneUna consegna o un ritiro viene segnato come completatoConsegna
loan.items_importedSi completa un’importazione CSV delle attrezzatureConteggi
visit.expectedUn visitatore viene invitatoVisita
visit.signed_inUn visitatore registra l’ingresso, al banco o dal tuo cartello QRVisita
visit.host_confirmedIl banco conferma chi un visitatore registrato da solo è venuto a trovareVisita
visit.signed_outNe viene registrata l’uscita, al banco, dal suo pass o automaticamente dopo la fine della giornataVisita
visit.cancelledUn invito viene annullatoVisita
visit.approval_requestedUna visita attende l’approvazione del personaleVisita
visit.approvedUna visita in attesa viene approvataVisita
visit.deniedUna visita in attesa viene rifiutataVisita
visit.host_repliedUn referente risponde dal suo link privatoVisita
visit.roll_call_startedParte un appello in tempo reale (un’emergenza, un’esercitazione o un avviso)Riepilogo dell’appello
visit.roll_call_completedTermina un appello in tempo realeRiepilogo dell’appello
visitor_type.createdViene creato un tipo di visitatoreTipo di visitatore
visitor_type.updatedCambia un tipo di visitatoreTipo di visitatore
visitor_type.deactivatedUn tipo di visitatore viene disattivatoTipo di visitatore
visitor_agreement.signedUn visitatore ha firmato un documento di accordo, con un link alla copia firmata che funziona per sette giorniFirma dell’accordo
kiosk.pairedUn chiosco per visitatori viene abbinatoChiosco
kiosk.revokedUn chiosco per visitatori viene revocatoChiosco
courier.signed_inUn corriere in visita viene registrato in ParcelsCorriere
courier.signed_outUn corriere in visita se ne vaCorriere
staff.signed_inUna persona dell’elenco del personale registra l’ingresso, in ufficio o da remotoPresenza del personale
staff.signed_outUna persona dell’elenco del personale registra l’uscita, o ne viene registrata automaticamente l’uscitaPresenza del personale
person.createdViene aggiunta una personaPersona
person.updatedUna persona viene modificataPersona
person.deactivatedIl provisioning della directory disattiva una personaPersona
person.deletedUna persona viene rimossaPersona
people.sync.completedSi completa una sincronizzazione CSV collegataConteggi
people.sync.failedUna sincronizzazione CSV collegata fallisce in sicurezzaErrore
report.deliveredUn report programmato di Report e analisi, condiviso con la sede, viene eseguito con invio ai webhook scelti (un report privato non viene mai inviato ai webhook); iscriviti in Impostazioni, Per sviluppatori (una chiave API non può iscriversi)Ogni colonna indicata dal report e fino a 5,000 righe, oppure ogni gruppo
queue.ticket_joinedUna persona si mette in coda, dal telefono, da un chiosco, dal banco o dall’APITicket di coda
queue.ticket_calledUna persona viene chiamata a uno sportello, o chiamata di nuovoTicket di coda
queue.ticket_servedUna persona viene segnata come servitaTicket di coda
queue.ticket_no_showUna persona chiamata viene segnata come assente, dal team o dopo i minuti della codaTicket di coda
queue.ticket_leftUna persona esce dalla coda dal suo ticket, o il team la toglieTicket di coda
queue.ticket_transferredUna persona viene spostata in un’altra coda o a un altro sportelloTicket di coda
queue.ticket_closedUn ticket ancora aperto alla fine della giornata della sede, o in una coda archiviata, viene chiusoTicket di coda
queue.booking_createdUna persona prenota un orario dalla pagina degli orari prenotati di una coda, o lo prenota l’APIPrenotazione di Queue
queue.booking_cancelledUn orario prenotato viene annullato dalla persona, dal team o dall’APIPrenotazione di Queue
queue.ticket_arrivedUna persona che si è messa in coda prima di arrivare dice di essere qui, o il team la segna come arrivataTicket di coda
queue.message_receivedUna persona in coda scrive al team dalla pagina del suo ticket; l’evento non contiene le paroleMessaggio di Queue
queue.message_sentIl team scrive a una persona in coda; l’evento non contiene le paroleMessaggio di Queue
queue.survey_answeredUna persona servita risponde al sondaggio; l’evento contiene la valutazione e mai il commentoRisposta al sondaggio di Queue
{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
 "venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}

Verifica la firma

Ogni invio contiene Vfound-Signature: t=<unix time>,v1=<hex>, dove l’esadecimale è un HMAC SHA256 di t + "." + raw body con il segreto del tuo endpoint. Rifiuta gli invii più vecchi di cinque minuti. Dopo aver creato un nuovo segreto di firma, per 24 ore gli invii contengono due valori v1, uno per ciascun segreto, quindi accetta l’invio se uno qualsiasi corrisponde.

// 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;

Le intestazioni includono anche Vfound-Event e un id univoco Vfound-Delivery che puoi usare per ignorare i duplicati. I webhook vengono inviati solo a indirizzi HTTPS pubblici sulla porta 443.

Iscriversi tramite l’API

Strumenti come Zapier possono aggiungere e rimuovere i propri indirizzi con una chiave che ha webhooks:manage. Il segreto di firma viene mostrato una sola volta, nella risposta al POST. La risposta contiene anche un’intestazione Location con l’indirizzo da chiamare con DELETE quando l’iscrizione viene rimossa.

Una chiave può iscriversi solo a eventi i cui dati potrebbe leggere: ogni evento richiede l’ambito di lettura del suo prodotto (items:read per gli eventi degli oggetti, claims:read per gli eventi delle richieste, lost_reports:read, parcels:read, checkroom:read, loans:read per gli eventi delle attrezzature, visitors:read per gli eventi di visita, tipo di visitatore, chiosco e corriere, e people:read per gli eventi di persone e dell’elenco delle persone). Una chiave elenca e rimuove solo gli indirizzi che ha creato lei stessa; gli indirizzi aggiunti in Impostazioni, o da un’altra chiave, non sono visibili per lei.

RichiestaChe cosa faAmbito
GET/webhooksGli indirizzi creati da questa chiave e i loro eventi.webhooks:manage
POST/webhooksAggiunge un indirizzo: url (HTTPS pubblico sulla porta 443) e events, un elenco degli eventi sopra elencati che la chiave può leggere.webhooks:manage
DELETE/webhooks/{id}Rimuove un indirizzo creato da questa chiave e la sua cronologia degli invii.webhooks:manage

Cronologia degli invii

Impostazioni, Per sviluppatori, elenca ogni invio a ciascun indirizzo degli ultimi 30 giorni, con il suo esito, e ne rimanda qualsiasi con lo stesso id Vfound-Delivery. Lì puoi anche modificare un indirizzo, riattivarne uno in pausa e creare un nuovo segreto di firma. Un indirizzo che fallisce 15 invii di fila viene messo in pausa e il titolare della sede riceve un’e-mail.

Feed dei dati dei report (Power BI)

Un titolare o un responsabile crea un link di feed in Report e analisi, in Feed di dati Power BI, per i prodotti che sceglie. Il link viene mostrato una sola volta. In Power BI scegli Recupera dati, poi Web, e incollalo. Ogni link legge una sola sede e smette subito di funzionare quando viene revocato, quando la persona che lo ha creato non è più titolare o responsabile della sede, o quando la sede è in pausa o chiusa.

GET /api/feeds/reports/{token}/{dataset} restituisce le righe di un dataset: equipment_loans, equipment_activity, visits o checkroom_tickets. Scegli il suo periodo con days (da 1 a 366, 90 se omesso) oppure from e to (YYYY-MM-DD, secondo l’orologio della sede). GET /api/feeds/reports/{token}/saved/{id} restituisce un report salvato condiviso con l’intera sede, per il periodo proprio di quel report; days, from e to non lo cambiano. Puoi anche inviare il token come Authorization: Bearer <token> a /api/feeds/reports/{dataset} o /api/feeds/reports/saved/{id}. Una risposta contiene fino a 100,000 righe in value, quindi Recupera dati, Web legge l’intero risultato; poi trasforma l’elenco value in una tabella. La risposta termina con total e truncated: quando corrispondono più righe di quante ne contenga una risposta, truncated è true e @odata.nextLink indica il resto ($top e $skip le scorrono, per gli strumenti che lo seguono); Recupera dati, Web non lo segue, quindi scegli invece un periodo più breve. Quando le righe di un report richiederebbero la lettura di più di 400,000 righe o più di 20 secondi, la risposta termina con error, total null e truncated true; un report salvato raggruppato risponde invece 422 con il motivo. Le righe arrivano nell’ordine in cui sono state registrate. Gli orari nelle righe sono in UTC (ISO 8601); un report salvato raggruppato per una data etichetta ogni gruppo con il giorno, la settimana, il mese, il giorno della settimana o l’ora secondo l’orologio della sede. Gli indirizzi e-mail e il nome e la stanza di un ospite di Checkroom sono esclusi a meno che il link non sia stato creato per includere i dati di contatto.

Assistenti IA (MCP)

vFound è un server Model Context Protocol a https://vfound.io/api/mcp, così gli assistenti IA possono cercare informazioni e aiutare al banco. Collegane uno in uno di due modi: accedi con vFound, per gli assistenti i cui connettori accedono con OAuth, oppure con una chiave API, per i client che inviano un’intestazione, come Claude Code, Cursor e Visual Studio Code. In entrambi i casi vede solo gli strumenti che i suoi ambiti consentono, per i prodotti che la tua sede ha aperto. Un client collegato con una chiave API può anche inviare X-Acting-User; ogni strumento viene allora eseguito come quel membro del team, nei limiti del suo ruolo.

# 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_…"}}}}
StrumentoChe cosa faAmbito
search_found_itemsCerca oggetti ritrovati per parole come “iPhone nero”items:read
list_expected_visitorsVisitatori invitati e non ancora arrivativisitors:read
list_visitors_on_siteVisitatori presenti in questo momentovisitors:read
list_visitor_typesTipi di visitatore e le loro regolevisitors:read
visitor_analyticsTotali, andamenti e permanenza media dei visitatorivisitors:read
visitor_registration_linkIl link di auto-registrazione della sedevisitors:read
list_couriers_on_siteCorrieri registrati tramite Visitorsparcels:read
list_waiting_parcelsPacchi in attesa di ritiroparcels:read
detect_parcel_trackingNormalizza un numero di tracciamento e rileva il suo corriereparcels:read
parcel_pickup_queuePersone in attesa al banco dei pacchiparcels:read
parcel_shelvesCapacità e occupazione degli scaffali dei pacchiparcels:read
parcel_analyticsVolume dei pacchi, corrieri e rendimento dei ritiriparcels:read
list_outgoing_parcelsPacchi in uscita e il loro stato di consegnaparcels:read
list_parcel_roundsGiri di consegna dei pacchi e fermateparcels:read
list_checkroom_exit_queueTicket i cui ospiti attendono all’uscitacheckroom:read
mark_checkroom_readySegna come pronto un ticket in attesa e avvisa l’ospitecheckroom:write
list_checkroom_stationsPostazioni di Checkroom e intervalli di numericheckroom:read
list_checkroom_eventsEventi di Checkroom recenti e futuricheckroom:read
checkroom_reportVolume di Checkroom, tempo di restituzione e totali delle tariffecheckroom:read
list_queue_linesCode, persone in attesa e attesa stimata adessoqueue:read
list_queue_waitingPersone in attesa oggi, in ordine di chiamataqueue:read
queue_reportTotali di Queue e mediana dei minuti di attesa e di servizioqueue:read
call_next_in_queueChiama la persona successiva a uno sportelloqueue:write
mark_queue_ticket_servedSegna come servita la persona allo sportelloqueue:write
list_overdue_equipmentAttrezzature oltre l’orario di scadenza e chi le haloans:read
list_equipment_kitsGruppi salvati di attrezzatureloans:read
create_equipment_kitSalva un kit di attrezzature riutilizzabile senza consegnarloloans:write
list_equipment_reservationsPrenotazioni per orario e statoloans:read
reserve_equipmentRiserva un articolo o una categoria senza consegnarliloans:write
book_repeating_reservationPrenota un articolo, una categoria o uno spazio ogni giorno o ogni settimanaloans:write
move_reservationSposta una prenotazione a nuovi orari o a un altro articolo della sua categorialoans:write
list_waitlistLe persone in attesa di un orario che è stato presoloans:read
join_waitlistAggiunge una persona alla lista d’attesaloans:write
list_space_bookingsOgni stanza, scrivania o posto auto e le sue prenotazioni tra due orariloans:read
book_spacePrenota una stanza o uno spazio per una persona e un orario; non viene mai consegnatoloans:write
list_equipment_rulesRegole di consegna della sede e delle categorieloans:read
save_equipment_ruleCrea o sostituisce la regola di una categorialoans:write
list_equipment_maintenanceCronologia di manutenzione delle attrezzature e lavori in arrivoloans:read
list_equipment_service_plansPiani ricorrenti di manutenzione, taratura, prova di sicurezza, ispezione e pulizia e quali sono in scadenzaloans:read
update_equipment_work_orderModifica o chiude un ordine di lavoro delle attrezzatureloans:write
get_equipment_maintenance_costsCosto di manutenzione, riparazione e pulizia per articololoans:read
get_equipment_valuationIl valore delle attrezzature a una data dopo l’ammortamento (titolari e responsabili)loans:read
list_equipment_substancesIl registro delle sostanze pericolose: sostanza, luogo, classi di pericolo e date di revisione (un record, nessun consiglio sulla sicurezza)loans:read
get_equipment_fundingChe cosa ha acquistato ciascun fondo, contributo o centro di costo e quale lavoro gli è stato addebitato (titolari e responsabili)loans:read
get_equipment_plannerLavori programmati e ordini di lavoro aperti per giorno della sedeloans:read
list_equipment_licencesLicenze delle attrezzature con utenze e date di fine (titolari e responsabili)loans:read
get_equipment_expiriesAssicurazioni e licenze in scadenza o già scadute (titolari e responsabili)loans:read
log_equipment_maintenanceRegistra manutenzione, taratura, una prova di sicurezza, un’ispezione, una pulizia, una riparazione o una notaloans:write
list_equipment_stocktakesInventari recenti e i loro conteggiloans:read
start_equipment_stocktakeAvvia un inventarioloans:write
scan_equipment_stocktakeRegistra un articolo in un inventario apertoloans:write
scan_many_equipment_stocktakeConta molti codici in un inventario aperto in una voltaloans:write
finish_equipment_stocktakeTermina un inventario e restituisce ciò che mancaloans:write
list_equipment_transfersTrasferimenti in entrata e in uscita senza i dati dell’utilizzatoreloans:read
preview_equipment_importConvalida un CSV di attrezzature senza salvarloloans:write
find_personCerca una persona nell’elenco delle personepeople:read
export_peopleEsporta l’elenco delle persone come CSV a prova di formulepeople:read
directory_sync_statusControlla il collegamento CSV salvato e la sua ultima esecuzionepeople:read
run_directory_syncEsegue subito il collegamento CSV salvatopeople:write
email_my_vfoundInvia per e-mail a una persona la sua pagina privata firmatapeople:write
invite_visitorInvita un visitatore, che riceve un pass per e-mailvisitors:write
approve_visitApprova la richiesta di una visita in attesavisitors:write
list_free_workplace_spacesTrova scrivanie, sale riunioni o parcheggi liberi per un orariovisitors:read
book_workplace_spacePrenota una scrivania, una sala riunioni o un posto auto per una personavisitors:write
request_visit_cateringChiede il catering con una visita, tra le opzioni elencate dalla sedevisitors:write
list_appointment_pagesElenca le pagine di appuntamento della sede e se ciascuna è aperta ai visitatorivisitors:read
list_staff_on_siteElenca le persone dell’elenco del personale presenti in questo momento, in ufficio o da remotovisitors:read
sign_staff_in_or_outRegistra l’ingresso o l’uscita di una persona dell’elenco del personalevisitors:write
list_visitor_assets_not_returnedElenca gli oggetti consegnati ai visitatori che non sono ancora segnati come restituitivisitors:read
issue_visitor_assetRegistra un oggetto consegnato a una visita attesa o già registratavisitors:write
return_visitor_assetSegna come restituito un oggetto consegnato a una visitavisitors:write
start_roll_callAvvia l’appello o ottiene quello attivovisitors:write
mark_visitor_safeSegna un visitatore al sicurovisitors:write
create_kiosk_pairingCrea un codice di abbinamento del chiosco di dieci minutivisitors:write
log_parcelRegistra un pacco e invia un’e-mail al destinatarioparcels:write
remind_parcelRicorda a un destinatario di ritirare un paccoparcels:write
remind_parcelsInvia un promemoria fino a 200 destinatari di pacchi selezionatiparcels:write
log_outgoing_parcelAggiunge un pacco in uscita al registro dei corrieriparcels:write
create_parcel_roundCrea un giro di consegna dai pacchi in attesaparcels:write
extend_loanDà più tempo a un utilizzatoreloans:write

Ogni strumento esegue la richiesta API sopra con gli stessi controlli, quindi un assistente non può mai fare più della sua chiave o del suo collegamento. Non esistono strumenti che consegnano qualcosa, registrano l’ingresso o l’uscita di qualcuno, decidono una richiesta o eliminano. Ogni risposta conta per le 120 richieste al minuto della chiave o del collegamento.

Accedi con vFound

Aggiungi https://vfound.io/api/mcp come connettore nel tuo assistente. L’assistente trova da solo come accedere e apre una pagina di vFound, dove un titolare o un responsabile accede come di consueto alla propria area di lavoro, sceglie la sede e vede in parole semplici che cosa può fare l’assistente, e può deselezionare qualsiasi cosa. Il personale e i membri con sola visualizzazione non possono collegare un assistente. L’assistente è della tua sede: il tuo abbonamento con il suo provider paga la sua IA, e vFound riceve solo le richieste di strumenti che invia.

Un collegamento agisce come la persona che lo ha autorizzato, con gli stessi controlli di una chiave API: smette di funzionare se quella persona non gestisce più la sede o la sede non è attiva, non cambia nulla mentre l’abbonamento è in pausa e vede gli strumenti solo dei prodotti aperti. Il suo token di accesso dura un’ora e l’assistente lo rinnova da solo; un collegamento non usato per 30 giorni richiede di nuovo l’accesso. Vedi ciascuno, chi lo ha collegato e quando è stato usato l’ultima volta in Impostazioni, Per sviluppatori, dove Scollega lo ferma subito. Il token funziona solo sull’endpoint MCP, non sull’API REST; un’app che ha bisogno dell’API REST si collega come dice la sezione successiva.

Per chi sviluppa client: OAuth 2.1 come descrive la specifica di autorizzazione MCP, solo con il flusso del codice di autorizzazione e PKCE (S256). Individuazione: /.well-known/oauth-protected-resource (RFC 9728, resource https://vfound.io/api/mcp) e /.well-known/oauth-authorization-server (RFC 8414); una richiesta senza token riceve un’intestazione WWW-Authenticate che indica la prima. I client si registrano da soli su /oauth/register (RFC 7591) come client pubblici senza segreto; gli indirizzi di reindirizzamento devono usare https, oppure http solo per localhost o 127.0.0.1, e devono poi corrispondere esattamente. Poi /oauth/authorize, /oauth/token (i codici durano 60 secondi e funzionano una sola volta; i token di aggiornamento vengono sostituiti a ogni uso e riusarne uno vecchio scollega l’assistente) e /oauth/revoke (RFC 7009). Gli ambiti usano i nomi delle chiavi API sopra; invia resource=https://vfound.io/api/mcp (RFC 8707).

Accedi con vFound per altre app

Un’app che non è un assistente IA, come un sistema di inventario, di prenotazione o HR, può collegarsi allo stesso modo all’API REST invece di usare una chiave API: invia resource=https://vfound.io/api/v1 a /oauth/authorize e /oauth/token, con gli ambiti nei nomi delle chiavi API, tranne webhooks:manage, che a un’app non può essere dato. Un titolare o un responsabile accede, vede il nome dell’app e che cosa può fare in parole semplici, può deselezionare qualsiasi cosa e lo autorizza. Il collegamento agisce come quella persona con gli stessi controlli di una chiave API: smette di funzionare se non gestisce più la sede o la sede non è attiva, non cambia nulla mentre l’abbonamento è in pausa e può fare 120 richieste al minuto, come una chiave. X-Acting-User funziona solo con una chiave API. Il suo token di accesso funziona solo sull’API REST, mai sull’endpoint MCP, e un consenso mostrato per uno non approva mai l’altro. Compare in Impostazioni, Per sviluppatori come app che usa l’API di vFound, dove Scollega la ferma subito. Individuazione: /.well-known/oauth-protected-resource/api/v1; il resto è il flusso sopra.

Errori

Gli errori sono JSON con un message; gli errori di convalida aggiungono errors per campo. 401 significa nessuna chiave valida, 403 un ambito mancante, una chiave il cui creatore non gestisce più la sede, un membro del team in X-Acting-User che non è un membro attivo o il cui ruolo non consente l’ambito, una sede non attiva, o una modifica inviata mentre l’abbonamento è in pausa, 404 non trovato nella tua sede, 422 dati non validi e 429 troppe richieste.

Quando una modifica non può avvenire a causa dello stato attuale del record, la risposta è 422 con anche un code stabile. I codici non cambiano mai nome:

CodiceChe cosa significa
parcel_not_waitingIl pacco non è più in attesa: è già stato ritirato, restituito o consegnato.
tracking_duplicateUn pacco con questo numero di tracciamento è già in attesa qui.
no_emailLa persona o il visitatore non ha un indirizzo e-mail, quindi non si può inviare nulla.
capacity_fullOgni numero di Checkroom è in uso.
already_checked_inIl ticket di Checkroom è già registrato in deposito.
already_handed_backIl ticket di Checkroom è già stato riconsegnato.
nothing_to_hand_backIl ticket di Checkroom non ha nulla da riconsegnare.
number_in_useQuel numero di Checkroom è già in uso.
ticket_closedSolo un ticket di Checkroom aperto può essere inviato per e-mail.
item_outL’attrezzatura è fuori con qualcuno. Riprendila prima.
item_in_repairL’attrezzatura è messa da parte per la riparazione.
item_retiredL’attrezzatura è ritirata dal servizio, quindi non può essere consegnata né riservata.
reservation_conflictQualcuno ha riservato l’articolo, o l’ultimo libero della sua categoria, in questo periodo, oppure si prevede che sia ancora fuori.
already_backL’attrezzatura è già stata ripresa.
not_outL’attrezzatura non è fuori, quindi non può avere più tempo, un promemoria né essere segnata come non restituita.
borrower_overdueL’utilizzatore ha attrezzature in ritardo, e la sede o la categoria non consente altro finché non rientrano.
borrower_item_limitQuesto darebbe all’utilizzatore più articoli di quanti la sede o la categoria ne consenta contemporaneamente.
reservation_not_readyLa prenotazione non è ancora approvata, oppure è già stata ritirata o annullata.
reservation_item_mismatchLa consegna non include l’articolo per cui è la prenotazione.
reservation_category_mismatchLa consegna include un articolo fuori dalla categoria riservata.
reservation_borrower_mismatchLa prenotazione appartiene a un altro utilizzatore.
reservation_too_longLa prenotazione è più lunga di quanto la categoria possa essere usata. Solo le prenotazioni fatte da My vFound sono limitate in questo modo.
reservation_daily_limitL’utilizzatore ha già fatto 5 prenotazioni da My vFound nelle ultime 24 ore.
booking_noticeLa prenotazione inizia prima di quanto consenta il preavviso minimo della categoria.
booking_too_far_aheadLa prenotazione, la consegna o il nuovo orario di scadenza finisce più tardi di quanto la categoria possa essere prenotata in anticipo.
desk_closedLa prenotazione inizierebbe in un giorno in cui il banco delle attrezzature è chiuso.
kit_unavailableUna parte di un kit o di un carrello non è disponibile in questo periodo, quindi non è stato riservato nulla. Il campo unavailable elenca ogni parte e il motivo.
borrower_not_in_groupLa sede lascia ritirare o prenotare solo alle persone con un tipo di utilizzatore, e questo utilizzatore non ne ha nessuno (oppure è stato digitato invece di essere scelto dall’elenco delle persone).
category_not_allowedNessuno dei tipi di utilizzatore dell’utilizzatore consente questa categoria.
borrower_on_holdIl ritiro è sospeso per questa persona: il personale ha messo un blocco, la sede sospende il ritiro dopo restituzioni in ritardo ripetute, oppure la persona deve almeno l’importo a cui la sede blocca (tipo charges). Il campo hold indica il suo tipo e fino a quando.
space_too_smallPiù persone di quante la stanza o lo spazio ne contenga (la sua capacità).
kit_lockedL’attrezzatura appartiene a un kit bloccato, che esce solo per intero: includi ogni articolo indicato del kit.
approval_not_yoursLa sede ha impostato gli approvatori in ordine e questa persona non è la prossima (oppure la sede non lascia saltare una fase a nessuno per lei).
project_not_approvedLa prenotazione appartiene a un progetto non ancora approvato, quindi non si può ritirare nulla.
not_enough_creditsLa sede usa crediti di prenotazione e questa persona non ne ha più. Dagliene prima. Una prenotazione annullata o mai ritirata restituisce il suo credito.
risk_assessment_pendingLa prenotazione ha una valutazione dei rischi non ancora approvata, quindi non si può ritirare nulla.
series_unavailableNon è stato possibile fare una prenotazione ripetuta perché almeno uno dei suoi orari è occupato o contrario a una regola di prenotazione, quindi non è stato riservato nulla. Il campo skipped elenca ogni orario e il motivo.
time_availableL’orario per cui qualcuno ha chiesto di aspettare è libero, quindi prenotalo invece di mettersi in lista d’attesa.
space_not_handed_outUna stanza o uno spazio è prenotato per il suo orario e non viene mai consegnato, quindi non si può consegnare né ritirare.
stock_shortNon c’è abbastanza di questo articolo di scorta nel luogo (e nel lotto) indicato, quindi non è cambiato nulla. Il campo available dà la quantità presente.
stock_issue_closedTutto ciò che è stato consegnato da questa scorta è già rientrato o stornato.
order_closedUn ordine di acquisto è concluso o annullato e non può cambiare.
order_over_receivedÈ stato inserito più di quanto una riga dell’ordine di acquisto ancora si aspetti.
order_not_placedLa scorta non può essere ricevuta rispetto a un ordine di acquisto ancora in bozza.
fees_offGli addebiti sono disattivati per questa sede. Attivali prima nel criterio del banco e di consegna.
entry_closedQuella voce di addebito o fattura non può più cambiare in questo modo: l’addebito è saldato o condonato, il pagamento è annullato, la cauzione è stata restituita o incamerata, oppure la fattura è annullata.
on_invoiceL’addebito è su una fattura emessa. Annulla prima la fattura, poi condona l’addebito.
not_lateLa consegna non è rientrata in ritardo secondo le regole sulle multe per ritardo della sede, oppure è ancora fuori.
nothing_to_invoiceL’utilizzatore non ha addebiti aperti in quella valuta che non siano già su una fattura emessa.
charge_unavailableUno degli addebiti scelti non è aperto, è su un’altra fattura o è per qualcun altro.
desk_keptLa scrivania è riservata a un’altra persona in uno dei giorni richiesti.
desk_has_bookingsRiservare la scrivania a questa persona entrerebbe in conflitto con prenotazioni aperte di altri in quei giorni. Annullale prima.
booking_closedLa prenotazione della scrivania, della sala o del parcheggio è stata annullata o rilasciata, quindi non si può registrare la presenza.
check_in_closedLa registrazione della presenza si apre 15 minuti prima dell’inizio di una prenotazione e si chiude quando finisce.
item_service_dueLa sede impedisce l’uscita delle attrezzature che richiedono lavori, e la data di manutenzione di questo articolo è arrivata o uno dei suoi piani scade. Registra prima il lavoro.
item_failed_inspectionLa sede impedisce l’uscita delle attrezzature che richiedono lavori, e l’ultimo controllo di questo articolo non è stato superato. Registra prima un esito positivo.
work_order_closedQuesto ordine di lavoro è già chiuso e non può essere modificato.
already_disposedQuesto articolo è già stato dismesso.
not_disposedQuesto articolo non è stato dismesso, quindi non c’è nulla da annullare.
item_disposedQuesto articolo è stato dismesso. Annulla la dismissione prima di usarlo di nuovo.
training_requiredUna regola di categoria o l’articolo richiede una formazione che l’utilizzatore non ha, o ha solo oltre la data di scadenza. Il campo training indica che cosa manca.
stocktake_openUn inventario è già aperto. Terminalo prima.
item_unavailableL’attrezzatura non è disponibile o è messa da parte per la riparazione, quindi non può avviare un trasferimento.
transfer_openL’attrezzatura ha già un trasferimento aperto.
transfer_not_readySi può inviare solo un trasferimento preparato.
transfer_not_in_transitSi può ricevere o segnalare con un problema solo un’attrezzatura in transito.
transfer_already_sentUn trasferimento inviato non può più essere annullato né rifiutato.
already_signed_inIl visitatore ha già registrato l’ingresso.
visit_closedLa visita è chiusa. Registra l’ingresso del visitatore come nuova visita.
not_signed_inIl visitatore non ha registrato l’ingresso.
not_expectedSolo una visita attesa può essere annullata o ricevere un pass.
approval_requiredLa visita richiede approvazione prima che il visitatore possa registrare l’ingresso.
visit_not_valid_todayIl pass non può essere usato di nuovo oggi, oppure oggi è fuori dalle sue date.
plus_one_not_allowedIl pass non consente ospiti, oppure non è più approvato, atteso o valido.
plus_one_limitIl visitatore ha aggiunto tutti gli ospiti che il pass consente.
nobody_to_sign_inNessuno del gruppo della visita è atteso oggi.
visitor_capacity_fullRegistrare l’ingresso del visitatore supererebbe il limite di visitatori presenti contemporaneamente della sede o del tipo di visitatore.

Registrare l’ingresso di un visitatore al banco risponde 409 con un code quando il visitatore ha prima bisogno di un controllo di un membro del team. La risposta indica solo il tipo di corrispondenza (blocklist, building, restricted_party o answers); la voce, il suo nome e il suo motivo sono per il team della sede e non compaiono mai in una risposta API. Invia di nuovo la richiesta con screening_reviewed impostato su true solo dopo che un membro del team ha controllato la corrispondenza. Serve una chiave con l’ambito visitors:screening (disattivato per impostazione predefinita, come l’accesso di ogni altra chiave), e una chiave che indica un membro del team in X-Acting-User ha bisogno di uno il cui ruolo decide sulle visite. La conferma viene registrata come della chiave, con il suo nome, mai come del membro del team che ha creato la chiave. Senza l’ambito la risposta è 403 con screening_scope. Lo stesso vale per l’approvazione di una visita che una corrispondenza trattiene:

CodiceChe cosa significa
screening_matchIl visitatore corrisponde a una delle liste di esclusione della sede, a un controllo del team o all’elenco dei controlli. Un membro del team deve confermare di aver controllato la corrispondenza prima di registrare l’ingresso del visitatore.
screening_scopeLa richiesta conferma o approva una corrispondenza del controllo, e la chiave non ha l’ambito visitors:screening (oppure il membro del team indicato in X-Acting-User non decide sulle visite).

Elenchi di controllo del flusso di lavoro

Una sede con vFound Enterprise può impostare i passaggi che il suo personale conferma in un momento chiave: registrare, consegnare, donare o smaltire un oggetto ritrovato; consegnare o restituire un pacco; registrare il deposito o riconsegnare a Checkroom; consegnare o riprendere un’attrezzatura; e registrare l’ingresso o l’uscita di un visitatore. Finché ne vale uno, queste richieste accettano un campo checklist: [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}], oppure un oggetto che associa ogni chiave a true o al testo di una nota. Lo accettano 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 e POST /visitors/{id}/sign-out. Senza i passaggi richiesti la risposta è 422 con il codice checklist_incomplete e un oggetto checklist che indica i passaggi ancora da confermare, e non cambia nulla. Quando non vale alcun elenco di controllo, il campo viene ignorato. Gli elenchi completati, con chi li ha confermati e quando, sono in checklists nelle risposte del singolo oggetto, richiesta, pacco, ticket, consegna e visita.

CodiceChe cosa significa
checklist_incomplete422: un elenco di controllo del flusso di lavoro si applica a questo passaggio e i suoi passaggi richiesti non sono confermati.

Anche i nuovi tentativi con un’intestazione Idempotency-Key possono rispondere con un code:

CodiceChe cosa significa
idempotency_key_invalid400: l’intestazione non è composta da 1 a 191 caratteri ASCII visibili.
idempotency_key_reused422: questa chiave è già stata usata per una richiesta diversa.
idempotency_in_progress409: la prima richiesta con questa chiave è ancora in corso. Riprova a breve.
offline_in_progressLa prima copia di questa azione offline è ancora in salvataggio. Il dispositivo la invia di nuovo a breve.

Anche una richiesta che indica un membro del team in X-Acting-User può rispondere con un code:

CodiceChe cosa significa
acting_user_refused403: l’intestazione non indica esattamente un membro attivo del team di questa sede, oppure la chiave è un collegamento creato accedendo.
acting_user_role403: il membro del team indicato non può usare l’ambito di questa operazione con il suo ruolo nella sede.
Domande o un caso d’uso che dovremmo supportare? Scrivici. Leggiamo ogni messaggio.