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_…"
| Ambito | Consente | Endpoint |
|---|---|---|
items:read | Leggere gli oggetti ritrovati, le categorie e i trasferimenti tra sedi | GET /items, /items/{id}, /categories, /item-transfers |
items:write | Aggiungere e aggiornare gli oggetti ritrovati, e inviarli o riceverli tra sedi | POST /items, PATCH /items/{id}, POST /item-transfers e le relative azioni cancel e receive |
claims:write | Registrare le verifiche di proprietà fatte da persone, le decisioni, l’approvazione del rilascio e il ritiro | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | Creare segnalazioni degli ospiti per un contact center | POST /lost-reports |
claims:read | Leggere le richieste, con i dati di contatto del richiedente | GET /claims, /claims/{id} |
lost_reports:read | Leggere le segnalazioni di smarrimento degli ospiti | GET /lost-reports |
analytics:read | Leggere il riepilogo delle analisi | GET /analytics |
parcels:read | Leggere i pacchi, con nome ed e-mail di ogni destinatario | GET /parcels, /parcels/{id} |
parcels:write | Registrare, consegnare, restituire e inviare promemoria | POST /parcels e le relative azioni |
checkroom:read | Leggere ticket, postazioni, eventi, la coda d’uscita e i report | GET sotto /checkroom |
checkroom:write | Registrare il deposito, riconsegnare, segnare come pronto e gestire postazioni o eventi | POST e PUT sotto /checkroom |
loans:read | Leggere le attrezzature e chi le ha | GET /loans, /loans/items e una singola voce di ciascuno |
loans:write | Aggiungere attrezzature, consegnarle, prorogare e riprendere | POST e PATCH sotto /loans |
visitors:read | Leggere le visite | GET /visitors, /visitors/{id} |
visitors:write | Invitare, registrare ingresso e uscita, annullare, inviare un pass | POST /visitors e le relative azioni |
visitors:screening | Confermare 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 nome | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | Leggere l’elenco delle persone | GET /people, /people/{id} |
people:write | Aggiungere, aggiornare, sincronizzare e rimuovere persone | POST, PATCH e DELETE sotto /people |
stays:read | Leggere il contesto privato dei soggiorni in hotel e la cronologia delle correzioni | GET /stays, /stays/{stay} |
stays:write | Aggiungere o aggiornare in modo idempotente il contesto di un soggiorno da un sistema alberghiero | POST /stays |
school:read | Leggere dalla segreteria scolastica gli ingressi in ritardo e le uscite anticipate degli alunni | GET /school/movements |
school:write | Aggiungere o aggiornare gli alunni dal sistema informativo della scuola | PUT /school/pupils |
queue:read | Leggere le code, i ticket, gli orari prenotati, i messaggi, i dati dei sondaggi e il report di Queue | GET sotto /queue |
queue:write | Aggiungere persone a una coda, chiamarle, chiudere i loro ticket, prenotare e annullare orari e scrivere alle persone in coda | POST sotto /queue |
webhooks:manage | Iscrivere e rimuovere gli indirizzi webhook propri della chiave, per gli eventi i cui dati la chiave può leggere | GET, 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.
| Sistema | Che cosa legge vFound | Aree di vFound |
|---|---|---|
| Cloudbeds | Contesto 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 Flex | ID 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 ID | ID 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.
Oggetti
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/items | Oggetti, 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/categories | I nomi delle categorie che un oggetto può usare. | items:read |
| POST/items | Aggiunge 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-transfers | Oggetti 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-transfers | Invia 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}/cancel | La sede che invia riprende l’oggetto prima che venga ricevuto. | items:write |
| POST/item-transfers/{id}/receive | La 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 percorso | Che cosa fa | Ambito |
|---|---|---|
| GET /lost-found/context-schema | Legge 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-settings | Legge le impostazioni facoltative del banco. | lost_reports:read |
| PUT /lost-found/desk-settings | Sostituisce le impostazioni del banco; solo titolare o responsabile. Le nuove impostazioni di posta sono disattivate per impostazione predefinita. | lost_reports:write |
| GET /checkroom/desk-settings | Legge le impostazioni facoltative del banco. | checkroom:read |
| PUT /checkroom/desk-settings | Sostituisce le impostazioni del banco; solo titolare o responsabile. Le nuove impostazioni di posta sono disattivate per impostazione predefinita. | checkroom:write |
| GET /lost-found/counts | Elenca le ultime 30 sessioni di conteggio con scansione. | items:read |
| POST /lost-found/counts | Registra 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}/scan | Registra 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}/finish | Termina un conteggio senza modificare gli oggetti. | items:write |
| GET /lost-found/queues | Elenca 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/queues | Salva 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-review | Restituisce suggerimenti deterministici su completezza e privacy; nessuna IA e nessuna modifica. | items:read |
| GET /checkroom/templates | Elenca 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/templates | Salva la configurazione delle postazioni di un evento senza ospiti né ticket; solo responsabile. | checkroom:write |
| POST /checkroom/templates/{id}/apply | Crea 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 percorso | Che cosa fa | Ambito |
|---|---|---|
| POST /lost-reports | Inserimento 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}/matches | Fino 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}/matches | Id 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}/verification | Registra 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}/decision | status: 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-approval | Un altro responsabile approva un rilascio accettato di alto valore, con gli stessi controlli dell’area di lavoro. | claims:write |
| GET /claims/{id}/custody | Verifica 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}/handover | Registra 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}/disposition | kind 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
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/claims | Richieste, 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.
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/stays | Elenca 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/stays | Crea 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
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/parcels | Pacchi, 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/parcels | Registra 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}/collect | Lo consegna: collected_by (obbligatorio) e una signature facoltativa (un data URL PNG). | parcels:write |
| POST/parcels/{id}/return | Lo restituisce al mittente, con una note facoltativa. | parcels:write |
| POST/parcels/{id}/remind | Invia al destinatario un promemoria per ritirarlo. | parcels:write |
| POST/parcels/tracking | Normalizza 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-queue | Persone che hanno dichiarato di essere al banco, con il numero dei loro pacchi e gli scaffali. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | Segna come servito un arrivo al banco. | parcels:write |
| POST/parcels/bulk-remind | Invia promemoria e-mail per un massimo di 200 pacchi in attesa selezionati. | parcels:write |
| POST/parcels/bulk-return | Restituisce al mittente fino a 200 pacchi in attesa selezionati. | parcels:write |
| GET/parcels/shelves | Capacità degli scaffali dei pacchi e occupazione attuale. | parcels:read |
| POST/parcels/shelves | Crea uno scaffale o ne cambia la capacità. | parcels:write |
| GET/parcels/analytics | Volume, mix di corrieri, tempo di ritiro, tasso di pacchi non ritirati e scaffali più occupati. | parcels:read |
| GET/parcels/outgoing | Pacchi in uscita pronti per un corriere o già consegnati. | parcels:read |
| POST/parcels/outgoing | Registra un pacco in uscita. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | Registra il corriere e la firma alla consegna. | parcels:write |
| GET/parcels/rounds | Giri di consegna e le loro fermate. | parcels:read |
| POST/parcels/rounds | Crea un giro per il campus o l’ufficio dai pacchi in attesa. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | Completa una fermata con il nome del destinatario e la firma. | parcels:write |
| GET/parcels/couriers | Corrieri 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
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/checkroom/tickets | Ticket, 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/tickets | Registra 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-back | Lo 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/stations | Elenca le postazioni di Checkroom della sede, gli intervalli di numeri e i luoghi di conservazione. | checkroom:read |
| POST/checkroom/stations | Crea 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/events | Elenca gli eventi di Checkroom recenti e futuri. | checkroom:read |
| POST/checkroom/events | Crea 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-queue | Ticket i cui ospiti hanno chiesto al banco di preparare le loro cose. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | Segna come pronto un ticket in attesa e avvisa l’ospite. | checkroom:write |
| GET/checkroom/report | Volume dei ticket, ore di punta, tempo di restituzione e tariffe per metodo e per personale. | checkroom:read |
| GET/checkroom/export | Scarica 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.
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/queue/lines | Code 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/tickets | Ticket 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/report | Ticket, 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/tickets | Aggiunge una persona a una coda, come fa il banco. | queue:write |
| POST/queue/call-next | Chiama 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}/call | Chiama una persona scelta a uno sportello. | queue:write |
| POST/queue/tickets/{id}/served | Segna come servita la persona allo sportello. | queue:write |
| POST/queue/tickets/{id}/no-show | Segna come assente una persona chiamata che non si è presentata. | queue:write |
| POST/queue/tickets/{id}/remove | Toglie una persona dalla coda. | queue:write |
| GET/queue/bookings | Orari prenotati, i più vicini per primi, con from, to, line, status e paginazione. Mai l’e-mail della persona. | queue:read |
| POST/queue/bookings | Prenota 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}/cancel | Annulla un orario prenotato; la persona riceve un’e-mail che le dice che il team l’ha annullato. | queue:write |
| POST/queue/bookings/{id}/arrived | Registra l’arrivo di una persona con orario prenotato; il suo ticket viene collocato in base all’orario prenotato. | queue:write |
| POST/queue/tickets/{id}/arrived | Segna come presente una persona che si è messa in coda prima di arrivare. | queue:write |
| GET/queue/tickets/{id}/messages | I 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}/messages | Scrive a una persona in coda (body, da 1 a 500 caratteri), come il membro del team della chiave. | queue:write |
| GET/queue/survey | Dati 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/performance | Dati semplici per ogni membro del team negli stessi giorni del report. Nessun punteggio e nessuna classifica. | queue:read |
| GET/queue/lines/{id}/slots | Gli orari prenotabili aperti di una coda, come li offre la sua pagina di prenotazione. | queue:read |
| POST/queue/join | Prende 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/lookup | Trova i ticket dal numero che l’ospite ha. | queue:read |
| GET/queue/tickets/{id}/status | Che cosa mostra la pagina del ticket dell’ospite: posizione, stima e frase. | queue:read |
| GET/queue/tickets/{id}/history | I 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/history | Visite 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/insights | Conteggi 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-data | I 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
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/loans | Attrezzature 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/loans | Consegna 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}/extend | Dà più tempo: un nuovo due_at. L’utilizzatore riceve per e-mail il nuovo orario. | loans:write |
| POST/loans/{id}/return | Lo 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/returns | Riprende 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/items | Tutto 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}/tickets | Ticket inviati al Jira, Zendesk o ServiceNow della sede per questo articolo (beta), con lo stato letto per ultimo. | loans:read |
| POST/loans/items | Aggiunge 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}/tag | Se un tag NFC o RFID è collegato e le ultime quattro cifre esadecimali del suo numero di serie. | loans:read |
| PUT/loans/items/{id}/tag | Collega 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}/tag | Rimuove il tag dell’articolo. | loans:write |
| POST/loans/checkouts | Consegna 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/kits | Gruppi salvati di attrezzature che di solito vengono consegnate insieme. | loans:read |
| POST/loans/kits | Salva 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/trainings | Le 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}/holders | Chi ha una formazione, da quando e fino a quando, e se è scaduta. | loans:read |
| POST/loans/trainings/{id}/holders | Assegna 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-types | I 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}/members | Chi ha un tipo di utilizzatore. | loans:read |
| POST/loans/borrower-types/{id}/members | Assegna 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/credits | Crediti 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/credits | Assegna crediti di prenotazione a una persona, o ne toglie con un numero negativo (titolari e responsabili). | loans:write |
| GET/loans/holds | Blocchi attivi sul ritiro: finché uno dura, alla persona non viene consegnato nulla e non può prenotare. | loans:read |
| POST/loans/holds | Mette 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}/lift | Toglie un blocco. | loans:write |
| GET/loans/spaces | Stanze, 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/spaces | Aggiunge 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/availability | Ogni 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}/book | Prenota 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}/parts | Aggiunge 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-part | Toglie una parte da una prenotazione di kit o carrello; l’ultima parte viene annullata insieme alla prenotazione. | loans:write |
| GET/loans/places | I 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-tree | Le 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-models | Modelli 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}/links | I collegamenti di un articolo con altri articoli della stessa sede: funziona con, un’alternativa, sostituisce. | loans:read |
| POST/loans/items/{id}/links | Collega 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}/move | Sposta 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-readings | Letture del contatore inserite per un articolo, le più recenti per prime. | loans:read |
| POST/loans/items/{id}/meter-readings | Registra 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/contracts | Contratti con i fornitori collegati agli articoli che coprono (titolari e responsabili). | loans:read |
| GET/loans/resale | Articoli 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/points | Punti di ritiro e di riconsegna che una prenotazione può indicare. | loans:read |
| POST/loans/points | Aggiunge 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/projects | Progetti a cui può appartenere una prenotazione. Nulla viene ritirato per un progetto finché non è approvato. | loans:read |
| POST/loans/projects | Aggiunge un progetto (in attesa di approvazione). | loans:write |
| POST/loans/projects/{id}/decision | Approva o rifiuta un progetto (titolari e responsabili). | loans:write |
| GET/loans/risk-assessments | Valutazioni dei rischi in attesa di revisione (o per status), con le risposte dell’utilizzatore. | loans:read |
| POST/loans/risk-assessments/{id}/review | Approva o rifiuta una valutazione dei rischi (titolari e responsabili). Un rifiuto annulla la prenotazione. | loans:write |
| POST/loans/reservation-series | Prenota 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}/move | Sposta 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/waitlist | Persone in attesa di un orario che è stato preso, per status (waiting per impostazione predefinita). | loans:read |
| POST/loans/waitlist | Aggiunge 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}/cancel | Toglie una persona dalla lista d’attesa. | loans:write |
| GET/loans/fees | Il 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/party | Un utilizzatore (person_id o party_key): quanto deve per valuta, cauzioni custodite, voci e fatture. | loans:read |
| GET/loans/fees/billing-codes | Addebitato, condonato, saldato e ancora dovuto per codice di fatturazione e valuta in un periodo; format=csv per un CSV. | loans:read |
| POST/loans/fees/charges | Registra 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/payments | Registra 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/deposits | Registra una cauzione incassata dalla sede; custodita finché non viene restituita o incamerata. | loans:write |
| POST/loans/fees/deposits/{id}/return | Restituisce una cauzione custodita. | loans:write |
| POST/loans/fees/deposits/{id}/keep | Incamera 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}/waive | Condona ciò che un addebito richiede ancora (titolari e responsabili, con un motivo). | loans:write |
| POST/loans/fees/{id}/void | Annulla 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}/fees | Ciò 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-fine | Aggiunge la multa per ritardo per una consegna rientrata in ritardo, calcolata da quando è rientrata. Una volta per consegna. | loans:write |
| GET/loans/invoices | Fatture, prima il numero più recente. | loans:read |
| POST/loans/invoices | Emette una fattura numerata per gli addebiti aperti di un utilizzatore in una valuta. | loans:write |
| POST/loans/invoices/{id}/void | Annulla una fattura (titolari e responsabili, con un motivo); reissue mette i suoi addebiti aperti su una nuova che la sostituisce. | loans:write |
| GET/loans/reservations | Prenotazioni per orario di inizio, filtrabili facoltativamente per status o from. | loans:read |
| POST/loans/reservations | Riserva 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}/approve | Approva 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}/cancel | Annulla una prenotazione in attesa, approvata o pronta. | loans:write |
| POST/loans/reservations/{id}/pickup | Consegna in modo atomico l’articolo riservato e chiude la prenotazione come ritirata. | loans:write |
| POST/loans/reservation-groups | Riserva 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/downtimes | Finestre 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/downtimes | Aggiunge 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/closures | Giorni in cui il banco delle attrezzature è chiuso e che non sono ancora finiti. | loans:read |
| POST/loans/closures | Aggiunge 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/rules | Impostazioni 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/rules | Crea o sostituisce la regola di una categoria. I campi delle regole di prenotazione omessi mantengono i valori salvati. | loans:write |
| GET/loans/timeline | Controlli 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/warranties | Date 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/utilization | Ore 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/maintenance | Cronologia 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/maintenance | Registra 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-plans | Piani 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-plans | Aggiunge 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/costs | Costo di manutenzione, riparazione e pulizia per articolo, dalle voci concluse e dagli ordini di lavoro completati. | loans:read |
| GET/loans/items/{id}/lifecycle | Il 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}/lifecycle | Salva 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}/dispose | Registra 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}/dispose | Annulla una dismissione fatta per errore; l’articolo torna disponibile. | loans:write |
| GET/loans/valuation | Il 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/import | Controlla 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/import | Controlla o aggiunge ordini di lavoro aperti da un CSV con le colonne documentate (titolari e responsabili). | loans:write |
| GET/loans/maintenance/planner | Lavori programmati e ordini di lavoro aperti per giorno della sede fino a 62 giorni, facoltativamente per un solo tecnico. | loans:read |
| GET/loans/funding | Che 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/substances | Il 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/substances | Aggiunge 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/licences | Licenze 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/licences | Aggiunge 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/expiries | Assicurazioni e licenze in scadenza o già scadute (titolari e responsabili). | loans:read |
| GET/loans/stocktakes | Inventari recenti delle attrezzature con i conteggi di scansioni e di mancanti. | loans:read |
| POST/loans/stocktakes | Avvia 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}/scan | Scansiona un’etichetta di attrezzatura, un codice inventario o un numero di serie nell’inventario aperto. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | Conta 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}/assign | Assegna l’inventario aperto a un membro del team perché lo conti (assigned_to), o a nessuno (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | Termina l’inventario e restituisce l’elenco degli articoli mancanti. | loans:write |
| GET/loans/stocktake-schedules | Inventari che si aprono da soli, una volta o ripetuti. | loans:read |
| POST/loans/stocktake-schedules | Programma 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-seen | Dove 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/transfers | Trasferimenti di attrezzature in entrata e in uscita per questa sede. | loans:read |
| POST/loans/transfers | Prepara le attrezzature per un’altra sede autorizzata dello stesso gruppo di clienti. | loans:write |
| POST/loans/transfers/{id}/send | Registra che le attrezzature preparate hanno lasciato la sede di origine. | loans:write |
| POST/loans/transfers/{id}/receive | Riceve le attrezzature nella sede di destinazione con il loro luogo e il loro stato all’arrivo. | loans:write |
| POST/loans/transfers/{id}/cancel | Annulla un trasferimento preparato prima della spedizione. | loans:write |
| POST/loans/transfers/{id}/reject | Rifiuta un trasferimento preparato nella sede di destinazione prima della spedizione. | loans:write |
| POST/loans/transfers/{id}/exception | Registra un problema mentre le attrezzature sono in transito. | loans:write |
| POST/loans/import | Anteprima o importazione fino a 5,000 righe CSV con le intestazioni di vFound, Snipe-IT, Sortly o Cheqroom. | loans:write |
Visitors
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/visitors | Visite, 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/visitors | Invita 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-in | Registra 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-in | Registra 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-out | Ne registra l’uscita. | visitors:write |
| POST/visitors/{id}/cancel | Annulla un invito. | visitors:write |
| POST/visitors/{id}/send-pass | Invia di nuovo il pass per e-mail. | visitors:write |
| POST/visitors/{id}/approve | Approva una visita in attesa e invia il pass. | visitors:write |
| POST/visitors/{id}/deny | Rifiuta una visita in attesa. | visitors:write |
| GET/visitors/{id}/badge | Scarica il badge stampabile dal browser. Scegli size 4x3, brother o dymo. | visitors:read |
| GET/visitors/{id}/card | Se 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}/card | Assegna 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}/card | Ritira la tessera. | visitors:write |
| GET/visitors/{id}/assets | Gli oggetti consegnati alla visita, digitati a mano. | visitors:read |
| POST/visitors/{id}/assets | Registra un oggetto consegnato alla visita, con un tag facoltativo. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | Segna un oggetto come restituito. | visitors:write |
| GET/visitor-assets/not-returned | Oggetti consegnati ai visitatori e non ancora restituiti, i più recenti per primi. | visitors:read |
| GET/visitors/{id}/fast-track | Se 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-track | Assegna a un visitatore che torna un codice di accesso rapido che dura days (da 1 a 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | Ritira il codice. | visitors:write |
| GET/visitor-types | Elenca 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-types | Crea 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-call | Ottiene 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-call | Avvia 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}/finish | Termina l’appello attivo e ne conserva il report. | visitors:write |
| GET/staff-attendance | Elenca 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-attendance | Registra 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-presence | Invia 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}/catering | Crea, 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/spaces | Elenca le scrivanie, le sale riunioni e i posti auto che le persone possono prenotare nella sede. | visitors:read |
| GET/workplace/free | Trova gli spazi liberi per un intero periodo (al massimo 7 giorni), escludendo una scrivania riservata a un’altra persona. | visitors:read |
| GET/workplace/bookings | Elenca 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/bookings | Prenota 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}/cancel | Annulla una prenotazione, oppure con scope following o series i suoi orari successivi. | visitors:write |
| POST/workplace/bookings/{id}/check-in | Registra la presenza per una prenotazione, da 15 minuti prima dell’inizio fino alla fine. | visitors:write |
| POST/visitors/{id}/room | Prenota una sala riunioni per una visita, dall’orario della visita; la sala segue la visita. | visitors:write |
| GET/appointment-pages | Elenca le pagine di appuntamento della sede, i loro orari e se ciascuna è aperta ai visitatori adesso. | visitors:read |
| GET/visitor-roll-call/archive | Elenca 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}/people | Aggiunge una persona (un dipendente, altro o un appaltatore) all’appello in corso. | visitors:write |
| POST/visitor-roll-call/{id}/scan | Segna un visitatore al sicuro dal suo link o codice del pass, in un punto di raccolta. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | Registra una zona come controllata e libera o come con persone al suo interno. | visitors:write |
| POST/visitor-roll-call/{id}/messages | Invia 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}/messages | La 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-alerts | Un 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-alerts | Chiedi aiuto in modo discreto: i membri del team scelti per questo vengono avvisati; nessun visitatore vede nulla. | visitors:write |
| GET/visitor-kiosks | Elenca i dispositivi chiosco abbinati, in attesa e revocati. | visitors:read |
| POST/visitor-kiosks/pairing | Crea 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}/settings | Modifica 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-analytics | Totali per giorno, ora, tipo e referente, più la permanenza media dell’ultimo anno. | visitors:read |
| GET/visitor-registration | Ottiene il link di auto-registrazione della sede e se è attivo. | visitors:read |
| GET/school/movements | Ingressi 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/pupils | Aggiunge 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.
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/people | L’elenco, per nome. Filtri: search (nome, e-mail, unità o riferimento), updated_since. | people:read |
| GET/people/{id} | Una persona. | people:read |
| POST/people | Aggiunge qualcuno: name (obbligatorio), email, unit, reference e language per le sue e-mail. | people:write |
| POST/people/upsert | Aggiunge 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/export | Scarica l’elenco completo delle persone come CSV a prova di formule. | people:read |
| POST/people/{id}/send-my-vfound | Invia per e-mail a una persona attiva la pagina firmata con i suoi pacchi, visitatori e attrezzature collegati. | people:write |
| GET/people/sync-source | Mostra la directory CSV salvata e l’ultimo risultato di sincronizzazione. | people:read |
| PUT/people/sync-source | Salva un url CSV HTTPS pubblico e mode (upsert o mirror). | people:write |
| DELETE/people/sync-source | Rimuove il collegamento e mantiene le persone già importate. | people:write |
| POST/people/sync-source/run | Esegue 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.
| Evento | Quando | Dati |
|---|---|---|
item.created | Viene aggiunto un oggetto ritrovato | Oggetto |
item.updated | Cambiano il suo stato, titolo, luogo, categoria, data di conservazione o visibilità della foto | Oggetto |
item.transfer_sent | Un oggetto ritrovato viene inviato a un’altra sede del gruppo (entrambe le sedi lo ricevono) | Trasferimento di oggetto |
item.transfer_cancelled | La sede che invia lo riprende prima che arrivi | Trasferimento di oggetto |
item.transfer_received | La sede ricevente conferma che è arrivato | Trasferimento di oggetto |
claim.created | Un ospite invia una richiesta | Richiesta |
item.disposition_recorded | Un oggetto viene donato o smaltito | Oggetto |
item.match_updated | Cambia un verdetto di abbinamento IA salvato; report_id, item_id, label e reason | Coppia di corrispondenza |
lost_report.match_updated | Cambia un verdetto di abbinamento IA salvato; report_id, item_id, label e reason | Coppia di corrispondenza |
claim.ownership_reviewed | Un responsabile registra una verifica di proprietà; recupera la custodia per la cronologia delle verifiche | Richiesta |
claim.decision_recorded | Una richiesta viene accettata o rifiutata | Richiesta |
claim.release_approved | Un altro responsabile approva il rilascio | Richiesta |
claim.handover_recorded | Il ritiro fisico chiude una richiesta pronta per il ritiro | Richiesta |
claim.status_changed | Una richiesta passa a un nuovo stato | Richiesta |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | Un ospite segnala uno smarrimento | Segnalazione di smarrimento |
parcel.logged | Un pacco viene registrato al banco o tramite l’API | Pacco |
parcel.updated | Cambia uno qualsiasi dei suoi dettagli al banco, come il destinatario, il numero di tracciamento o lo scaffale | Pacco |
parcel.reminded | Al destinatario viene inviato un promemoria, dal banco o automaticamente | Pacco |
parcel.collected | Un pacco viene consegnato | Pacco |
parcel.returned | Un pacco viene restituito al mittente | Pacco |
parcel.recipient_arrived | Un destinatario dice di essere al banco | Voce della coda di ritiro |
parcel.reminders_snoozed | Un destinatario mette in pausa i suoi promemoria | Persona e numero di pacchi |
parcel.held | Un destinatario imposta una data di sospensione | Persona, data e numero di pacchi |
parcel.proxy_created | Un destinatario invia per e-mail a un delegato un codice di ritiro | Persona, delegato e scadenza |
parcel.pickup_served | Il banco segna un arrivo come servito | Voce della coda di ritiro |
parcel.escalated | Un pacco in attesa raggiunge l’anzianità di escalation della sede | Pacco |
parcel.outgoing_logged | Un pacco in uscita viene registrato | Pacco in uscita |
parcel.outgoing_handed_over | Un pacco in uscita viene consegnato a un corriere | Consegna in uscita |
parcel.round_created | Viene creato un giro di consegna | Riepilogo del giro |
parcel.round_delivered | Viene completata una fermata di un giro di consegna | Id del giro, della fermata e dei pacchi |
checkroom.checked_in | Qualcosa viene registrato in deposito e riceve un numero | Ticket |
checkroom.handed_back | Viene riconsegnato | Ticket |
checkroom.left | La serata viene chiusa con l’oggetto ancora in Checkroom | Ticket |
checkroom.self_checkin_started | Un ospite avvia un ticket da un chiosco abbinato | Ticket |
checkroom.ready_requested | Un ospite chiede al banco di preparare le sue cose | Ticket |
checkroom.ready | Il banco segna come pronte le cose di un ospite | Ticket |
checkroom.station_created | Viene creata una postazione di Checkroom | Postazione |
checkroom.station_updated | Cambia una postazione di Checkroom | Postazione |
checkroom.event_created | Viene creato un evento di Checkroom | Evento |
checkroom.event_updated | Cambia un evento di Checkroom | Evento |
loan.checked_out | Un articolo viene consegnato | Consegna |
loan.due_soon | L’orario di scadenza è a meno di due ore, una volta per orario di scadenza | Consegna |
loan.overdue | L’orario di scadenza passa e l’articolo non è rientrato, una volta per orario di scadenza | Consegna |
loan.extended | Cambia il suo orario di scadenza | Consegna |
loan.returned | Rientra al banco | Consegna |
loan.lost | Viene registrato come non restituito | Consegna |
loan.checkout_created | Viene creata una consegna atomica di più articoli | Consegna, con l’eventuale scorta sulla stessa ricevuta in stock |
loan.self_checkout | Un utilizzatore completa la consegna al chiosco | Consegna |
loan.kit_created | Viene creato un kit di attrezzature salvato | Kit |
loan.kit_updated | Cambia un kit di attrezzature salvato | Kit |
loan.reservation_requested | Una prenotazione attende l’approvazione | Prenotazione |
loan.reservation_created | Una prenotazione viene confermata subito | Prenotazione |
loan.reservation_approved | Una prenotazione in attesa viene approvata | Prenotazione |
loan.reservation_ready | Le attrezzature prenotate sono pronte per il ritiro | Prenotazione |
loan.reservation_cancelled | Una prenotazione viene annullata | Prenotazione |
loan.reservation_collected | Le attrezzature prenotate vengono consegnate | Consegna |
loan.extension_requested | Un utilizzatore chiede più tempo | Consegna |
loan.problem_reported | Un utilizzatore segnala un problema a un’attrezzatura | Consegna |
loan.rule_updated | Cambia la regola di consegna di una categoria | Regola |
loan.maintenance_logged | Viene registrata una manutenzione | Manutenzione |
loan.maintenance_due | Una manutenzione programmata scade | Manutenzione |
loan.service_due | Un piano di manutenzione ricorrente scade (per data, ore di consegna o numero di consegne), una volta per ciclo | Manutenzione |
loan.work_order_opened | Viene aperto un ordine di lavoro, dal personale o da una restituzione per cui la sede chiede di aprirne uno | Manutenzione |
loan.work_order_closed | Un ordine di lavoro viene completato o annullato | Manutenzione |
loan.item_disposed | Un articolo viene dismesso (venduto, rottamato, donato, riciclato, perso o rubato) | Equipment |
loan.stocktake_started | Parte un inventario delle attrezzature | Inventario |
loan.stocktake_completed | Termina un inventario delle attrezzature | Inventario |
loan.transfer_prepared | Una sede autorizzata prepara le attrezzature da spostare | Trasferimento |
loan.transfer_sent | Le attrezzature preparate lasciano la sede di origine | Trasferimento |
loan.transfer_received | La sede di destinazione riceve le attrezzature | Trasferimento |
loan.transfer_rejected | La sede di destinazione rifiuta un trasferimento preparato | Trasferimento |
loan.transfer_cancelled | La sede di origine annulla un trasferimento preparato | Trasferimento |
loan.transfer_exception | Un trasferimento in transito richiede attenzione | Trasferimento |
loan.transfer_lost | La sede di origine chiude un trasferimento mai arrivato | Trasferimento |
loan.charge_recorded | Viene registrata una multa, un danno, una sostituzione, un uso o un altro addebito | Voce di addebito |
loan.charge_waived | Un responsabile condona ciò che un addebito richiede ancora, con un motivo | Voce di addebito |
loan.payment_recorded | Il personale registra denaro che la sede ha incassato direttamente (vFound non elabora mai un pagamento) | Voce di addebito |
loan.payment_voided | Un responsabile annulla un pagamento registrato per errore | Voce di addebito |
loan.deposit_recorded | Il personale registra una cauzione incassata dalla sede | Voce di addebito |
loan.deposit_resolved | Una cauzione custodita viene restituita o incamerata | Voce di addebito |
loan.invoice_issued | Viene emessa una fattura per gli addebiti di un utilizzatore | Fattura |
loan.invoice_voided | Un responsabile annulla una fattura, con un motivo | Fattura |
loan.quote_accepted | Il team accetta un preventivo e le sue prenotazioni vengono fatte | Preventivo |
loan.payment_request_created | Il team registra una richiesta di pagamento (non viene inviato nulla alla persona) | Richiesta di pagamento |
loan.payment_request_paid | I pagamenti registrati rispetto a una richiesta la coprono per intero | Richiesta di pagamento |
loan.delivery_done | Una consegna o un ritiro viene segnato come completato | Consegna |
loan.items_imported | Si completa un’importazione CSV delle attrezzature | Conteggi |
visit.expected | Un visitatore viene invitato | Visita |
visit.signed_in | Un visitatore registra l’ingresso, al banco o dal tuo cartello QR | Visita |
visit.host_confirmed | Il banco conferma chi un visitatore registrato da solo è venuto a trovare | Visita |
visit.signed_out | Ne viene registrata l’uscita, al banco, dal suo pass o automaticamente dopo la fine della giornata | Visita |
visit.cancelled | Un invito viene annullato | Visita |
visit.approval_requested | Una visita attende l’approvazione del personale | Visita |
visit.approved | Una visita in attesa viene approvata | Visita |
visit.denied | Una visita in attesa viene rifiutata | Visita |
visit.host_replied | Un referente risponde dal suo link privato | Visita |
visit.roll_call_started | Parte un appello in tempo reale (un’emergenza, un’esercitazione o un avviso) | Riepilogo dell’appello |
visit.roll_call_completed | Termina un appello in tempo reale | Riepilogo dell’appello |
visitor_type.created | Viene creato un tipo di visitatore | Tipo di visitatore |
visitor_type.updated | Cambia un tipo di visitatore | Tipo di visitatore |
visitor_type.deactivated | Un tipo di visitatore viene disattivato | Tipo di visitatore |
visitor_agreement.signed | Un visitatore ha firmato un documento di accordo, con un link alla copia firmata che funziona per sette giorni | Firma dell’accordo |
kiosk.paired | Un chiosco per visitatori viene abbinato | Chiosco |
kiosk.revoked | Un chiosco per visitatori viene revocato | Chiosco |
courier.signed_in | Un corriere in visita viene registrato in Parcels | Corriere |
courier.signed_out | Un corriere in visita se ne va | Corriere |
staff.signed_in | Una persona dell’elenco del personale registra l’ingresso, in ufficio o da remoto | Presenza del personale |
staff.signed_out | Una persona dell’elenco del personale registra l’uscita, o ne viene registrata automaticamente l’uscita | Presenza del personale |
person.created | Viene aggiunta una persona | Persona |
person.updated | Una persona viene modificata | Persona |
person.deactivated | Il provisioning della directory disattiva una persona | Persona |
person.deleted | Una persona viene rimossa | Persona |
people.sync.completed | Si completa una sincronizzazione CSV collegata | Conteggi |
people.sync.failed | Una sincronizzazione CSV collegata fallisce in sicurezza | Errore |
report.delivered | Un 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_joined | Una persona si mette in coda, dal telefono, da un chiosco, dal banco o dall’API | Ticket di coda |
queue.ticket_called | Una persona viene chiamata a uno sportello, o chiamata di nuovo | Ticket di coda |
queue.ticket_served | Una persona viene segnata come servita | Ticket di coda |
queue.ticket_no_show | Una persona chiamata viene segnata come assente, dal team o dopo i minuti della coda | Ticket di coda |
queue.ticket_left | Una persona esce dalla coda dal suo ticket, o il team la toglie | Ticket di coda |
queue.ticket_transferred | Una persona viene spostata in un’altra coda o a un altro sportello | Ticket di coda |
queue.ticket_closed | Un ticket ancora aperto alla fine della giornata della sede, o in una coda archiviata, viene chiuso | Ticket di coda |
queue.booking_created | Una persona prenota un orario dalla pagina degli orari prenotati di una coda, o lo prenota l’API | Prenotazione di Queue |
queue.booking_cancelled | Un orario prenotato viene annullato dalla persona, dal team o dall’API | Prenotazione di Queue |
queue.ticket_arrived | Una persona che si è messa in coda prima di arrivare dice di essere qui, o il team la segna come arrivata | Ticket di coda |
queue.message_received | Una persona in coda scrive al team dalla pagina del suo ticket; l’evento non contiene le parole | Messaggio di Queue |
queue.message_sent | Il team scrive a una persona in coda; l’evento non contiene le parole | Messaggio di Queue |
queue.survey_answered | Una persona servita risponde al sondaggio; l’evento contiene la valutazione e mai il commento | Risposta 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.
| Richiesta | Che cosa fa | Ambito |
|---|---|---|
| GET/webhooks | Gli indirizzi creati da questa chiave e i loro eventi. | webhooks:manage |
| POST/webhooks | Aggiunge 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_…"}}}}
| Strumento | Che cosa fa | Ambito |
|---|---|---|
search_found_items | Cerca oggetti ritrovati per parole come “iPhone nero” | items:read |
list_expected_visitors | Visitatori invitati e non ancora arrivati | visitors:read |
list_visitors_on_site | Visitatori presenti in questo momento | visitors:read |
list_visitor_types | Tipi di visitatore e le loro regole | visitors:read |
visitor_analytics | Totali, andamenti e permanenza media dei visitatori | visitors:read |
visitor_registration_link | Il link di auto-registrazione della sede | visitors:read |
list_couriers_on_site | Corrieri registrati tramite Visitors | parcels:read |
list_waiting_parcels | Pacchi in attesa di ritiro | parcels:read |
detect_parcel_tracking | Normalizza un numero di tracciamento e rileva il suo corriere | parcels:read |
parcel_pickup_queue | Persone in attesa al banco dei pacchi | parcels:read |
parcel_shelves | Capacità e occupazione degli scaffali dei pacchi | parcels:read |
parcel_analytics | Volume dei pacchi, corrieri e rendimento dei ritiri | parcels:read |
list_outgoing_parcels | Pacchi in uscita e il loro stato di consegna | parcels:read |
list_parcel_rounds | Giri di consegna dei pacchi e fermate | parcels:read |
list_checkroom_exit_queue | Ticket i cui ospiti attendono all’uscita | checkroom:read |
mark_checkroom_ready | Segna come pronto un ticket in attesa e avvisa l’ospite | checkroom:write |
list_checkroom_stations | Postazioni di Checkroom e intervalli di numeri | checkroom:read |
list_checkroom_events | Eventi di Checkroom recenti e futuri | checkroom:read |
checkroom_report | Volume di Checkroom, tempo di restituzione e totali delle tariffe | checkroom:read |
list_queue_lines | Code, persone in attesa e attesa stimata adesso | queue:read |
list_queue_waiting | Persone in attesa oggi, in ordine di chiamata | queue:read |
queue_report | Totali di Queue e mediana dei minuti di attesa e di servizio | queue:read |
call_next_in_queue | Chiama la persona successiva a uno sportello | queue:write |
mark_queue_ticket_served | Segna come servita la persona allo sportello | queue:write |
list_overdue_equipment | Attrezzature oltre l’orario di scadenza e chi le ha | loans:read |
list_equipment_kits | Gruppi salvati di attrezzature | loans:read |
create_equipment_kit | Salva un kit di attrezzature riutilizzabile senza consegnarlo | loans:write |
list_equipment_reservations | Prenotazioni per orario e stato | loans:read |
reserve_equipment | Riserva un articolo o una categoria senza consegnarli | loans:write |
book_repeating_reservation | Prenota un articolo, una categoria o uno spazio ogni giorno o ogni settimana | loans:write |
move_reservation | Sposta una prenotazione a nuovi orari o a un altro articolo della sua categoria | loans:write |
list_waitlist | Le persone in attesa di un orario che è stato preso | loans:read |
join_waitlist | Aggiunge una persona alla lista d’attesa | loans:write |
list_space_bookings | Ogni stanza, scrivania o posto auto e le sue prenotazioni tra due orari | loans:read |
book_space | Prenota una stanza o uno spazio per una persona e un orario; non viene mai consegnato | loans:write |
list_equipment_rules | Regole di consegna della sede e delle categorie | loans:read |
save_equipment_rule | Crea o sostituisce la regola di una categoria | loans:write |
list_equipment_maintenance | Cronologia di manutenzione delle attrezzature e lavori in arrivo | loans:read |
list_equipment_service_plans | Piani ricorrenti di manutenzione, taratura, prova di sicurezza, ispezione e pulizia e quali sono in scadenza | loans:read |
update_equipment_work_order | Modifica o chiude un ordine di lavoro delle attrezzature | loans:write |
get_equipment_maintenance_costs | Costo di manutenzione, riparazione e pulizia per articolo | loans:read |
get_equipment_valuation | Il valore delle attrezzature a una data dopo l’ammortamento (titolari e responsabili) | loans:read |
list_equipment_substances | Il registro delle sostanze pericolose: sostanza, luogo, classi di pericolo e date di revisione (un record, nessun consiglio sulla sicurezza) | loans:read |
get_equipment_funding | Che cosa ha acquistato ciascun fondo, contributo o centro di costo e quale lavoro gli è stato addebitato (titolari e responsabili) | loans:read |
get_equipment_planner | Lavori programmati e ordini di lavoro aperti per giorno della sede | loans:read |
list_equipment_licences | Licenze delle attrezzature con utenze e date di fine (titolari e responsabili) | loans:read |
get_equipment_expiries | Assicurazioni e licenze in scadenza o già scadute (titolari e responsabili) | loans:read |
log_equipment_maintenance | Registra manutenzione, taratura, una prova di sicurezza, un’ispezione, una pulizia, una riparazione o una nota | loans:write |
list_equipment_stocktakes | Inventari recenti e i loro conteggi | loans:read |
start_equipment_stocktake | Avvia un inventario | loans:write |
scan_equipment_stocktake | Registra un articolo in un inventario aperto | loans:write |
scan_many_equipment_stocktake | Conta molti codici in un inventario aperto in una volta | loans:write |
finish_equipment_stocktake | Termina un inventario e restituisce ciò che manca | loans:write |
list_equipment_transfers | Trasferimenti in entrata e in uscita senza i dati dell’utilizzatore | loans:read |
preview_equipment_import | Convalida un CSV di attrezzature senza salvarlo | loans:write |
find_person | Cerca una persona nell’elenco delle persone | people:read |
export_people | Esporta l’elenco delle persone come CSV a prova di formule | people:read |
directory_sync_status | Controlla il collegamento CSV salvato e la sua ultima esecuzione | people:read |
run_directory_sync | Esegue subito il collegamento CSV salvato | people:write |
email_my_vfound | Invia per e-mail a una persona la sua pagina privata firmata | people:write |
invite_visitor | Invita un visitatore, che riceve un pass per e-mail | visitors:write |
approve_visit | Approva la richiesta di una visita in attesa | visitors:write |
list_free_workplace_spaces | Trova scrivanie, sale riunioni o parcheggi liberi per un orario | visitors:read |
book_workplace_space | Prenota una scrivania, una sala riunioni o un posto auto per una persona | visitors:write |
request_visit_catering | Chiede il catering con una visita, tra le opzioni elencate dalla sede | visitors:write |
list_appointment_pages | Elenca le pagine di appuntamento della sede e se ciascuna è aperta ai visitatori | visitors:read |
list_staff_on_site | Elenca le persone dell’elenco del personale presenti in questo momento, in ufficio o da remoto | visitors:read |
sign_staff_in_or_out | Registra l’ingresso o l’uscita di una persona dell’elenco del personale | visitors:write |
list_visitor_assets_not_returned | Elenca gli oggetti consegnati ai visitatori che non sono ancora segnati come restituiti | visitors:read |
issue_visitor_asset | Registra un oggetto consegnato a una visita attesa o già registrata | visitors:write |
return_visitor_asset | Segna come restituito un oggetto consegnato a una visita | visitors:write |
start_roll_call | Avvia l’appello o ottiene quello attivo | visitors:write |
mark_visitor_safe | Segna un visitatore al sicuro | visitors:write |
create_kiosk_pairing | Crea un codice di abbinamento del chiosco di dieci minuti | visitors:write |
log_parcel | Registra un pacco e invia un’e-mail al destinatario | parcels:write |
remind_parcel | Ricorda a un destinatario di ritirare un pacco | parcels:write |
remind_parcels | Invia un promemoria fino a 200 destinatari di pacchi selezionati | parcels:write |
log_outgoing_parcel | Aggiunge un pacco in uscita al registro dei corrieri | parcels:write |
create_parcel_round | Crea un giro di consegna dai pacchi in attesa | parcels:write |
extend_loan | Dà più tempo a un utilizzatore | loans: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:
| Codice | Che cosa significa |
|---|---|
parcel_not_waiting | Il pacco non è più in attesa: è già stato ritirato, restituito o consegnato. |
tracking_duplicate | Un pacco con questo numero di tracciamento è già in attesa qui. |
no_email | La persona o il visitatore non ha un indirizzo e-mail, quindi non si può inviare nulla. |
capacity_full | Ogni numero di Checkroom è in uso. |
already_checked_in | Il ticket di Checkroom è già registrato in deposito. |
already_handed_back | Il ticket di Checkroom è già stato riconsegnato. |
nothing_to_hand_back | Il ticket di Checkroom non ha nulla da riconsegnare. |
number_in_use | Quel numero di Checkroom è già in uso. |
ticket_closed | Solo un ticket di Checkroom aperto può essere inviato per e-mail. |
item_out | L’attrezzatura è fuori con qualcuno. Riprendila prima. |
item_in_repair | L’attrezzatura è messa da parte per la riparazione. |
item_retired | L’attrezzatura è ritirata dal servizio, quindi non può essere consegnata né riservata. |
reservation_conflict | Qualcuno ha riservato l’articolo, o l’ultimo libero della sua categoria, in questo periodo, oppure si prevede che sia ancora fuori. |
already_back | L’attrezzatura è già stata ripresa. |
not_out | L’attrezzatura non è fuori, quindi non può avere più tempo, un promemoria né essere segnata come non restituita. |
borrower_overdue | L’utilizzatore ha attrezzature in ritardo, e la sede o la categoria non consente altro finché non rientrano. |
borrower_item_limit | Questo darebbe all’utilizzatore più articoli di quanti la sede o la categoria ne consenta contemporaneamente. |
reservation_not_ready | La prenotazione non è ancora approvata, oppure è già stata ritirata o annullata. |
reservation_item_mismatch | La consegna non include l’articolo per cui è la prenotazione. |
reservation_category_mismatch | La consegna include un articolo fuori dalla categoria riservata. |
reservation_borrower_mismatch | La prenotazione appartiene a un altro utilizzatore. |
reservation_too_long | La prenotazione è più lunga di quanto la categoria possa essere usata. Solo le prenotazioni fatte da My vFound sono limitate in questo modo. |
reservation_daily_limit | L’utilizzatore ha già fatto 5 prenotazioni da My vFound nelle ultime 24 ore. |
booking_notice | La prenotazione inizia prima di quanto consenta il preavviso minimo della categoria. |
booking_too_far_ahead | La prenotazione, la consegna o il nuovo orario di scadenza finisce più tardi di quanto la categoria possa essere prenotata in anticipo. |
desk_closed | La prenotazione inizierebbe in un giorno in cui il banco delle attrezzature è chiuso. |
kit_unavailable | Una 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_group | La 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_allowed | Nessuno dei tipi di utilizzatore dell’utilizzatore consente questa categoria. |
borrower_on_hold | Il 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_small | Più persone di quante la stanza o lo spazio ne contenga (la sua capacità). |
kit_locked | L’attrezzatura appartiene a un kit bloccato, che esce solo per intero: includi ogni articolo indicato del kit. |
approval_not_yours | La 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_approved | La prenotazione appartiene a un progetto non ancora approvato, quindi non si può ritirare nulla. |
not_enough_credits | La 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_pending | La prenotazione ha una valutazione dei rischi non ancora approvata, quindi non si può ritirare nulla. |
series_unavailable | Non è 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_available | L’orario per cui qualcuno ha chiesto di aspettare è libero, quindi prenotalo invece di mettersi in lista d’attesa. |
space_not_handed_out | Una stanza o uno spazio è prenotato per il suo orario e non viene mai consegnato, quindi non si può consegnare né ritirare. |
stock_short | Non 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_closed | Tutto ciò che è stato consegnato da questa scorta è già rientrato o stornato. |
order_closed | Un 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_placed | La scorta non può essere ricevuta rispetto a un ordine di acquisto ancora in bozza. |
fees_off | Gli addebiti sono disattivati per questa sede. Attivali prima nel criterio del banco e di consegna. |
entry_closed | Quella 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_invoice | L’addebito è su una fattura emessa. Annulla prima la fattura, poi condona l’addebito. |
not_late | La consegna non è rientrata in ritardo secondo le regole sulle multe per ritardo della sede, oppure è ancora fuori. |
nothing_to_invoice | L’utilizzatore non ha addebiti aperti in quella valuta che non siano già su una fattura emessa. |
charge_unavailable | Uno degli addebiti scelti non è aperto, è su un’altra fattura o è per qualcun altro. |
desk_kept | La scrivania è riservata a un’altra persona in uno dei giorni richiesti. |
desk_has_bookings | Riservare la scrivania a questa persona entrerebbe in conflitto con prenotazioni aperte di altri in quei giorni. Annullale prima. |
booking_closed | La prenotazione della scrivania, della sala o del parcheggio è stata annullata o rilasciata, quindi non si può registrare la presenza. |
check_in_closed | La registrazione della presenza si apre 15 minuti prima dell’inizio di una prenotazione e si chiude quando finisce. |
item_service_due | La 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_inspection | La 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_closed | Questo ordine di lavoro è già chiuso e non può essere modificato. |
already_disposed | Questo articolo è già stato dismesso. |
not_disposed | Questo articolo non è stato dismesso, quindi non c’è nulla da annullare. |
item_disposed | Questo articolo è stato dismesso. Annulla la dismissione prima di usarlo di nuovo. |
training_required | Una 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_open | Un inventario è già aperto. Terminalo prima. |
item_unavailable | L’attrezzatura non è disponibile o è messa da parte per la riparazione, quindi non può avviare un trasferimento. |
transfer_open | L’attrezzatura ha già un trasferimento aperto. |
transfer_not_ready | Si può inviare solo un trasferimento preparato. |
transfer_not_in_transit | Si può ricevere o segnalare con un problema solo un’attrezzatura in transito. |
transfer_already_sent | Un trasferimento inviato non può più essere annullato né rifiutato. |
already_signed_in | Il visitatore ha già registrato l’ingresso. |
visit_closed | La visita è chiusa. Registra l’ingresso del visitatore come nuova visita. |
not_signed_in | Il visitatore non ha registrato l’ingresso. |
not_expected | Solo una visita attesa può essere annullata o ricevere un pass. |
approval_required | La visita richiede approvazione prima che il visitatore possa registrare l’ingresso. |
visit_not_valid_today | Il pass non può essere usato di nuovo oggi, oppure oggi è fuori dalle sue date. |
plus_one_not_allowed | Il pass non consente ospiti, oppure non è più approvato, atteso o valido. |
plus_one_limit | Il visitatore ha aggiunto tutti gli ospiti che il pass consente. |
nobody_to_sign_in | Nessuno del gruppo della visita è atteso oggi. |
visitor_capacity_full | Registrare 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:
| Codice | Che cosa significa |
|---|---|
screening_match | Il 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_scope | La 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.
| Codice | Che cosa significa |
|---|---|
checklist_incomplete | 422: 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:
| Codice | Che cosa significa |
|---|---|
idempotency_key_invalid | 400: l’intestazione non è composta da 1 a 191 caratteri ASCII visibili. |
idempotency_key_reused | 422: questa chiave è già stata usata per una richiesta diversa. |
idempotency_in_progress | 409: la prima richiesta con questa chiave è ancora in corso. Riprova a breve. |
offline_in_progress | La 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:
| Codice | Che cosa significa |
|---|---|
acting_user_refused | 403: l’intestazione non indica esattamente un membro attivo del team di questa sede, oppure la chiave è un collegamento creato accedendo. |
acting_user_role | 403: il membro del team indicato non può usare l’ambito di questa operazione con il suo ruolo nella sede. |