Die vFound API und Webhooks
Verbinden Sie die vFound Suite mit den Systemen, die Sie bereits betreiben: Immobilienverwaltung, Service Desks, Personal- und Studierendensysteme, Scanner im Postraum, Data Warehouses oder Ihre eigenen Apps. Lesen und ändern Sie Datensätze in jedem Produkt, halten Sie Ihre Personenliste synchron, erhalten Sie innerhalb von Sekunden einen signierten Webhook, wenn etwas passiert, und lassen Sie KI-Assistenten am Empfang helfen.
Sie möchten eine geführte Einrichtung? Die vFound Integrationsanleitungen gibt es für Cloudbeds, OfficeRnD Flex, Microsoft Entra, Slack, Microsoft Teams, Google Chat, Kalender, Zapier und MCP-Clients.
Authentifizierung
Jeder Standort hat die API. Ein Inhaber oder Manager erstellt unter Einstellungen, Für Entwickler bis zu 10 Schlüssel und legt fest, was jeder Schlüssel darf. Der vollständige Schlüssel wird nur einmal angezeigt. Senden Sie ihn als Bearer-Token:
curl https://vfound.io/api/v1/items \
-H "Authorization: Bearer vf_live_xxxxxxxxxx_…"
| Scope | Erlaubt | Endpunkte |
|---|---|---|
items:read | Fundsachen, Kategorien und Wechsel zwischen Standorten lesen | GET /items, /items/{id}, /categories, /item-transfers |
items:write | Fundsachen hinzufügen und aktualisieren sowie zwischen Standorten senden oder empfangen | POST /items, PATCH /items/{id}, POST /item-transfers und dessen Abbruch und Empfang |
claims:write | Prüfungen der Eigentümerschaft durch Personen, Entscheidungen, Freigabe der Herausgabe und Abholung erfassen | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | Verlustmeldungen von Gästen für ein Kontaktcenter erstellen | POST /lost-reports |
claims:read | Rückgabeanfragen lesen, mit den Kontaktdaten der anfragenden Person | GET /claims, /claims/{id} |
lost_reports:read | Verlustmeldungen von Gästen lesen | GET /lost-reports |
analytics:read | Die Analysenübersicht lesen | GET /analytics |
parcels:read | Pakete lesen, mit Name und E-Mail-Adresse der jeweiligen empfangenden Person | GET /parcels, /parcels/{id} |
parcels:write | Erfassen, übergeben, zurückgeben und erinnern | POST /parcels und dessen Aktionen |
checkroom:read | Tickets, Stationen, Veranstaltungen, die Ausgabeschlange und Berichte lesen | GET unter /checkroom |
checkroom:write | Abgaben erfassen, zurückgeben, als bereit markieren und Stationen oder Veranstaltungen verwalten | POST und PUT unter /checkroom |
loans:read | Geräte lesen und wer sie hat | GET /loans, /loans/items und jeweils ein einzelner Eintrag |
loans:write | Geräte hinzufügen, ausgeben, verlängern und zurücknehmen | POST und PATCH unter /loans |
visitors:read | Besuche lesen | GET /visitors, /visitors/{id} |
visitors:write | Einladen, an- und abmelden, stornieren, einen Pass senden | POST /visitors und dessen Aktionen |
visitors:screening | Bestätigen, dass der Treffer einer Besucherprüfung kontrolliert wurde: screening_reviewed senden oder einen Besuch freigeben, den ein Treffer zurückhält. Standardmäßig aus; was der Schlüssel tut, wird als Handlung des Schlüssels mit seinem Namen aufgezeichnet | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | Die Personenliste lesen | GET /people, /people/{id} |
people:write | Personen hinzufügen, aktualisieren, synchronisieren und entfernen | POST, PATCH und DELETE unter /people |
stays:read | Privaten Kontext zu Hotelaufenthalten und dessen Korrekturverlauf lesen | GET /stays, /stays/{stay} |
stays:write | Kontext zu Aufenthalten aus einem Hotelsystem idempotent hinzufügen oder aktualisieren | POST /stays |
school:read | Verspätetes Kommen und frühes Gehen von Schülern aus dem Schulsekretariat lesen | GET /school/movements |
school:write | Schüler aus dem Schulverwaltungssystem hinzufügen oder aktualisieren | PUT /school/pupils |
queue:read | Warteschlangen, Tickets, gebuchte Zeiten, Nachrichten, Umfragewerte und den Warteschlangenbericht lesen | GET unter /queue |
queue:write | Personen zu einer Warteschlange hinzufügen, aufrufen, ihre Tickets abschließen, Zeiten buchen und stornieren und Wartenden schreiben | POST unter /queue |
webhooks:manage | Die eigenen Webhook-Adressen des Schlüssels abonnieren und abbestellen, für Ereignisse, deren Daten der Schlüssel lesen kann | GET, POST und DELETE /webhooks |
Fundsachen, Rückgabeanfragen, Verlustmeldungen und Analysen brauchen vFound Lost & Found; Pakete brauchen vFound Parcels; Tickets brauchen vFound Checkroom; Geräte brauchen vFound Equipment; Besuche brauchen vFound Visitors; die Personenliste braucht Parcels, Visitors oder Equipment; Hotelaufenthalte brauchen Lost & Found oder Parcels; das Schulsekretariat braucht Visitors mit eingeschaltetem Schulsekretariat (es antwortet mit 404, solange es aus ist); Warteschlangen und Tickets brauchen vFound Queue. Ein Produkt, das für den Standort nicht freigeschaltet ist, antwortet mit 403.
Ein Schlüssel handelt als die Person, die ihn erstellt hat, und funktioniert nicht mehr, wenn diese Person den Standort nicht mehr verwaltet, es sei denn, die Anfrage nennt in X-Acting-User ein Teammitglied (siehe Im Namen eines Teammitglieds handeln). Änderungen mit einem Schlüssel laufen über dieselben Regeln, E-Mails und denselben Prüfpfad wie am Empfang, und jeder Eintrag im Prüfpfad hält den Schlüssel fest, der die Änderung vorgenommen hat. Jeder Schlüssel kann 120 Anfragen pro Minute stellen. Basisadresse: https://vfound.io/api/v1. Listen liefern 25 Datensätze pro Seite (bis zu 100 mit per_page) und akzeptieren page; die meisten lassen sich außerdem mit updated_since (ISO 8601) und search filtern, wie unten aufgeführt.
Testschlüssel
Ein als Testschlüssel erstellter Schlüssel beginnt mit vf_test_ und kann nur queue:read und queue:write enthalten. Er arbeitet auf einer einzigen gekennzeichneten Testwarteschlange, Test line (sandbox) (Warteschlange 1, Schalter 1), und nirgends sonst: Dieselben Queue-Adressen wie bei einem Live-Schlüssel für Warteschlangen, Zeitfenster, Tickets, /queue/join, nächste aufrufen, aufrufen, bedient, nicht erschienen und entfernen antworten aus der Testwarteschlange; jede andere Adresse antwortet mit 403 und code: test_key. Ein Testschlüssel liest oder ändert nie eine echte Warteschlange oder ein echtes Ticket und sendet keine E-Mail, keine SMS, keinen Browser-Hinweis und keinen Webhook. Ein Testschlüssel ignoriert Idempotency-Key: Dieselbe Anfrage, zweimal gesendet, wird zweimal ausgeführt. Antworten enthalten "sandbox": true und den Header X-Vfound-Sandbox: 1. Eine Testwarteschlange fasst bis zu 100 Tickets pro Schlüssel, ohne E-Mail-Adresse, und sie werden mit dem Schlüssel und nach sieben Tagen gelöscht. Verwenden Sie erfundene Namen.
Sichere Wiederholungen
Senden Sie bei einem POST, PATCH oder DELETE einen Idempotency-Key-Header (ein beliebiger eindeutiger Wert mit bis zu 191 sichtbaren Zeichen, etwa eine UUID). Wenn die Verbindung abbricht und Sie dieselbe Anfrage innerhalb von 24 Stunden mit demselben Schlüssel erneut senden, wiederholt vFound die Änderung nicht: Es antwortet mit der ersten Antwort und dem Header Idempotent-Replayed: true. Derselbe Schlüssel mit einer anderen Anfrage wird abgelehnt (422, idempotency_key_reused); ein Schlüssel, dessen erste Anfrage noch läuft, antwortet mit 409 (idempotency_in_progress). Nachdem persönliche Daten von Findern oder anfragenden Personen gelöscht wurden, liefern gespeicherte Antworten für diesen Standort stattdessen 410 ohne die gelöschten Daten; aktualisieren Sie den Datensatz, statt den alten Schreibvorgang mit einem neuen Schlüssel zu wiederholen. Serverfehler werden nicht gespeichert, daher führt eine Wiederholung danach die Anfrage erneut aus. Eine Antwort mit etwas, das nur einmal angezeigt wird, etwa das Signaturgeheimnis aus POST /webhooks oder ein Kiosk-Kopplungscode, wird ebenfalls nie gespeichert: Eine Wiederholung führt die Anfrage erneut aus. Prüfen Sie daher GET /webhooks, bevor Sie dieselbe Adresse zweimal abonnieren.
Im Namen eines Teammitglieds handeln
Eine App, die Ihr Team am Empfang nutzt, etwa eine Stations- oder Depot-App, kann angeben, für welches Teammitglied sie handelt. Senden Sie X-Acting-User mit der Anmelde-E-Mail-Adresse oder der Nutzer-ID der Person. Sie muss aktuell ein aktives Mitglied des Standorts des Schlüssels sein. Die Anfrage läuft dann als diese Person: Der Verlauf der Fundsache und der Verlauf der Rückgabeanfrage nennen diese Person statt des Erstellers des Schlüssels, und der Prüfpfad nennt diese Person, den Schlüssel und den Manager, der den Schlüssel erstellt hat. Sie darf nur tun, was sowohl die Scopes des Schlüssels als auch ihre eigene Rolle am Standort erlauben: Ein Betrachter kann nur lesen, Mitarbeitende können zusätzlich Fundsachen, Rückgabeanfragen, Verlustmeldungen, Pakete, Garderobentickets, Geräte, Besuche und Hotelaufenthalte ändern, und Inhaber und Manager können jeden Scope nutzen, den der Schlüssel hat. Ein Name, der kein aktives Mitglied des Standorts ist, wird mit 403 und acting_user_refused abgelehnt, mit derselben Meldung, ob die Adresse existiert oder nicht; ein Scope, den die Rolle der Person nicht erlaubt, wird mit 403 und acting_user_role abgelehnt. Sichere Wiederholungen werden pro Person geführt, daher wird die gespeicherte Antwort einer Person nie für eine andere wiedergegeben. Der Header funktioniert nur mit Standortschlüsseln, nicht mit einem Assistenten, der sich per Anmeldung verbindet und bereits als die Person handelt, die ihn verbunden hat. vFound prüft, dass die genannte Person ein aktives Mitglied ist; es verlangt nicht, dass sie sich anmeldet. Nennen Sie daher nur Personen aus einer App, bei der sich Ihr Team anmeldet. Ohne den Header funktioniert ein Schlüssel genau wie bisher.
OpenAPI
Die gesamte API, jedes Ereignis und jedes Objekt ist in einer OpenAPI-3.1-Datei beschrieben: vfound.io/openapi/v1.json. Importieren Sie sie in Postman, Insomnia oder Ihren eigenen Codegenerator. Ein Test hält sie mit der API im Gleichschritt, daher führt sie nie einen Endpunkt auf, den es nicht gibt, und lässt keinen aus, den es gibt.
Fertige Verbindungen zu Betriebssystemen
Inhaber und Manager richten diese schreibgeschützten Anbieterverbindungen unter Einstellungen, Verbindungen, Betriebssysteme ein. Sie sind von der öffentlichen REST-API getrennt: Der Kunde erstellt und kontrolliert die Zugangsdaten des Anbieters, die Verbindung muss vor der Aktivierung einen Test bestehen, wiederholte Fehler pausieren nur diese Verbindung, und die manuelle Arbeit bleibt möglich.
| System | Was vFound liest | vFound Bereiche |
|---|---|---|
| Cloudbeds | Minimaler Reservierungs- und Zimmerkontext über einen vom Kunden kontrollierten Objektschlüssel, der auf read:reservation beschränkt ist. Teil von vFound Enterprise. | Private Aufenthalte für Lost & Found und Parcels |
| OfficeRnD Flex | Mitglieds-ID, Name, E-Mail-Adresse und aktiver Status über flex.community.members.read, mit optionalem Standortfilter. | Die gemeinsame Personenliste für Parcels, Equipment und Visitors |
| Microsoft Entra ID | Nutzer-ID, Anzeigename, E-Mail-Adresse und aktiver Status über Microsoft-Graph-Delta-Updates und die vom Administrator genehmigte Berechtigung User.Read.All. | Die gemeinsame Personenliste für Parcels, Equipment und Visitors |
Das sind vom Kunden eingerichtete API-Verbindungen, keine Aussagen über eine Zertifizierung durch den Anbieter. Das Testen, Einschalten und Synchronisieren einer Verbindung gehört zu vFound Enterprise. Die Entra-Verbindung ist insbesondere keine App im Microsoft Marketplace.
Fundsachen
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/items | Fundsachen, zuletzt geänderte zuerst. Filter: status, search (Wörter im Titel, in der Beschreibung, Marke, Farbe oder in den Tags), updated_since (ISO 8601), page, per_page (bis zu 100). | items:read |
| GET/items/{id} | Eine Fundsache anhand ihrer ID. | items:read |
| GET/categories | Die Kategorienamen, die eine Fundsache haben kann. | items:read |
| POST/items | Eine Fundsache hinzufügen. Sie wird auf Ihrer Gästeseite veröffentlicht, löst Hinweise und den Abgleich aus und erscheint in Ihrem Prüfpfad wie eine von Hand erfasste. | items:write |
| PATCH/items/{id} | Details oder Status ändern. | items:write |
| GET/item-transfers | Fundsachen, die dieser Standort an einen anderen Standort derselben Kundengruppe gesendet hat oder von dort erhält, unterwegs befindliche zuerst. Listet außerdem die Standorte auf, an die Sie senden können (destinations), und die Lagerbehälter dieses Standorts (bins). Filter: status (in_transit, received oder cancelled), direction (incoming oder outgoing). | items:read |
| POST/item-transfers | Eine Fundsache, die auf ihren Eigentümer wartet, an einen anderen Standort der Gruppe senden: item_id, destination_business_id und eine optionale note. Nur für Schlüssel, die ein Inhaber oder Manager erstellt hat. Die Fundsache verschwindet von der Gästeseite des sendenden Standorts (sofern dieser Standort seine Fundsachen zeigt) und kann sich bis zu ihrer Ankunft nicht ändern. Eine Fundsache mit einer Rückgabeanfrage bleibt, wo sie ist. | items:write |
| POST/item-transfers/{id}/cancel | Der sendende Standort nimmt die Fundsache zurück, bevor sie empfangen wurde. | items:write |
| POST/item-transfers/{id}/receive | Der empfangende Standort bestätigt die Ankunft, mit bin_id (erforderlich, wenn der Standort Lagerbehälter hat) oder location. Die Fundsache gehört dann zu diesem Standort, mit ihren Fotos, ihrem Verlauf und ihren Daten, und wird wie eine neu erfasste Fundsache mit den Verlustmeldungen dieses Standorts abgeglichen. | items:write |
Werkzeuge für Lost & Found und Checkroom am Empfang
Neue E-Mail-Einstellungen sind standardmäßig aus. Zählungen per Scan und Abweichungen beim Schließen dienen nur der Prüfung. P90 verwendet das 90. Perzentil nach dem Nearest-Rank-Verfahren aus gültigen Zeitstempel-Intervallen; fehlen Stichproben, wird null zurückgegeben. Die Kapazität in physischen Stücken warnt, blockiert die Abgabe aber nie. Die Anfragefelder stehen in der OpenAPI-Beschreibung. Einrichtungsvorlagen und Einstellungen erfordern einen Inhaber oder Manager.
| Methode und Pfad | Was sie tut | Scope |
|---|---|---|
| GET /lost-found/context-schema | Versionierte Felddefinitionen für privaten Kontext lesen, ohne Datensatzwerte. Jeder der genannten Lese-Scopes genügt. | items:read oder lost_reports:read |
| GET /lost-found/desk-settings | Optionale Einstellungen für den Empfang lesen. | lost_reports:read |
| PUT /lost-found/desk-settings | Einstellungen für den Empfang ersetzen; nur Inhaber oder Manager. Neue E-Mail-Einstellungen sind standardmäßig aus. | lost_reports:write |
| GET /checkroom/desk-settings | Optionale Einstellungen für den Empfang lesen. | checkroom:read |
| PUT /checkroom/desk-settings | Einstellungen für den Empfang ersetzen; nur Inhaber oder Manager. Neue E-Mail-Einstellungen sind standardmäßig aus. | checkroom:write |
| GET /lost-found/counts | Die letzten 30 Scan-Zählsitzungen auflisten. | items:read |
| POST /lost-found/counts | Eine Momentaufnahme der gehaltenen Gegenstandskennungen für eine reine Berichtszählung erstellen; keine Änderungen der Verwahrung. | items:write |
| GET /lost-found/counts/{id} | Eine Zählung mit den Werten für fehlende, unerwartete und nicht mehr vorhandene Gegenstände lesen. | items:read |
| POST /lost-found/counts/{id}/scan | Einen Scan eines QR-Codes oder kurzen Gegenstandsetiketts erfassen; mehrfach gescannte bekannte Gegenstände zählen einmal. | items:write |
| POST /lost-found/counts/{id}/finish | Eine Zählung abschließen, ohne Gegenstände zu ändern. | items:write |
| GET /lost-found/queues | Die gespeicherten Arbeitslisten des aktuellen Schlüsselerstellers an diesem Standort auflisten. | lost_reports:read |
| PUT /lost-found/queues/{id} | Ihre eigene gespeicherte Arbeitsliste ersetzen; die zugrunde liegenden Fundsachen und Rückgabeanfragen bleiben unverändert. | lost_reports:write |
| DELETE /lost-found/queues/{id} | Ihre eigene gespeicherte Arbeitsliste löschen; die zugrunde liegenden Fundsachen und Rückgabeanfragen bleiben unverändert. | lost_reports:write |
| POST /lost-found/queues | Eine benannte Vorlage für eine Arbeitsliste für den aktuellen Schlüsselersteller speichern. | lost_reports:write |
| GET /lost-found/queues/{id} | Die aktuellen Datensätze hinter einer gespeicherten Arbeitsliste lesen. Eingehende Übergaben öffnen die bestehende Ansicht für Übergaben mit ihren Berechtigungen. | lost_reports:read, items:read, claims:read |
| POST /lost-found/intake-review | Deterministische Hinweise zu Vollständigkeit und Datenschutz zurückgeben; keine KI und keine Änderungen. | items:read |
| GET /checkroom/templates | Reine Einrichtungsvorlagen auflisten; nur Manager. | checkroom:read |
| PUT /checkroom/templates/{id} | Eine Einrichtungsvorlage als Manager ersetzen; die zugrunde liegenden Veranstaltungen, Stationen und Tickets bleiben unverändert. | checkroom:write |
| DELETE /checkroom/templates/{id} | Eine Einrichtungsvorlage als Manager löschen; die zugrunde liegenden Veranstaltungen, Stationen und Tickets bleiben unverändert. | checkroom:write |
| POST /checkroom/templates | Die Stationskonfiguration einer Veranstaltung ohne Gäste oder Tickets speichern; nur Manager. | checkroom:write |
| POST /checkroom/templates/{id}/apply | Eine neue Veranstaltung und Stationen erstellen; Überschneidungen mit aktiven Nummernbereichen lassen den gesamten Vorgang scheitern. | checkroom:write |
Lost & Found Kontaktcenter und Verwahrung
Von Menschen bediente Integrationen können eine Verlustmeldung von Gästen erstellen, eine Prüfung der Eigentümerschaft erfassen, über eine Rückgabeanfrage entscheiden und die physische Abholung erfassen. Neue Schreib-Scopes müssen ausdrücklich ausgewählt werden; bestehende Schlüssel erhalten sie nicht. Keiner dieser Schreibvorgänge für Rückgabeanfragen oder Verbleib wird als MCP- oder Ask-vFound-Werkzeug angeboten. Ihre Integration ist dafür verantwortlich, die bedienende Person zu identifizieren und zu autorisieren: Der Prüfpfad nennt den Manager, der den Schlüssel erstellt hat, und, wenn die Integration X-Acting-User sendet, auch das genannte Teammitglied, das vFound nicht authentifiziert.
| Methode und Pfad | Was sie tut | Scope |
|---|---|---|
| POST /lost-reports | Aufnahme über das Kontaktcenter: first_name, last_name, email, title und description; optional phone, category id, colour_brand, place_lost, date_lost und language. Sendet die normale Gästebestätigung mit privatem Link und startet die 90-tägige Beobachtung. Eine Einwilligung für das Telefon wird nie unterstellt. Die bestehenden Grenzen für offene Meldungen gelten. | lost_reports:write |
| PUT /lost-reports/{id} | Bearbeiten, was verloren wurde, mit dem Fingerabdruck, den GET /lost-reports zurückgibt. Titel und Beschreibung sind erforderlich. Eine ausgelassene Journey behält die gespeicherten Details; bei deaktivierter Erfassung werden Änderungen am Kontext abgelehnt. Änderungen der Kontaktdaten erfordern den separaten Ablauf der verifizierten Kontaktdaten. | lost_reports:write |
| GET /lost-reports/{id}/matches | Bis zu 24 aktuelle Kandidaten nach Text und Kategorie, jeweils mit match.label, reason und source. Frische gespeicherte KI-Einschätzungen verwenden cached_ai; sonst wird ein Stichwortvorschlag als possible gekennzeichnet. Kein neuer Modellaufruf und keine Entscheidung über die Eigentümerschaft. | lost_reports:read und items:read |
| GET /items/{id}/matches | Passende Meldungs-ID und Titel ohne Kontaktdaten der meldenden Person; bis zu 24 Treffer aus den letzten 1,000 offenen Meldungen. Dieselben Quellenbezeichnungen und kein neuer Modellaufruf. | items:read und lost_reports:read |
| POST /claims/{id}/verification | verified (boolean) und method (distinctive_details, purchase_proof oder staff_review) erfassen. Bestätigung durch eine Person, keine automatische Echtheitsprüfung von Dokumenten; keine Dokumentkopie und kein Freitext als Nachweis. Die letzte Prüfung muss bestanden sein, bevor die API die Annahme zulässt. | claims:write |
| POST /claims/{id}/decision | status: open, accepted, rejected, expired, ready_for_pickup, ready_for_shipment, shipped oder handed_to_courier. Der bestehende Zustandsautomat und die zweite Freigabe gelten. Manuelle Versandfelder folgen den Regeln des Arbeitsbereichs. Bei accepted bringt eine optionale return (pickup oder shipment) die Rückgabeanfrage in derselben Anfrage in diese Phase, mit einer E-Mail an die anfragende Person; wenn eine Herausgabe mit hohem Wert noch ihre zweite Freigabe braucht, bleibt die Rückgabeanfrage auf accepted und return_notice nennt den Grund (dieselbe Anfrage noch einmal ändert nichts). Ein optionales arranged_by (site oder owner) gibt an, wer einen Kurier oder eine Postrückgabe bucht, und jede Antwort zur Rückgabeanfrage zeigt es an. Ohne arranged_by bedeutet eine in shipment gesendete Lieferadresse (oder eine, die die Rückgabeanfrage schon hat), dass Ihr Team es verschickt, wie bisher; andernfalls entscheidet die Einstellung des Standorts für Lost & Found. owner bedeutet, dass der Kurier der anfragenden Person die Fundsache abholt: Es wird keine Adresse verlangt, eine mit owner gesendete Adresse wird abgelehnt, und shipped wird abgelehnt. Wenn ihr Kurier sie abholt, senden Sie handed_to_courier mit der Kurierfirma in shipment.carrier und ihrer Buchungsreferenz in shipment.tracking_number; die Rückgabeanfrage wird abgeschlossen. Um zu ändern, wer bucht, setzen Sie die Rückgabeanfrage auf ready_for_pickup und mit arranged_by zurück auf ready_for_shipment. | claims:write |
| POST /claims/{id}/release-approval | Ein anderer Manager gibt die Herausgabe einer angenommenen Fundsache mit hohem Wert frei, unter denselben Prüfungen wie im Arbeitsbereich. | claims:write |
| GET /claims/{id}/custody | Verlauf der Prüfungen und Phasen, Freigebender sowie Name und Zeit der Abholung lesen. signature_recorded ist ein boolescher Wert; weder ein Unterschriftsbild noch eine private Dateiadresse wird offengelegt. | claims:read |
| POST /claims/{id}/handover | Die physische Abholung ab ready_for_pickup erfassen, mit handover.name und, wenn erforderlich, einer PNG-Daten-URL in handover.signature. Wiederholte Aufrufe nach dem Abschluss behalten die erste Quittung. | claims:write |
| POST /items/{id}/disposition | kind donated/disposed, recipient bei einer Spende, optionale notes. Das Datum der Verwahrung und die Prüfungen auf ausstehende oder angenommene Rückgabeanfragen gelten. Gibt die nummerierte Sammelquittung zurück. | items:write |
Verwenden Sie für Wiederholungen von Schreibvorgängen einen Idempotency-Key. Ein Prüfeintrag authentifiziert weder ein Ausweisdokument noch gibt er selbst die Eigentümerschaft frei. Die erste Erstellung einer Meldung folgt dem Ablauf für Gäste, einschließlich der am Standort eingeschalteten KI; GET-Listen der Treffer verwenden gespeicherte Einschätzungen und nur die Textsuche. Das sind allgemeine REST/OpenAPI-Operationen; keine WSO2-Installation und kein nativer Konnektor wurde zertifiziert.
Eine Fundsache hinzufügen
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}'
Felder: title und category sind erforderlich. Optional: found_date, found_time (HH:MM), keep_until, location, description, colour, brand, tags, value_band (unknown, low, medium, high), notes (nur für Mitarbeitende), photo (eine Base64-Daten-URL bis 8 MB) und photo_public. Über die API gesendete Fotos werden vom Datenschutzfilter von vFound AI nicht geprüft; setzen Sie daher photo_public für jedes Foto, das persönliche Daten zeigt, auf false.
Das Fundsachen-Objekt
{"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":"…"}
Der Status ist einer von in_care, in_transit (auf dem Weg zu einem anderen Standort; transfer nennt dann beide Standorte), claimed, expired, donated, disposed oder trash. Ein PATCH darf in_care, expired, donated, disposed oder trash setzen; Rückgaben an einen Gast laufen über Rückgabeanfragen.
Anfragen
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/claims | Rückgabeanfragen, zuletzt geänderte zuerst. Filter: status, updated_since, page, per_page. | claims:read |
| GET/claims/{id} | Eine Rückgabeanfrage anhand ihrer Referenz. | 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":"…"}
Status der Rückgabeanfrage: unread, open, accepted, awaiting_information, ready_for_pickup, ready_for_shipment, shipped, closed, rejected oder expired (angenommen, aber nie abgeholt). arranged_by gibt an, wer einen Kurier oder eine Postrückgabe bucht: venue (Ihr Team verschickt) oder owner (der Kurier der anfragenden Person holt ab); null, wenn die Rückgabeanfrage keine solche Rückgabe hat. Die Angaben der anfragenden Personen sind personenbezogene Daten: Bewahren Sie sie nur so lange auf, wie Sie sie brauchen.
Verlustmeldungen
GET/lost-reports listet auf, was Gäste als verloren gemeldet haben, mit status (open oder closed), den Kontaktdaten der meldenden Person, der verwendeten Sprache und einem geteilten „Wo ist?“-Link. Scope: lost_reports:read.
Analysen
GET/analytics?days=30 liefert dieselbe Übersicht wie Berichte: erfasste und zurückgegebene Fundsachen, Rückgabequote, mittlere Tage bis zur Rückgabe, wo Fundsachen gelandet sind, Kategorien, Hotspots, die geschäftigsten Tage, Leistung des Teams, der Verlauf und Feedback von Gästen. days ist 7, 30, 90 oder 365. Scope: analytics:read.
Hotelaufenthalte
Der Aufenthaltskontext ist privat für den Standort und bewusst minimal. Er enthält eine stabile Aufenthaltsreferenz, eine optionale Gastreferenz, den Namen des Gastes, An- und Abreise, die Zeitzone der Quelle, das aktuelle Zimmer, den Status und die Zeitstempel der Quelle. Er enthält nie Preise, Zahlungsdaten, Treuedaten, Ausweisdokumente, Vorlieben oder andere Reservierungsnotizen.
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/stays | Aufenthalte auflisten. Filter: search (Gast, stabile Referenz oder aktuelles Zimmer), state, source, page und per_page. Ein Treffer beim Zimmer hilft nur bei der Navigation; er deutet nie auf Eigentümerschaft hin. | stays:read |
| GET/stays/{stay} | Ein Aufenthalt und sein nachvollziehbarer Verlauf von Quelle und Korrekturen. | stays:read |
| POST/stays | Den über external_stay_ref identifizierten Datensatz der API-Quelle erstellen oder aktualisieren. Senden Sie source_updated_at; verspätete oder wiederholte Ereignisse, die nicht neuer sind als das gespeicherte, werden bestätigt, ohne neuere Daten zu ersetzen. | 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"}'
Fundsachen und Pakete akzeptieren optional stay_id und room_at_event. Wenn das Zimmer zum Ereignis fehlt, hält vFound das aktuelle Zimmer des Aufenthalts fest. Diese Momentaufnahme ändert sich nach einem Zimmerwechsel nicht; der Datensatz zeigt auch das aktuelle Zimmer, sodass der Empfang beides sieht.
Parcels
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/parcels | Pakete, zuletzt geänderte zuerst. Filter: status (waiting, collected oder returned), search (Empfänger, Einheit, Sendungsnummer, Absender oder Abholcode), updated_since. | parcels:read |
| GET/parcels/{id} | Ein Paket. | parcels:read |
| POST/parcels | Ein Paket für recipient_email (abgeglichen mit Ihrer Personenliste) oder recipient_name erfassen, mit optionalen unit, carrier, tracking, sender und shelf. Die Person erhält ihren Abholcode per E-Mail, es sei denn, notify ist false. | parcels:write |
| POST/parcels/{id}/collect | Übergeben: collected_by (erforderlich) und eine optionale signature (eine PNG-Daten-URL). | parcels:write |
| POST/parcels/{id}/return | An den Absender zurücksenden, mit einer optionalen note. | parcels:write |
| POST/parcels/{id}/remind | Dem Empfänger eine Erinnerung zur Abholung per E-Mail senden. | parcels:write |
| POST/parcels/tracking | Eine Sendungsnummer normalisieren und UPS, FedEx, USPS, DHL, Amazon oder einen internationalen S10-Versanddienst erkennen. Ein gültiger GS1-SSCC wird als Sendungsverfolgung akzeptiert; eine GS1-Produktkennung wird erkannt, aber nie als Paketnummer behandelt. | parcels:read |
| GET/parcels/pickup-queue | Personen, die gemeldet haben, dass sie am Empfang sind, mit der Anzahl ihrer Pakete und den Regalen. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | Eine Ankunft am Empfang als bedient markieren. | parcels:write |
| POST/parcels/bulk-remind | Erinnerungen per E-Mail für bis zu 200 ausgewählte wartende Pakete senden. | parcels:write |
| POST/parcels/bulk-return | Bis zu 200 ausgewählte wartende Pakete an den Absender zurücksenden. | parcels:write |
| GET/parcels/shelves | Kapazitäten der Paketregale und aktuelle Belegung. | parcels:read |
| POST/parcels/shelves | Ein Regal erstellen oder seine Kapazität ändern. | parcels:write |
| GET/parcels/analytics | Menge, Verteilung der Versanddienste, Zeit bis zur Abholung, Quote nicht abgeholter Pakete und die am stärksten genutzten Regale. | parcels:read |
| GET/parcels/outgoing | Ausgehende Pakete, die für einen Kurier bereit sind oder übergeben wurden. | parcels:read |
| POST/parcels/outgoing | Ein ausgehendes Paket erfassen. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | Den Kurier und die Unterschrift bei der Übergabe erfassen. | parcels:write |
| GET/parcels/rounds | Zustellrunden und ihre Stopps. | parcels:read |
| POST/parcels/rounds | Eine Runde für einen Campus oder ein Büro aus wartenden Paketen erstellen. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | Einen Stopp mit Name und Unterschrift der empfangenden Person abschließen. | parcels:write |
| GET/parcels/couriers | Kuriere, die über Visitors erfasst wurden, mit status in oder 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":"…"}
Der Abholcode wird nur angezeigt, solange das Paket wartet. Die Angaben der Empfänger sind personenbezogene Daten: Bewahren Sie sie nur so lange auf, wie Sie sie brauchen.
Checkroom
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/checkroom/tickets | Tickets, zuletzt geänderte zuerst, mit status (pending, in, returned, left oder moved), der Nummer, dem Abgegebenen, einzeln gekennzeichneten piece_records, den Angaben des Gastes, falls vorhanden, der am Empfang erfassten Gebühr und den Zeiten. Filter: status, search (Gast, Zimmer, Ticketnummer, Stückkennzeichnung oder Ticketcode), updated_since. | checkroom:read |
| GET/checkroom/tickets/{id} | Ein Ticket. | checkroom:read |
| POST/checkroom/tickets | Etwas annehmen und die nächste freie Nummer erhalten: kind (coat, bag, luggage oder other, erforderlich), pieces, optional piece_details mit je einer Art und einem Aufbewahrungsort für jedes Stück, guest_name, guest_email, guest_room, collect_by für Gepäck, notes, fee_method (cash oder card), station_id, event_id, storage_location, language und photo. Die Antwort enthält außerdem einmalig guest_ticket (den Code und die private Ticketadresse), um sie dem Gast als QR-Code zu zeigen oder auszudrucken; Lesezugriffe, Listen und Webhooks enthalten sie nie. | checkroom:write |
| POST/checkroom/tickets/{id}/hand-back | Zurückgeben, sobald Ihr System das Ticket des Gastes gelesen hat, mit optionalen collected_by und signature. Senden Sie piece_ids, um ausgewählte Stücke zurückzugeben und die anderen offen zu lassen; lassen Sie es weg, um jedes offene Stück zurückzugeben. without_ticket hält fest, dass der Gast sein Ticket verloren hat, und braucht dann collected_by und signature. | checkroom:write |
| GET/checkroom/stations | Die Garderobenstationen des Standorts, Nummernbereiche und Aufbewahrungsorte auflisten. | checkroom:read |
| POST/checkroom/stations | Eine Station mit einem sich nicht überschneidenden Nummernbereich erstellen. | checkroom:write |
| PUT/checkroom/stations/{id} | Eine Station, ihren Nummernbereich, die Aufbewahrungsorte oder den aktiven Status ändern. | checkroom:write |
| GET/checkroom/events | Vergangene und kommende Veranstaltungen der Garderobe auflisten. | checkroom:read |
| POST/checkroom/events | Eine Veranstaltung mit erwarteter Menge und Stationen erstellen. | checkroom:write |
| PUT/checkroom/events/{id} | Zeiten, Prognose oder Stationen einer Veranstaltung ändern. | checkroom:write |
| GET/checkroom/exit-queue | Tickets, deren Gäste den Empfang gebeten haben, ihre Sachen bereitzumachen. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | Ein wartendes Ticket als bereit markieren und den Gast benachrichtigen. | checkroom:write |
| GET/checkroom/report | Ticketmenge, Stoßzeiten, Rückgabezeit und Gebühren nach Zahlungsart und Mitarbeitenden. | checkroom:read |
| GET/checkroom/export | Die Zeilen des Garderobenberichts als formelsicheres CSV herunterladen. | checkroom:read |
Queue
Warteschlangen, die Personen darin und die Schalter, zu denen sie aufgerufen werden. Jede Änderung läuft über dieselben Schritte wie am Empfang, mit demselben Verlauf, als Ersteller des Schlüssels oder als das in X-Acting-User genannte Teammitglied. Ein Ticket enthält nie die E-Mail-Adresse des Gastes oder seine Antworten auf die Fragen der Warteschlange.
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/queue/lines | Warteschlangen mit ihrem aktuellen Zustand, den wartenden Personen und einer geschätzten Wartezeit für jemanden, der sich jetzt anstellt. | queue:read |
| GET/queue/lines/{id} | Eine Warteschlange. | queue:read |
| GET/queue/tickets | Tickets eines Standorttags (day, standardmäßig heute), in der Reihenfolge des Aufrufs; filtern Sie nach line und status. | queue:read |
| GET/queue/tickets/{id} | Ein Ticket. | queue:read |
| GET/queue/report | Tickets, bediente Personen, nicht Erschienene, Personen, die gegangen sind, sowie mittlere Warte- und Servicezeit in Minuten für die letzten days. | queue:read |
| POST/queue/tickets | Eine Person zu einer Warteschlange hinzufügen, wie es der Empfang tut. | queue:write |
| POST/queue/call-next | Die nächste Person an einen Schalter aufrufen (counter_id). Zwei Aufrufende bekommen nie dieselbe Person; data ist null, wenn niemand wartet. | queue:write |
| POST/queue/tickets/{id}/call | Eine ausgewählte Person an einen Schalter aufrufen. | queue:write |
| POST/queue/tickets/{id}/served | Die Person am Schalter als bedient markieren. | queue:write |
| POST/queue/tickets/{id}/no-show | Eine aufgerufene Person, die nicht gekommen ist, als nicht erschienen markieren. | queue:write |
| POST/queue/tickets/{id}/remove | Eine Person aus der Warteschlange nehmen. | queue:write |
| GET/queue/bookings | Gebuchte Zeiten, früheste zuerst, mit from, to, line, status und der Seiteneinteilung. Nie die E-Mail-Adresse der Person. | queue:read |
| POST/queue/bookings | Eine der freien Zeiten auf der Seite für gebuchte Zeiten einer Warteschlange für eine Person buchen (line_id, starts_at, email). | queue:write |
| POST/queue/bookings/{id}/cancel | Eine gebuchte Zeit stornieren; die Person erhält eine E-Mail, dass das Team sie storniert hat. | queue:write |
| POST/queue/bookings/{id}/arrived | Eine Person mit gebuchter Zeit anmelden; ihr Ticket wird nach der gebuchten Zeit eingeordnet. | queue:write |
| POST/queue/tickets/{id}/arrived | Eine Person, die sich vor ihrer Ankunft angestellt hat, als anwesend markieren. | queue:write |
| GET/queue/tickets/{id}/messages | Die Nachrichten zwischen einer Person in der Warteschlange und dem Team, älteste zuerst. Beim Lesen werden die Nachrichten der Person als gelesen markiert. | queue:read |
| POST/queue/tickets/{id}/messages | Einer Person in der Warteschlange schreiben (body, 1 bis 500 Zeichen), als Teammitglied des Schlüssels. | queue:write |
| GET/queue/survey | Umfragewerte nach dem Service: Antworten, Durchschnitt, jede Bewertung, nach Warteschlange, Service, Schalter und Teammitglied (der Durchschnitt eines Teammitglieds erscheint ab 5 Antworten). Nie Kommentare. | queue:read |
| GET/queue/performance | Schlichte Zahlen für jedes Teammitglied über dieselben Tage wie der Bericht. Keine Punktzahl und keine Rangliste. | queue:read |
| GET/queue/lines/{id}/slots | Die offenen gebuchten Zeiten einer Warteschlange, wie ihre Buchungsseite sie anbietet. | queue:read |
| POST/queue/join | Eine Nummer für einen Gast Ihrer eigenen Website ziehen, nach den Regeln für Gäste (offene Warteschlange, Grenzen, erforderliche Antworten und Einwilligungsfelder). Senden Sie es von Ihrem Server: Der Schlüssel ersetzt das Captcha. | queue:write |
| GET/queue/tickets/lookup | Tickets anhand der Nummer finden, die der Gast hält. | queue:read |
| GET/queue/tickets/{id}/status | Was die eigene Ticketseite des Gastes zeigt: Platz, Schätzung und Satz. | queue:read |
| GET/queue/tickets/{id}/history | Die Schritte eines Tickets. Wer sie ausgeführt hat, ist team, guest, api (ein Anstellen über einen Schlüssel) oder system (automatisch erledigt, etwa das automatische Nicht-Erscheinen), nie ein Name. | queue:read |
| GET/queue/customers/history | Besuche von jemandem, der darum gebeten hat, sich gemerkt zu werden, gefunden per E-Mail-Adresse, solange der Standort die Wiedererkennung eingeschaltet hat. Sie sagt dem Schlüsselinhaber, ob eine E-Mail-Adresse zu einem gemerkten Besucher gehört. | queue:read |
| GET/queue/insights | Zahlen für dieselben Tage wie der Bericht: Personen, die gingen, bevor sie aufgerufen wurden, Personen mit gebuchter Zeit und ohne Termin, der Anteil, der innerhalb des Wartezeitziels aufgerufen wurde, nach Warteschlange und Woche, und die Stoßzeiten aus vergangenen Wochen. Nur Zahlen; nie ein Name oder eine Antwort. | queue:read |
| GET/queue/report-data | Die Queue-Tickets, wie der Berichtsgenerator sie liest (fields[], limit bis zu 1000, offset), für BI-Werkzeuge. Der Name des Gastes ist nie enthalten. | queue:read |
Equipment
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/loans | Ausgegebene Geräte, zuletzt geänderte zuerst, mit status (out, returned oder lost), ob es overdue ist, dem Gerät, der Person, die es hat, und den Zeiten. Filter: status (out, returned, lost oder overdue), search (Name, E-Mail-Adresse oder Referenz der Person), updated_since. | loans:read |
| GET/loans/{id} | Eine Ausgabe. | loans:read |
| POST/loans | Etwas ausgeben: item_id oder item_code (der Code auf dem Etikett oder der Link, den sein QR-Code enthält), borrower_name (erforderlich), optional person_id, um die Personenliste zu verknüpfen, borrower_email für eine Quittung, borrower_reference, due_at, note, language und signature. | loans:write |
| POST/loans/{id}/extend | Mehr Zeit geben: ein neues due_at. Die Person, die das Gerät hat, erhält die neue Zeit per E-Mail. | loans:write |
| POST/loans/{id}/return | Zurücknehmen, mit optionalen condition (good, damaged oder incomplete), note und set_aside, um das Gerät zur Reparatur beiseitezulegen. | loans:write |
| POST/loans/returns | Mehrere Dinge gemeinsam zurücknehmen: loan_ids (1 bis 50), mit denselben optionalen condition, note und set_aside für alle. Ganz oder gar nicht: Ist eines schon zurück oder nicht gefunden, ändert sich nichts. Eine Person mit E-Mail-Adresse erhält für jede Ausgabe eine Quittung, die alles aufführt, was zurückkam, und jede Ausgabe sendet ihr eigenes Ereignis loan.returned. | loans:write |
| GET/loans/items | Alles, was der Empfang ausgibt, nach Namen. Filter: status (available, out, repair oder retired), search (Name, Inventarnummer oder Etikettencode), updated_since. | loans:read |
| GET/loans/items/{id} | Ein Gerät, mit dem Link, den der QR-Code seines Etiketts enthält. | loans:read |
| GET/loans/items/{id}/tickets | Tickets, die für dieses Gerät an das eigene Jira, Zendesk oder ServiceNow des Standorts gesendet wurden (Beta), mit dem zuletzt zurückgelesenen Status. | loans:read |
| POST/loans/items | Geräte hinzufügen: name (erforderlich), category, tag, location, notes, loan_hours (für wie viele Stunden es üblicherweise ausgegeben wird), photo, product und variant (Einheiten eines Produkts und einer Variante können als eines gebucht werden) und copies, um bis zu 50 identische, nummerierte Geräte hinzuzufügen. | loans:write |
| PATCH/loans/items/{id} | Seine Details ändern oder status auf available, repair oder retired setzen. product und variant ändern seine Produktfamilie; cleaning_status needs_cleaning markiert es als wartend auf die Reinigung und null markiert es als gereinigt. Geräte zeigen product, variant, cleaning_status und cleaning_since. | loans:write |
| GET/loans/items/{id}/tag | Ob ein NFC- oder RFID-Tag verknüpft ist, und die letzten vier Hex-Ziffern seiner Seriennummer. | loans:read |
| PUT/loans/items/{id}/tag | Einen Tag über seine Seriennummer verknüpfen, so wie ein Handy sie liest oder ein Lesegerät in Tastaturform sie tippt (Hex, umgekehrtes Hex oder dezimal); er ersetzt jeden Tag, den das Gerät hatte. | loans:write |
| DELETE/loans/items/{id}/tag | Den Tag des Geräts entfernen. | loans:write |
| POST/loans/checkouts | Ein bis 50 Geräte in einer atomaren Ausgabe ausgeben oder ein gespeichertes Set ausgeben. Sie akzeptiert eine Person, eine Rückgabezeit, eine Notiz und eine optionale Unterschrift sowie Bestandszeilen (stock), die auf derselben Quittung ausgegeben und in stock zurückgemeldet werden. custom_values setzt die benutzerdefinierten Attribute des Standorts für die Ausgabe. | loans:write |
| GET/loans/kits | Gespeicherte Gruppen von Geräten, die üblicherweise zusammen ausgegeben werden. | loans:read |
| POST/loans/kits | Ein Set aus insgesamt mindestens zwei Teilen speichern: benannte item_ids, lines (eine Anzahl aus einer Kategorie) und child_kit_ids (Sets darin, bis zu drei Ebenen), stock_lines (gezählter Bestand, der mit ausgegeben und nie für eine Buchung zurückgehalten wird), optional locked, damit seine benannten Geräte nur gemeinsam hinausgehen. | loans:write |
| PUT/loans/kits/{id} | Ein gespeichertes Set und seine Geräte ändern. | loans:write |
| GET/loans/trainings | Die Schulungen, die eine Kategorie oder ein Gerät verlangen kann, bevor jemand es nutzt (eingerichtet unter Equipment, Richtlinien, Schulung). | loans:read |
| GET/loans/trainings/{id}/holders | Wer eine Schulung hat, ab wann und bis wann, und ob sie abgelaufen ist. | loans:read |
| POST/loans/trainings/{id}/holders | Einer Person aus der Personenliste eine Schulung zuordnen oder sie erneuern, mit einem optionalen Nachweisdokument. | loans:write |
| DELETE/loans/trainings/{id}/holders/{person} | Einer Person eine Schulung entziehen, samt ihrem Nachweisdokument. | loans:write |
| GET/loans/borrower-types | Die Nutzerarten: das Gerätelimit jeder Art, die übliche Dauer und die Kategorien, die ihre Personen sehen und nutzen können (eingerichtet unter Equipment, Richtlinien, „Personenarten“). Ein leeres Limit oder eine leere Dauer bedeutet, dass die eigene des Standorts gilt. | loans:read |
| GET/loans/borrower-types/{id}/members | Wer eine Nutzerart hat. | loans:read |
| POST/loans/borrower-types/{id}/members | Personen aus der Personenliste eine Nutzerart zuordnen (bis zu 500 auf einmal). | loans:write |
| PUT/loans/borrower-types/{id}/members/{person} | Die Zugehörigkeit einer Person zu einer Nutzerart ändern: ihren Starttag, ihren Endtag (danach sehen sie weiterhin, was die Art zeigt, können es aber nicht mehr reservieren oder nutzen) und eine Notiz dazu, wo eine Gebühr erhoben wurde. vFound nimmt keine Zahlung entgegen. | loans:write |
| DELETE/loans/borrower-types/{id}/members/{person} | Einer Person eine Nutzerart entziehen. | loans:write |
| GET/loans/credits | Kürzlich vergebene Buchungsguthaben und das Guthaben einer Person. Guthaben ist eine Anzahl, die Buchungen verbrauchen, nie Geld. | loans:read |
| POST/loans/credits | Einer Person Buchungsguthaben geben oder mit einer negativen Zahl welches zurücknehmen (Inhaber und Manager). | loans:write |
| GET/loans/holds | Aktive Sperren für die Ausgabe: Solange eine besteht, wird der Person nichts ausgegeben und sie kann nichts buchen. | loans:read |
| POST/loans/holds | Eine Sperre für die Ausgabe an eine Person verhängen, mit optionalem Grund (für das Team aufbewahrt, nie in der E-Mail), Endzeit und E-Mail an die Person. | loans:write |
| POST/loans/holds/{id}/lift | Eine Sperre aufheben. | loans:write |
| GET/loans/spaces | Räume, Arbeitsplätze, Parkplätze und andere Orte, die der Standort für eine Zeit bucht, optional gefiltert nach type. Jeder ist ein Eintrag der Art space und wird nie ausgegeben. | loans:read |
| POST/loans/spaces | Einen Raum oder Platz mit seiner Art, der Zahl der Personen, die er fasst, und seinem Ort hinzufügen. | loans:write |
| PUT/loans/spaces/{id} | Einen Raum oder Platz ändern. | loans:write |
| GET/loans/spaces/availability | Jeden Raum oder Platz mit seinen offenen Buchungen zwischen from und to (bis zu 31 Tage), mit dem Namen der Person, der Zahl der Teilnehmenden und eventuellen Anweisungen zum Aufbau. | loans:read |
| POST/loans/spaces/{id}/book | Einen Raum oder Platz für eine Person und eine Zeit buchen, allein oder mit Geräten (ganz oder gar nicht), mit Anweisungen zum Aufbau für das Team. | loans:write |
| POST/loans/reservation-groups/{id}/parts | Ein Gerät oder eines aus einer Kategorie zu einer Set- oder Warenkorbbuchung hinzufügen, geprüft wie eine neue Buchung. Bei einem gesperrten Set abgelehnt. Ein Teil aus einer Kategorie, die das Risikoformular des Standorts abdeckt, braucht risk_answers, und die Bewertung der Buchung wartet auf eine neue Prüfung. | loans:write |
| POST/loans/reservations/{id}/remove-part | Ein Teil aus einer Set- oder Warenkorbbuchung herausnehmen; das letzte Teil wird mit der Buchung storniert. | loans:write |
| GET/loans/places | Die eigenen verschachtelten Orte des Standorts: Gebäude, Räume, Regale, Einsatzorte und Lastwagen. Die place_id eines Geräts legt fest, wo es steht, und füllt seine location und sub_location. | loans:read |
| GET/loans/category-tree | Die Gerätekategorien als Baum gruppiert, übergeordnete zuerst. Regeln und Buchungen gelten weiterhin für die eigene Kategorie eines Geräts. | loans:read |
| GET/loans/asset-models | Modelle, aus denen neue Geräte erstellt werden. Senden Sie asset_model_id bei POST /loans/items, um jedes leer gelassene Detail zu füllen. | loans:read |
| GET/loans/items/{id}/links | Die Verknüpfungen eines Geräts mit anderen Geräten desselben Standorts: funktioniert mit, eine Alternative, ersetzt. | loans:read |
| POST/loans/items/{id}/links | Ein Gerät mit einem anderen desselben Standorts verknüpfen, mit einer Notiz. | loans:write |
| DELETE/loans/items/{id}/links/{link} | Eine Verknüpfung von beiden Geräten entfernen. | loans:write |
| POST/loans/kits/{id}/move | Ein Set an einen Ort des Standorts verschieben: Jedes benannte Gerät darin und in den Sets darin geht in einem Zug dorthin (Inhaber und Manager). | loans:write |
| GET/loans/items/{id}/meter-readings | Eingetippte Zählerstände für ein Gerät, neueste zuerst. | loans:read |
| POST/loans/items/{id}/meter-readings | Einen Zählerstand erfassen. Ein Wartungsplan mit every_meter ist fällig, sobald der Zähler so weit gelaufen ist; Zählerstände können nur steigen. | loans:write |
| GET/loans/contracts | Lieferantenverträge, verknüpft mit den Geräten, die sie abdecken (Inhaber und Manager). | loans:read |
| GET/loans/resale | Zum Verkauf eingestellte Geräte mit ihrem Angebotspreis und Buchwert (Inhaber und Manager). Nur eine Liste: Es wird nichts beworben oder verkauft. | loans:read |
| GET/loans/points | Abhol- und Rückgabepunkte, die eine Buchung nennen kann. | loans:read |
| POST/loans/points | Einen Punkt hinzufügen (Inhaber und Manager). Eine Buchung nennt mit pickup_point_id und dropoff_point_id einen Punkt zum Abholen und einen zum Zurückgeben. | loans:write |
| PUT/loans/points/{id} | Einen Punkt ändern oder abschalten. | loans:write |
| GET/loans/projects | Projekte, zu denen eine Buchung gehören kann. Für ein Projekt wird nichts abgeholt, bis es genehmigt ist. | loans:read |
| POST/loans/projects | Ein Projekt hinzufügen (wartet auf Genehmigung). | loans:write |
| POST/loans/projects/{id}/decision | Ein Projekt genehmigen oder ablehnen (Inhaber und Manager). | loans:write |
| GET/loans/risk-assessments | Risikobewertungen, die auf eine Prüfung warten (oder nach status), mit den Antworten der Person. | loans:read |
| POST/loans/risk-assessments/{id}/review | Eine Risikobewertung genehmigen oder ablehnen (Inhaber und Manager). Eine Ablehnung storniert die Buchung. | loans:write |
| POST/loans/reservation-series | Ein Gerät, eine Kategorie oder einen Raum oder Platz jeden Tag oder jede Woche buchen (repeat: frequency, every, weekdays, count oder until, skip_conflicts). Jeder Termin folgt den Buchungsregeln und zählt die Termine davor mit; es wird nichts gebucht, wenn einer vergeben ist, es sei denn, skip_conflicts ist an. Höchstens 52 Termine, innerhalb eines Jahres. | loans:write |
| POST/loans/reservations/{id}/move | Eine Reservierung, mit jedem Teil einer gemeinsam gebuchten Set- oder Warenkorbbuchung, auf neue Zeiten oder ein anderes Gerät derselben Kategorie verschieben. Erneut geprüft wie eine neue Buchung; ganz oder gar nicht. | loans:write |
| GET/loans/waitlist | Personen, die auf eine vergebene Zeit warten, nach status (standardmäßig waiting). | loans:read |
| POST/loans/waitlist | Jemanden auf die Warteliste für ein Gerät, eine Kategorie oder einen Raum oder Platz und eine Zeit setzen. Wird die Zeit frei, wird die erste Person, deren Zeit jetzt passt, gebucht und per E-Mail benachrichtigt. | loans:write |
| POST/loans/waitlist/{id}/cancel | Jemanden von der Warteliste entfernen. | loans:write |
| GET/loans/fees | Das Gebührenbuch, neueste zuerst (filtern nach party_key, kind, status, billing_code, from, to), mit den Gebühreneinstellungen des Standorts und allen, die etwas schulden oder eine Kaution hinterlegt haben. Beträge sind ganze Zahlen in der kleinsten Einheit der Währung. vFound erfasst Gebühren; es wickelt nie eine Zahlung ab. | loans:read |
| GET/loans/fees/party | Eine Person (person_id oder party_key): was sie je Währung schuldet, hinterlegte Kautionen, Einträge und Rechnungen. | loans:read |
| GET/loans/fees/billing-codes | Berechnet, erlassen, beglichen und noch offen je Abrechnungscode und Währung für einen Zeitraum; format=csv für eine CSV-Datei. | loans:read |
| POST/loans/fees/charges | Eine Gebühr für Schaden, Ersatz oder anderes erfassen, oder eine Gebühr mit Preis über fee_template_id. Die Steuer des Standorts gilt, es sei denn, taxable ist false. | loans:write |
| POST/loans/fees/payments | Geld erfassen, das der Standort selbst entgegengenommen hat (bar, mit dem eigenen Kartenterminal, per Überweisung). Es begleicht offene Gebühren, älteste zuerst. | loans:write |
| POST/loans/fees/deposits | Eine Kaution erfassen, die der Standort entgegengenommen hat; hinterlegt, bis sie zurückgegeben oder einbehalten wird. | loans:write |
| POST/loans/fees/deposits/{id}/return | Eine hinterlegte Kaution zurückgeben. | loans:write |
| POST/loans/fees/deposits/{id}/keep | Eine hinterlegte Kaution oder einen Teil davon einbehalten (Inhaber und Manager, mit Begründung); der einbehaltene Teil zählt als Zahlung. | loans:write |
| POST/loans/fees/{id}/waive | Erlassen, was eine Gebühr noch braucht (Inhaber und Manager, mit Begründung). | loans:write |
| POST/loans/fees/{id}/void | Eine versehentlich erfasste Zahlung ungültig machen (Inhaber und Manager, mit Begründung). Wird die Zahlung ungültig gemacht, die eine einbehaltene Kaution erzeugt hat, wird dieser Betrag wieder als Kaution hinterlegt. | loans:write |
| GET/loans/{id}/fees | Was dem Empfang für eine zurückgegebene Ausgabe angeboten wird: das noch nicht erfasste Verspätungsentgelt, der Ersatzwert bei Verlust oder Schaden, hinterlegte Kautionen. | loans:read |
| POST/loans/{id}/late-fine | Das Verspätungsentgelt für eine verspätet zurückgekommene Ausgabe hinzufügen, gezählt ab dem Zeitpunkt der Rückkehr. Einmal pro Ausgabe. | loans:write |
| GET/loans/invoices | Rechnungen, neueste Nummer zuerst. | loans:read |
| POST/loans/invoices | Eine nummerierte Rechnung für die offenen Gebühren einer Person in einer Währung ausstellen. | loans:write |
| POST/loans/invoices/{id}/void | Eine Rechnung ungültig machen (Inhaber und Manager, mit Begründung); reissue überträgt ihre offenen Gebühren auf eine neue, die sie ersetzt. | loans:write |
| GET/loans/reservations | Reservierungen nach Startzeit, optional gefiltert nach status oder from. | loans:read |
| POST/loans/reservations | Ein bestimmtes Gerät oder ein Gerät einer Kategorie für eine Person und ein Zeitfenster reservieren. custom_values setzt die benutzerdefinierten Attribute des Standorts für die Buchung. | loans:write |
| POST/loans/reservations/{id}/approve | Eine Reservierung genehmigen, die auf Prüfung wartet. Hat der Standort Genehmigungsschritte, zeichnet ein Schlüssel einen Schritt nur für das Teammitglied ab, das er in X-Acting-User nennt, eine Assistentenverbindung zeichnet nie einen ab, und niemand zeichnet einen Schritt einer Buchung ab, die er selbst gemacht hat (approval_not_yours). Dieselbe Regel gilt für das Buchen trotz eines Konflikts. | loans:write |
| POST/loans/reservations/{id}/cancel | Eine ausstehende, genehmigte oder bereite Reservierung stornieren. | loans:write |
| POST/loans/reservations/{id}/pickup | Das reservierte Gerät atomar übergeben und die Reservierung als abgeholt abschließen. | loans:write |
| POST/loans/reservation-groups | Ein Set (kit_id) oder einen Warenkorb (items: ein Gerät oder eine Kategorie und Menge je Zeile) für eine Person und ein Zeitfenster reservieren: jedes Teil oder keines. Das Genehmigen, Stornieren oder Abholen eines Teils wirkt auf jedes offene Teil. | loans:write |
| GET/loans/downtimes | Datierte Zeitfenster, in denen ein Gerät nicht gebucht oder ausgegeben werden kann und die noch nicht zu Ende sind (item_id schränkt auf ein Gerät ein). | loans:read |
| POST/loans/downtimes | Einem Gerät ein Zeitfenster hinzufügen: loan_item_id, starts_at, ends_at und ein optionaler reason. Abgelehnt, solange eine Buchung oder Ausgabe das Gerät für irgendeinen Teil dieser Zeit hält. | loans:write |
| DELETE/loans/downtimes/{id} | Ein Zeitfenster entfernen. | loans:write |
| GET/loans/extra-values/{type}/{id} | Die benutzerdefinierten Attribute des Standorts für eine Person (person), eine reservation oder eine checkout, mit den für diese Art von Datensatz definierten Feldern. | loans:read |
| PUT/loans/extra-values/{type}/{id} | Diese Attribute setzen, geprüft gegen die Felder des Standorts und deren Bedingungen für die Anzeige. | loans:write |
| GET/loans/closures | Tage, an denen der Geräteempfang geschlossen ist und die noch nicht zu Ende sind. | loans:read |
| POST/loans/closures | Eine Schließung hinzufügen: starts_on und ends_on als Daten in der Zeitzone des Standorts, bis zu 366 Tage. Eine optionale note bleibt intern; public_message (bis zu 300 Zeichen) wird den Personen angezeigt. Bestehende Notizen werden nie in die Nachricht an die Personen kopiert. | loans:write |
| DELETE/loans/closures/{id} | Eine Schließung entfernen. | loans:write |
| GET/loans/rules | Standardwerte des Standorts, Kategorieregeln für Dauer, Limits, Sperren bei Überfälligkeit, Genehmigung und Buchungsregeln (Pufferzeiten zwischen Buchungen, Mindestvorlauf, wie weit im Voraus) sowie Schließungen. | loans:read |
| POST/loans/rules | Eine Kategorieregel erstellen oder ersetzen. Weggelassene Felder der Buchungsregeln behalten ihre gespeicherten Werte. | loans:write |
| GET/loans/timeline | Kapazitätsprüfungen für ganze Tage nach Gerät oder Kategorie. Erforderlich sind die inklusiven, in der Ortszeit des Standorts angegebenen Daten from und until, höchstens 31 Tage, von heute bis nächstes Jahr; optional group=item|category, item_id, genaue category, page (50 Zeilen). Zellen sind true, false oder null (unsicher). Benachbarte Tage garantieren keine durchgehende Buchung. | loans:read |
| GET/loans/warranties | Erfasste Garantiedaten; filter=soon|expired|all, genaue category, page (50 Zeilen). Soon umfasst heute bis 30 Tage im Voraus. Die persönliche Anmeldung für Erinnerungen erfolgt im Arbeitsbereich. | loans:read |
| GET/loans/utilization | Verstrichene Stunden je Gerät aus dem erfassten Statusverlauf. Erforderlich sind die inklusiven, in der Ortszeit des Standorts angegebenen Daten from und until innerhalb der letzten 365 Tage, begrenzt auf jetzt; optional item_id, genaue category, format=csv. JSON liefert genaue Sekunden; die Stunden im CSV haben sechs Dezimalstellen. Verfügbar schließt Ausgegebenes ein; Reparatur, Wartung und andere nicht verfügbare Zeit sind ausgeschlossen. Frühere Ausfallzeiten sind unbekannt. Die Summen stimmen mit den Zeilen der Geräte überein. | loans:read |
| GET/loans/maintenance | Verlauf von Wartung, Kalibrierung, Sicherheitsprüfung, Inspektion, Reinigung, Reparatur und Notizen; filtern nach Gerät, anstehender Arbeit oder Arbeitsaufträgen (offen oder alle) und ihrem Techniker. | loans:read |
| POST/loans/maintenance | Wartung und die nächste Fälligkeit für ein Gerät erfassen. Mit plan_id die erledigte Arbeit eines wiederkehrenden Plans, die dessen nächste Runde startet. | loans:write |
| GET/loans/service-plans | Wiederkehrende Pläne für Wartung, Kalibrierung, Sicherheitsprüfung, Inspektion und Reinigung, mit der Angabe, ob jeder nach Datum, nach Stunden der Ausgabe oder nach Anzahl der Ausgaben fällig ist. | loans:read |
| POST/loans/service-plans | Einem Gerät einen wiederkehrenden Plan hinzufügen (Inhaber und Manager). | loans:write |
| PUT/loans/maintenance/{id} | Einen Arbeitsauftrag ändern oder abschließen: Status, Techniker, Lieferant, Kosten und bei done sein Ergebnis und ob das Gerät wieder in Betrieb geht. | loans:write |
| GET/loans/maintenance/costs | Kosten für Wartung, Reparatur und Reinigung je Gerät, aus abgeschlossenen Einträgen und erledigten Arbeitsaufträgen. | loans:read |
| GET/loans/items/{id}/lifecycle | Der Datensatz eines Geräts zu Kauf, Abschreibung, Versicherung und Abgang, mit seinem Wert heute (Inhaber und Manager). | loans:read |
| PUT/loans/items/{id}/lifecycle | Kaufpreis, Datum, Lieferant und Bestellung, die Abschreibungsmethode (linear oder degressiv), Nutzungsdauer und Restwert sowie die Versicherung speichern (Inhaber und Manager). | loans:write |
| POST/loans/items/{id}/dispose | Erfassen, wie ein Gerät ausgeschieden ist (verkauft, verschrottet, gespendet, recycelt, verloren oder gestohlen); es wird ausgemustert, und seine offenen Buchungen und Arbeitsaufträge werden storniert. | loans:write |
| DELETE/loans/items/{id}/dispose | Einen versehentlich erfassten Abgang rückgängig machen; das Gerät ist wieder verfügbar. | loans:write |
| GET/loans/valuation | Der Wert der Geräte an einem Datum, auf den Cent genau, mit Summen für das, was noch gehalten wird (Inhaber und Manager). | loans:read |
| POST/loans/service-plans/import | Pläne aus einer CSV-Datei mit den dokumentierten Spalten prüfen oder hinzufügen, wobei Geräte über die Inventarnummer benannt werden (Inhaber und Manager). | loans:write |
| POST/loans/maintenance/work-orders/import | Offene Arbeitsaufträge aus einer CSV-Datei mit den dokumentierten Spalten prüfen oder hinzufügen (Inhaber und Manager). | loans:write |
| GET/loans/maintenance/planner | Geplante Arbeit und offene Arbeitsaufträge nach dem eigenen Tag des Standorts für bis zu 62 Tage, optional für einen Techniker. | loans:read |
| GET/loans/funding | Was jeder Fonds, jeder Zuschuss oder jede Kostenstelle gekauft hat und welche Arbeit ihnen belastet wurde, filterbar nach Fonds und Datum (Inhaber und Manager). Nur ein Datensatz: vFound nimmt keine Zahlung entgegen. | loans:read |
| GET/loans/substances | Das Gefahrstoffverzeichnis: Stoff, Ort, Gefahrenklassen und Prüftermine. Ein Verzeichnis dessen, was der Standort angibt; vFound gibt keine Sicherheitsberatung. | loans:read |
| POST/loans/substances | Einen Stoff hinzufügen, mit seinem Sicherheitsdatenblatt als PDF oder Foto (Inhaber und Manager). | loans:write |
| PUT/loans/substances/{id} | Einen Stoff ändern oder sein Datenblatt ersetzen (Inhaber und Manager). | loans:write |
| DELETE/loans/substances/{id} | Einen Stoff und sein aufbewahrtes Datenblatt entfernen (Inhaber und Manager). | loans:write |
| GET/loans/licences | Lizenzen für die Geräte des Standorts mit Plätzen, Enddatum und den Geräten, auf denen sie installiert sind (Inhaber und Manager). Es wird kein Lizenzschlüssel gespeichert. | loans:read |
| POST/loans/licences | Eine Lizenz hinzufügen (Inhaber und Manager). | loans:write |
| PUT/loans/licences/{id} | Eine Lizenz und den Ort ihrer Installation ändern. | loans:write |
| DELETE/loans/licences/{id} | Eine Lizenz entfernen. | loans:write |
| GET/loans/expiries | Versicherungen und Lizenzen, die bald enden oder bereits beendet sind (Inhaber und Manager). | loans:read |
| GET/loans/stocktakes | Aktuelle Inventuren der Geräte mit Zahlen zu gescannten und fehlenden Geräten. | loans:read |
| POST/loans/stocktakes | Eine offene Inventur für den Standort starten, für alles, für einen Ort, eine Kategorie oder ein Set oder für das, was eine Person hat (custodian_id), optional einem Teammitglied zugewiesen (assigned_to). | loans:write |
| POST/loans/stocktakes/{id}/scan | Ein Gerätetikett, eine Inventarnummer oder eine Seriennummer in die offene Inventur einscannen. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | Bis zu 2,000 Codes auf einmal zählen (ein RFID-Lesegerät in Tastaturform oder eine Liste); jeder zählt einmal, und nicht zugeordnete Codes kommen zurück. | loans:write |
| PUT/loans/stocktakes/{id}/assign | Die offene Inventur einem Teammitglied zum Zählen geben (assigned_to) oder niemandem (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | Die Inventur abschließen und die Liste der fehlenden Geräte zurückgeben. | loans:write |
| GET/loans/stocktake-schedules | Inventuren, die sich von selbst öffnen, einmalig oder wiederkehrend. | loans:read |
| POST/loans/stocktake-schedules | Eine Inventur planen, einmalig, wöchentlich, monatlich, alle drei Monate oder jährlich, zur eigenen Tageszeit des Standorts. | loans:write |
| PATCH/loans/stocktake-schedules/{id} | Einen Plan ändern, pausieren oder fortsetzen. | loans:write |
| DELETE/loans/stocktake-schedules/{id} | Einen Plan löschen; von ihm geöffnete Inventuren bleiben bestehen. | loans:write |
| GET/loans/last-seen | Wo jedes Gerät zuletzt gescannt wurde, wenn der Standort Scan-Positionen speichert (nur von Teammitgliedern, die zugestimmt haben; nie von einem Schlüssel). | loans:read |
| GET/loans/transfers | Eingehende und ausgehende Übergaben von Geräten für diesen Standort. | loans:read |
| POST/loans/transfers | Geräte für einen anderen berechtigten Standort derselben Kundengruppe vorbereiten. | loans:write |
| POST/loans/transfers/{id}/send | Erfassen, dass vorbereitete Geräte den Ausgangsstandort verlassen haben. | loans:write |
| POST/loans/transfers/{id}/receive | Geräte am Zielstandort mit ihrem Ort und ihrem Zustand bei der Ankunft entgegennehmen. | loans:write |
| POST/loans/transfers/{id}/cancel | Eine vorbereitete Übergabe vor dem Versand abbrechen. | loans:write |
| POST/loans/transfers/{id}/reject | Eine vorbereitete Übergabe am Zielstandort vor dem Versand ablehnen. | loans:write |
| POST/loans/transfers/{id}/exception | Ein Problem erfassen, während Geräte unterwegs sind. | loans:write |
| POST/loans/import | Bis zu 5,000 CSV-Zeilen mit den Spaltenüberschriften von vFound, Snipe-IT, Sortly oder Cheqroom als Vorschau anzeigen oder importieren. | loans:write |
Visitors
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/visitors | Besuche, zuletzt geänderte zuerst, mit status (expected, in, out, cancelled oder missed), dem Besucher, dem Gastgeber, dem Passcode, solange er gültig ist, und den Zeiten. Filter: status, search (Besucher, Firma, Gastgeber oder Passcode), updated_since. | visitors:read |
| GET/visitors/{id} | Ein Besuch. | visitors:read |
| POST/visitors | Einen Besucher einladen oder anmelden. Akzeptiert werden die Felder für Besucher, Gastgeber und Zeit sowie visitor_type_id, Antworten, Gültigkeitsdaten und eine tägliche oder wochentägliche Wiederholung. | visitors:write |
| POST/visitors/{id}/sign-in | Einen erwarteten Besucher anmelden; der Gastgeber wird benachrichtigt. Senden Sie answers für ein Gruppenmitglied, dessen Besucherart erforderliche Fragen hat, und id_expires_on mit identity_checked, wenn der Standort das Ablaufdatum eines physischen Ausweises erfasst. Der Besuch enthält dann id_expires_on und id_expired. | visitors:write |
| POST/visitors/{id}/group/sign-in | Alle aus der Gruppe des Besuchs anmelden, die heute erwartet werden, mit einer E-Mail an den Gastgeber; wer ein eigenes Foto, eine eigene Ausweisprüfung, Unterschrift, Antworten oder Bedingungen braucht, steht in skipped. | visitors:write |
| POST/visitors/{id}/sign-out | Sie abmelden. | visitors:write |
| POST/visitors/{id}/cancel | Eine Einladung stornieren. | visitors:write |
| POST/visitors/{id}/send-pass | Den Pass erneut per E-Mail senden. | visitors:write |
| POST/visitors/{id}/approve | Einen ausstehenden Besuch freigeben und den Pass senden. | visitors:write |
| POST/visitors/{id}/deny | Einen ausstehenden Besuch ablehnen. | visitors:write |
| GET/visitors/{id}/badge | Den im Browser druckbaren Besucherausweis herunterladen. Wählen Sie für size 4x3, brother oder dymo. | visitors:read |
| GET/visitors/{id}/card | Ob der Besuch eine RFID-Karte hat, und ihre letzten vier Zeichen (nie die Nummer). Aus, bis der Standort Karten und Schlüsselanhänger einschaltet. | visitors:read |
| POST/visitors/{id}/card | Einem erwarteten oder angemeldeten Besuch eine Karte über ihre Nummer geben; eine Nummer ist jeweils nur für einen Besuch aktiv. | visitors:write |
| DELETE/visitors/{id}/card | Die Karte zurücknehmen. | visitors:write |
| GET/visitors/{id}/assets | Die Dinge, die dem Besuch übergeben wurden, von Hand eingetragen. | visitors:read |
| POST/visitors/{id}/assets | Ein dem Besuch übergebenes Ding erfassen, mit einem optionalen Tag. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | Ein Ding als zurückgegeben markieren. | visitors:write |
| GET/visitor-assets/not-returned | Dinge, die Besuchern übergeben und noch nicht zurückgegeben wurden, neueste zuerst. | visitors:read |
| GET/visitors/{id}/fast-track | Ob der Besuch einen gültigen Schnellzugangscode hat, bis wann und wie oft er verwendet wurde (nie der Code, den nur der Besucher sieht). | visitors:read |
| POST/visitors/{id}/fast-track | Einem wiederkehrenden Besucher einen Schnellzugangscode geben, der days gilt (1 bis 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | Den Code zurücknehmen. | visitors:write |
| GET/visitor-types | Besucherarten und ihre Fragen, Bedingungen, Ausweise, Freigaben und Aufbewahrung auflisten (retention_days ist null, wenn die Art dem Standard des Standorts folgt). | visitors:read |
| POST/visitor-types | Eine Besucherart erstellen. | visitors:write |
| PATCH/visitor-types/{id} | Die Felder der Besucherart ändern, die Sie senden. | visitors:write |
| DELETE/visitor-types/{id} | Eine Besucherart deaktivieren, ohne frühere Besuche zu ändern. | visitors:write |
| GET/visitor-roll-call | Die letzte Anwesenheitskontrolle und ihre Live-Zahlen abrufen. Eine laufende Anwesenheitskontrolle nimmt jeden auf, der sich seit ihrem Start angemeldet hat; eine, die 6 Stunden lang läuft, wird beendet. | visitors:read |
| POST/visitor-roll-call | Eine Anwesenheitskontrolle starten, optional einschließlich der heute erwarteten Besucher und aller, die auf Freigabe warten. | visitors:write |
| PATCH/visitor-roll-call/entries/{entry} | Einen Eintrag als in Sicherheit oder vermisst markieren. | visitors:write |
| POST/visitor-roll-call/{id}/finish | Die aktive Anwesenheitskontrolle beenden und ihren Bericht behalten. | visitors:write |
| GET/staff-attendance | Die Anwesenheit der Mitarbeitenden für einen Zeitraum nach der Uhr des Standorts auflisten (standardmäßig heute, höchstens 366 Tage) oder mit open=true nur Personen, die jetzt angemeldet sind. Enthält nie die E-Mail-Adresse der Person. | visitors:read |
| POST/staff-attendance | Eine Person aus der Liste der Mitarbeitenden anmelden (mode office oder remote) oder abmelden, mit denselben Regeln wie am Empfang. Setzt voraus, dass die Anmeldung für Mitarbeitende am Standort eingeschaltet ist. | visitors:write |
| POST/staff-presence | Bis zu 50 Anwesenheitsereignisse (in, out oder muster) aus Ihrem Ausweis-, Zeiterfassungs- oder WLAN-System senden, jedes mit einer Person aus der Liste der Mitarbeitenden über Referenz, externe ID oder E-Mail-Adresse. Setzt voraus, dass die Anmeldung für Mitarbeitende und der Anwesenheits-Feed am Standort eingeschaltet sind. Antwortet, was pro Ereignis geschehen ist, nie wer. | visitors:write |
| POST/visitors/{id}/catering | Die Catering-Anfrage eines erwarteten oder angemeldeten Besuchs aus den Optionen, die der Standort auflistet, erstellen, ändern oder (ohne Einträge) entfernen. Sendet eine E-Mail an das Catering-Postfach des Standorts; vFound bestellt nichts und nimmt keine Zahlung entgegen. Setzt voraus, dass Catering am Standort eingeschaltet ist. | visitors:write |
| GET/workplace/spaces | Die Arbeitsplätze, Besprechungsräume und Parkplätze auflisten, die Personen am Standort buchen können. | visitors:read |
| GET/workplace/free | Plätze finden, die für eine ganze Zeit frei sind (höchstens 7 Tage), wobei ein für eine andere Person reservierter Arbeitsplatz ausgelassen wird. | visitors:read |
| GET/workplace/bookings | Buchungen von Arbeitsplätzen, Räumen und Parkplätzen in einem Zeitraum von höchstens 31 Tagen auflisten. Enthält nie die E-Mail-Adresse der Person. | visitors:read |
| POST/workplace/bookings | Einen Platz für eine Person buchen, einmalig oder als wiederkehrende Buchung (täglich oder wöchentlich, bis zu 52 Mal, ganz oder gar nicht), nach den Reservierungsregeln von Equipment. | visitors:write |
| POST/workplace/bookings/{id}/cancel | Eine Buchung stornieren oder mit scope following oder series ihre späteren Termine. | visitors:write |
| POST/workplace/bookings/{id}/check-in | Eine Buchung anmelden, ab 15 Minuten vor ihrem Beginn bis zu ihrem Ende. | visitors:write |
| POST/visitors/{id}/room | Einen Besprechungsraum für einen Besuch buchen, ab der Zeit des Besuchs; der Raum folgt dem Besuch. | visitors:write |
| GET/appointment-pages | Die Terminseiten des Standorts, ihre Zeiten und die Angabe auflisten, ob jede jetzt für Besucher offen ist. | visitors:read |
| GET/visitor-roll-call/archive | Beendete Anwesenheitskontrollen (Notfälle, Übungen und Hinweise) auflisten, neueste zuerst. | visitors:read |
| GET/visitor-roll-call/{id} | Eine Anwesenheitskontrolle mit ihren Personen, ihrem Zeitverlauf, den Absuchungen und der Zahl der Nachrichten. | visitors:read |
| POST/visitor-roll-call/{id}/people | Eine Person (einen Mitarbeiter, eine andere Person oder einen Auftragnehmer) zur laufenden Anwesenheitskontrolle hinzufügen. | visitors:write |
| POST/visitor-roll-call/{id}/scan | Einen Besucher über seinen Passlink oder Code an einem Sammelpunkt als in Sicherheit markieren. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | Eine Zone als abgesucht und frei oder als mit Personen darin erfassen. | visitors:write |
| POST/visitor-roll-call/{id}/messages | Eine Nachricht an alle, an Personen, die noch nicht in Sicherheit sind, oder an Personen, die Hilfe brauchen, senden. Sie geht per E-Mail, Browser-Hinweis und, über den eigenen Anbieter des Standorts, per SMS oder WhatsApp, mit einem privaten Link, um mit „in Sicherheit“ oder „brauche Hilfe“ zu antworten. | visitors:write |
| GET/visitor-roll-call/{id}/people/{entry}/messages | Die Unterhaltung mit einer Person in einer Anwesenheitskontrolle: was das Team ihr gesendet hat und was sie von ihrem privaten Link zurückgeschrieben hat, älteste zuerst. Antworten Sie über den Nachrichten-Endpunkt mit audience entry. | visitors:read |
| POST/visitor-hazard-alerts | Eine Warnung, die ein Teammitglied verfasst und an eine gewählte Gruppe sendet: hazard, message und group (on_site, visitor_type, host oder tenant, mit group_ref). Sie startet eine Anwesenheitskontrolle der Art hazard für diese Gruppe. vFound liest keinen Wetter-, Nachrichten- oder Bedrohungs-Feed: Es wird nichts gesendet, es sei denn, Sie senden diese Anfrage. Antwortet mit 409, solange eine andere Anwesenheitskontrolle läuft. | visitors:write |
| POST/visitor-help-alerts | Leise um Hilfe bitten: Die dafür gewählten Teammitglieder werden benachrichtigt; kein Besucher sieht etwas. | visitors:write |
| GET/visitor-kiosks | Gekoppelte, ausstehende und widerrufene Kiosk-Geräte auflisten. | visitors:read |
| POST/visitor-kiosks/pairing | Einen Kopplungscode mit acht Zeichen erstellen, der zehn Minuten gilt. | visitors:write |
| DELETE/visitor-kiosks/{id} | Ein Kiosk-Gerät widerrufen. | visitors:write |
| PUT/visitor-kiosks/{id}/settings | Die Einstellungen eines Kiosks ändern: eine E-Mail, wenn er eine Anzahl von Minuten lang nicht gesehen wurde, Rückkehr zum Start nach einer ruhigen Zeit, eine Unterschrift bei der Anmeldung und das Drucken des Ausweises vom Tablet. Alles ist anfangs aus. | visitors:write |
| GET/visitor-analytics | Summen nach Tag, Stunde, Art und Gastgeber sowie die durchschnittliche Aufenthaltsdauer des letzten Jahres. | visitors:read |
| GET/visitor-registration | Den Link des Standorts zur Selbstregistrierung abrufen und ob er eingeschaltet ist. | visitors:read |
| GET/school/movements | Verspätetes Kommen und frühes Gehen von Schülern, älteste zuerst, ab since (standardmäßig die letzten 24 Stunden), mit der reference jedes Schülers für das Schulverwaltungssystem. Ein nur lesendes Teammitglied, das in X-Acting-User genannt wird, kann es nicht nutzen. | school:read |
| PUT/school/pupils | Bis zu 500 Schüler über reference hinzufügen oder aktualisieren; senden Sie active false für einen Schüler, der gegangen ist. Hier wird nichts gelöscht. | school:write |
Die Angaben der Besucher sind personenbezogene Daten: Bewahren Sie sie nur so lange auf, wie Sie sie brauchen.
Personen
Die Personenliste enthält die Bewohner, Mitarbeitenden oder Studierenden, die Ihr Empfang betreut. Parcels findet darin Empfänger, Visitors findet Gastgeber, und Equipment schlägt Personen vor, die ein Gerät bekommen. Halten Sie sie über die API im Gleichschritt mit Ihrem Personal-, Studierenden- oder Immobiliensystem.
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/people | Die Liste, nach Namen. Filter: search (Name, E-Mail-Adresse, Einheit oder Referenz), updated_since. | people:read |
| GET/people/{id} | Eine Person. | people:read |
| POST/people | Jemanden hinzufügen: name (erforderlich), email, unit, reference und language für seine E-Mails. | people:write |
| POST/people/upsert | Bis zu 500 Personen in einem Aufruf hinzufügen oder aktualisieren: people ist eine Liste mit denselben Feldern. Wer mit seiner E-Mail-Adresse schon auf der Liste steht, wird aktualisiert. Antwortet, wie viele hinzugefügt, aktualisiert und übersprungen wurden. | people:write |
| PATCH/people/{id} | Nur die Felder ändern, die Sie senden. | people:write |
| DELETE/people/{id} | Jemanden entfernen. Seine Pakete, Besuche und Ausgaben behalten den Namen, den er hatte. | people:write |
| GET/people/export | Die vollständige Personenliste als formelsicheres CSV herunterladen. | people:read |
| POST/people/{id}/send-my-vfound | Einer aktiven Person die signierte Seite für ihre verknüpften Pakete, Besucher und Geräte per E-Mail senden. | people:write |
| GET/people/sync-source | Das gespeicherte CSV-Verzeichnis und das letzte Ergebnis der Synchronisierung anzeigen. | people:read |
| PUT/people/sync-source | Eine öffentliche HTTPS-CSV-url und mode (upsert oder mirror) speichern. | people:write |
| DELETE/people/sync-source | Die Verbindung entfernen und die bereits importierten Personen behalten. | people:write |
| POST/people/sync-source/run | Die gespeicherte Verbindung jetzt ausführen. | people:write |
Inhaber und Manager können unter Personen auch einen öffentlichen HTTPS-CSV-Link verbinden. vFound prüft ihn stündlich, folgt höchstens drei Weiterleitungen und prüft dabei jedes Ziel, akzeptiert höchstens 10 MB und stoppt im Modus mirror, bevor es Änderungen vornimmt, wenn die Zahl der gültigen Zeilen um mehr als 30 Prozent sinkt. Verbundene Felder werden an ihrer Quelle geändert.
Automatische Bereitstellung aus dem Verzeichnis
Für Microsoft Entra gibt es die oben beschriebene fertige, vom Kunden eingerichtete Verbindung. Identitätsverzeichnisse wie Okta, OneLogin und JumpCloud können stattdessen die Personenliste unter https://vfound.io/api/scim/v2/Users mit einem vFound API-Schlüssel bereitstellen, der people:write hat. Verwenden Sie den Bearer-Schlüssel als geheimen Token. Eine Deaktivierung entfernt die Person aus den Vorschlägen; DELETE anonymisiert Verknüpfungen nach denselben Regeln für Personen. Dieser Endpunkt erstellt nur Einträge der Personenliste und nie Anmeldungen für das Team.
Schulungslisten für Equipment können aus demselben Verzeichnis kommen: Verknüpfen Sie eine Schulung über ihren Namen mit einer Verzeichnisgruppe (Equipment, Richtlinien, Schulung) und weisen Sie diese Gruppe dann der vFound-Anwendung zu. https://vfound.io/api/scim/v2/Groups antwortet nur für Gruppen, die eine Schulung nennt, und lehnt jede andere Gruppe ab. Ihre Mitglieder sind die Personen (über ihre SCIM-Nutzer-ID), die die Schulung haben; eine Person, die die Gruppe verlässt, verliert die Schulung nur, wenn das Verzeichnis sie vergeben hat, sodass ein vom Team hinzugefügter Eintrag bleibt. Ein vom Verzeichnis vergebener Eintrag, der abgelaufen ist, wird ab dem Tag erneuert, an dem das Verzeichnis die Gruppe erneut sendet und die Person noch darin ist. Gruppen antworten nur für einen Standort mit Equipment. Weil die Gruppenmitgliedschaft eine Schulung vergibt und eine Schulung Personen ermöglicht, die Geräte zu erhalten, die sie verlangen, kann ein Schlüssel mit people:write auf diese Weise Schulungen vergeben: Behalten Sie diesen Schlüssel für Ihren Identitätsanbieter.
Webhooks
Fügen Sie unter Einstellungen, Für Entwickler oder über die API unten bis zu 25 HTTPS-Adressen hinzu und wählen Sie, welche der folgenden Ereignisse jede erhält. vFound sendet innerhalb von Sekunden einen JSON-POST, wiederholt fehlgeschlagene Zustellungen etwa drei Stunden lang und pausiert eine Adresse nach 15 fehlgeschlagenen Zustellungen in Folge.
| Ereignis | Wann | Daten |
|---|---|---|
item.created | Eine Fundsache wird hinzugefügt | Fundsache |
item.updated | Ihr Status, Titel, Ort, ihre Kategorie, das Datum für die Aufbewahrung oder die Sichtbarkeit des Fotos ändert sich | Fundsache |
item.transfer_sent | Eine Fundsache wird an einen anderen Standort der Gruppe gesendet (beide Standorte erhalten es) | Übergabe einer Fundsache |
item.transfer_cancelled | Der sendende Standort nimmt sie zurück, bevor sie ankommt | Übergabe einer Fundsache |
item.transfer_received | Der empfangende Standort bestätigt die Ankunft | Übergabe einer Fundsache |
claim.created | Ein Gast reicht eine Rückgabeanfrage ein | Rückgabeanfrage |
item.disposition_recorded | Eine Fundsache wird gespendet oder entsorgt | Fundsache |
item.match_updated | Eine gespeicherte KI-Einschätzung zu einem Treffer ändert sich; report_id, item_id, label und reason | Trefferpaar |
lost_report.match_updated | Eine gespeicherte KI-Einschätzung zu einem Treffer ändert sich; report_id, item_id, label und reason | Trefferpaar |
claim.ownership_reviewed | Ein Manager erfasst eine Prüfung der Eigentümerschaft; rufen Sie die Verwahrung für den Verlauf der Prüfungen ab | Rückgabeanfrage |
claim.decision_recorded | Eine Rückgabeanfrage wird angenommen oder abgelehnt | Rückgabeanfrage |
claim.release_approved | Ein anderer Manager gibt die Herausgabe frei | Rückgabeanfrage |
claim.handover_recorded | Die physische Abholung schließt eine Rückgabeanfrage im Status ready_for_pickup ab | Rückgabeanfrage |
claim.status_changed | Eine Rückgabeanfrage wechselt in einen neuen Status | Rückgabeanfrage |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | Ein Gast meldet einen Verlust | Verlustmeldung |
parcel.logged | Ein Paket wird am Empfang oder über die API erfasst | Paket |
parcel.updated | Eine seiner Angaben ändert sich am Empfang, etwa Empfänger, Sendungsnummer oder Regal | Paket |
parcel.reminded | Dem Empfänger wird eine Erinnerung gesendet, vom Empfang oder automatisch | Paket |
parcel.collected | Ein Paket wird übergeben | Paket |
parcel.returned | Ein Paket wird an den Absender zurückgesendet | Paket |
parcel.recipient_arrived | Ein Empfänger meldet, dass er am Empfang ist | Eintrag der Abholwarteschlange |
parcel.reminders_snoozed | Ein Empfänger pausiert seine Erinnerungen | Person und Anzahl der Pakete |
parcel.held | Ein Empfänger legt ein Datum für das Zurückhalten fest | Person, Datum und Anzahl der Pakete |
parcel.proxy_created | Ein Empfänger sendet einer bevollmächtigten Person per E-Mail einen Abholcode | Person, bevollmächtigte Person und Ablauf |
parcel.pickup_served | Der Empfang markiert eine Ankunft als bedient | Eintrag der Abholwarteschlange |
parcel.escalated | Ein wartendes Paket erreicht das Eskalationsalter des Standorts | Paket |
parcel.outgoing_logged | Ein ausgehendes Paket wird erfasst | Ausgehendes Paket |
parcel.outgoing_handed_over | Ein ausgehendes Paket wird einem Kurier übergeben | Ausgehende Übergabe |
parcel.round_created | Eine Zustellrunde wird erstellt | Zusammenfassung der Runde |
parcel.round_delivered | Ein Stopp einer Zustellrunde wird abgeschlossen | IDs von Runde, Stopp und Paket |
checkroom.checked_in | Etwas wird angenommen und erhält eine Nummer | Ticket |
checkroom.handed_back | Es wird zurückgegeben | Ticket |
checkroom.left | Der Abend wird abgeschlossen, während es noch in der Garderobe ist | Ticket |
checkroom.self_checkin_started | Ein Gast startet ein Ticket an einem gekoppelten Kiosk | Ticket |
checkroom.ready_requested | Ein Gast bittet den Empfang, seine Sachen bereitzumachen | Ticket |
checkroom.ready | Der Empfang markiert die Sachen eines Gastes als bereit | Ticket |
checkroom.station_created | Eine Garderobenstation wird erstellt | Station |
checkroom.station_updated | Eine Garderobenstation ändert sich | Station |
checkroom.event_created | Eine Veranstaltung der Garderobe wird erstellt | Ereignis |
checkroom.event_updated | Eine Veranstaltung der Garderobe ändert sich | Ereignis |
loan.checked_out | Ein Gerät wird ausgegeben | Ausgabe |
loan.due_soon | Die Rückgabezeit liegt weniger als zwei Stunden entfernt, einmal pro Rückgabezeit | Ausgabe |
loan.overdue | Die Rückgabezeit verstreicht und es ist nicht zurück, einmal pro Rückgabezeit | Ausgabe |
loan.extended | Die Rückgabezeit ändert sich | Ausgabe |
loan.returned | Es kommt zum Empfang zurück | Ausgabe |
loan.lost | Es wird als nicht zurückkommend erfasst | Ausgabe |
loan.checkout_created | Eine atomare Ausgabe mehrerer Geräte wird erstellt | Sammelausgabe, mit Bestand auf derselben Quittung in stock |
loan.self_checkout | Eine Person schließt die Ausgabe am Kiosk ab | Sammelausgabe |
loan.kit_created | Ein gespeichertes Set von Geräten wird erstellt | Set |
loan.kit_updated | Ein gespeichertes Set von Geräten ändert sich | Set |
loan.reservation_requested | Eine Reservierung wartet auf Genehmigung | Reservierung |
loan.reservation_created | Eine Reservierung wird sofort bestätigt | Reservierung |
loan.reservation_approved | Eine ausstehende Reservierung wird genehmigt | Reservierung |
loan.reservation_ready | Reservierte Geräte sind zur Abholung bereit | Reservierung |
loan.reservation_cancelled | Eine Reservierung wird storniert | Reservierung |
loan.reservation_collected | Reservierte Geräte werden übergeben | Sammelausgabe |
loan.extension_requested | Eine Person bittet um mehr Zeit | Ausgabe |
loan.problem_reported | Eine Person meldet ein Problem mit einem Gerät | Ausgabe |
loan.rule_updated | Eine Ausgaberegel für eine Kategorie ändert sich | Regel |
loan.maintenance_logged | Eine Wartung wird erfasst | Wartung |
loan.maintenance_due | Eine geplante Wartung wird fällig | Wartung |
loan.service_due | Ein wiederkehrender Wartungsplan wird fällig (nach Datum, Stunden der Ausgabe oder Anzahl der Ausgaben), einmal pro Runde | Wartung |
loan.work_order_opened | Ein Arbeitsauftrag wird eröffnet, vom Team oder durch eine Rückgabe, für die der Standort einen eröffnen lässt | Wartung |
loan.work_order_closed | Ein Arbeitsauftrag wird erledigt oder storniert | Wartung |
loan.item_disposed | Ein Gerät scheidet aus (verkauft, verschrottet, gespendet, recycelt, verloren oder gestohlen) | Equipment |
loan.stocktake_started | Eine Inventur der Geräte beginnt | Inventur |
loan.stocktake_completed | Eine Inventur der Geräte endet | Inventur |
loan.transfer_prepared | Ein berechtigter Standort bereitet Geräte für den Transport vor | Übergabe |
loan.transfer_sent | Vorbereitete Geräte verlassen ihren Ausgangsstandort | Übergabe |
loan.transfer_received | Der Zielstandort erhält die Geräte | Übergabe |
loan.transfer_rejected | Der Zielstandort lehnt eine vorbereitete Übergabe ab | Übergabe |
loan.transfer_cancelled | Der Ausgangsstandort bricht eine vorbereitete Übergabe ab | Übergabe |
loan.transfer_exception | Eine Übergabe unterwegs braucht Aufmerksamkeit | Übergabe |
loan.transfer_lost | Der Ausgangsstandort schließt eine Übergabe ab, die nie angekommen ist | Übergabe |
loan.charge_recorded | Ein Entgelt für Verspätung, Schaden, Ersatz, Nutzung oder anderes wird erfasst | Gebühreneintrag |
loan.charge_waived | Ein Manager erlässt, was eine Gebühr noch braucht, mit Begründung | Gebühreneintrag |
loan.payment_recorded | Das Team erfasst Geld, das der Standort selbst entgegengenommen hat (vFound wickelt nie eine Zahlung ab) | Gebühreneintrag |
loan.payment_voided | Ein Manager macht eine versehentlich erfasste Zahlung ungültig | Gebühreneintrag |
loan.deposit_recorded | Das Team erfasst eine Kaution, die der Standort entgegengenommen hat | Gebühreneintrag |
loan.deposit_resolved | Eine hinterlegte Kaution wird zurückgegeben oder einbehalten | Gebühreneintrag |
loan.invoice_issued | Eine Rechnung wird für die Gebühren einer Person ausgestellt | Rechnung |
loan.invoice_voided | Ein Manager macht eine Rechnung ungültig, mit Begründung | Rechnung |
loan.quote_accepted | Das Team nimmt ein Angebot an und seine Buchungen werden angelegt | Angebot |
loan.payment_request_created | Das Team erfasst eine Zahlungsaufforderung (an die Person wird nichts gesendet) | Zahlungsaufforderung |
loan.payment_request_paid | Zu einer Aufforderung erfasste Zahlungen decken sie vollständig ab | Zahlungsaufforderung |
loan.delivery_done | Eine Lieferung oder eine Abholung wird als erledigt markiert | Lieferung |
loan.items_imported | Ein CSV-Import von Geräten wird abgeschlossen | Anzahlen |
visit.expected | Ein Besucher wird eingeladen | Besuch |
visit.signed_in | Ein Besucher meldet sich an, am Empfang oder über Ihr QR-Schild | Besuch |
visit.host_confirmed | Der Empfang bestätigt, wen ein selbst angemeldeter Besucher besuchen wollte | Besuch |
visit.signed_out | Er meldet sich ab, am Empfang, über seinen Pass oder automatisch nach Ende des Tages | Besuch |
visit.cancelled | Eine Einladung wird storniert | Besuch |
visit.approval_requested | Ein Besuch wartet auf die Freigabe durch das Team | Besuch |
visit.approved | Ein ausstehender Besuch wird freigegeben | Besuch |
visit.denied | Ein ausstehender Besuch wird abgelehnt | Besuch |
visit.host_replied | Ein Gastgeber antwortet über seinen privaten Link | Besuch |
visit.roll_call_started | Eine Live-Anwesenheitskontrolle (ein Notfall, eine Übung oder ein Hinweis) startet | Zusammenfassung der Anwesenheitskontrolle |
visit.roll_call_completed | Eine Live-Anwesenheitskontrolle endet | Zusammenfassung der Anwesenheitskontrolle |
visitor_type.created | Eine Besucherart wird erstellt | Besucherart |
visitor_type.updated | Eine Besucherart ändert sich | Besucherart |
visitor_type.deactivated | Eine Besucherart wird deaktiviert | Besucherart |
visitor_agreement.signed | Ein Besucher hat ein Vereinbarungsdokument unterschrieben, mit einem Link zur unterschriebenen Kopie, der sieben Tage funktioniert | Unterschrift unter einer Vereinbarung |
kiosk.paired | Ein Besucher-Kiosk wird gekoppelt | Kiosk |
kiosk.revoked | Ein Besucher-Kiosk wird widerrufen | Kiosk |
courier.signed_in | Ein Lieferant wird als Besucher in Parcels erfasst | Kurier |
courier.signed_out | Ein Lieferant verlässt den Standort | Kurier |
staff.signed_in | Eine Person aus der Liste der Mitarbeitenden meldet sich an, im Büro oder remote | Anwesenheit der Mitarbeitenden |
staff.signed_out | Eine Person aus der Liste der Mitarbeitenden meldet sich ab oder wird automatisch abgemeldet | Anwesenheit der Mitarbeitenden |
person.created | Eine Person wird hinzugefügt | Person |
person.updated | Eine Person wird geändert | Person |
person.deactivated | Die Bereitstellung aus dem Verzeichnis deaktiviert eine Person | Person |
person.deleted | Eine Person wird entfernt | Person |
people.sync.completed | Eine verbundene CSV-Synchronisierung wird abgeschlossen | Anzahlen |
people.sync.failed | Eine verbundene CSV-Synchronisierung schlägt sicher fehl | Fehler |
report.delivered | Ein geplanter Bericht aus Berichte & Analysen, der mit dem Standort geteilt wird, läuft mit Zustellung an die gewählten Webhooks (ein privater Bericht wird nie an Webhooks gesendet); abonnieren Sie ihn unter Einstellungen, Für Entwickler (ein API-Schlüssel kann ihn nicht abonnieren) | Jede Spalte, die der Bericht nennt, und bis zu 5,000 Zeilen, oder jede Gruppe |
queue.ticket_joined | Eine Person stellt sich an einer Warteschlange an, über ihr Handy, einen Kiosk, den Empfang oder die API | Queue-Ticket |
queue.ticket_called | Eine Person wird an einen Schalter aufgerufen oder erneut aufgerufen | Queue-Ticket |
queue.ticket_served | Eine Person wird als bedient markiert | Queue-Ticket |
queue.ticket_no_show | Eine aufgerufene Person wird als nicht erschienen markiert, vom Team oder nach den Minuten der Warteschlange | Queue-Ticket |
queue.ticket_left | Eine Person verlässt die Warteschlange über ihr Ticket, oder das Team nimmt sie heraus | Queue-Ticket |
queue.ticket_transferred | Eine Person wird in eine andere Warteschlange oder an einen anderen Schalter verschoben | Queue-Ticket |
queue.ticket_closed | Ein Ticket, das am Ende des Tages des Standorts noch offen ist oder in einer archivierten Warteschlange liegt, wird geschlossen | Queue-Ticket |
queue.booking_created | Eine Person bucht eine Zeit auf der Seite für gebuchte Zeiten einer Warteschlange, oder die API bucht eine | Queue-Buchung |
queue.booking_cancelled | Eine gebuchte Zeit wird von der Person, vom Team oder von der API storniert | Queue-Buchung |
queue.ticket_arrived | Eine Person, die sich vor ihrer Ankunft angestellt hat, sagt, dass sie da ist, oder das Team markiert sie als angekommen | Queue-Ticket |
queue.message_received | Eine Person in der Warteschlange schreibt dem Team von ihrer Ticketseite aus; das Ereignis enthält keine Worte | Queue-Nachricht |
queue.message_sent | Das Team schreibt einer Person in der Warteschlange; das Ereignis enthält keine Worte | Queue-Nachricht |
queue.survey_answered | Eine bediente Person beantwortet die Umfrage; das Ereignis enthält die Bewertung und nie den Kommentar | Antwort auf die Queue-Umfrage |
{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
"venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}
Die Signatur prüfen
Jede Zustellung enthält Vfound-Signature: t=<unix time>,v1=<hex>, wobei der Hex-Wert ein HMAC SHA256 von t + "." + raw body mit dem Geheimnis Ihres Endpunkts ist. Weisen Sie Zustellungen zurück, die älter als fünf Minuten sind. Nachdem Sie ein neues Signaturgeheimnis erstellt haben, enthalten Zustellungen 24 Stunden lang zwei v1-Werte, einen für jedes Geheimnis; akzeptieren Sie die Zustellung daher, wenn einer davon passt.
// 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;
Die Header enthalten außerdem Vfound-Event und eine eindeutige Vfound-Delivery-ID, mit der Sie Wiederholungen ignorieren können. Webhooks werden nur an öffentliche HTTPS-Adressen auf Port 443 gesendet.
Über die API abonnieren
Werkzeuge wie Zapier können mit einem Schlüssel, der webhooks:manage hat, ihre eigenen Adressen hinzufügen und entfernen. Das Signaturgeheimnis wird einmal angezeigt, in der Antwort auf den POST. Die Antwort enthält außerdem einen Location-Header mit der Adresse, die Sie mit DELETE aufrufen, wenn das Abonnement entfernt wird.
Ein Schlüssel kann nur Ereignisse abonnieren, deren Daten er lesen könnte: Jedes Ereignis braucht den Lese-Scope seines Produkts (items:read für Ereignisse zu Fundsachen, claims:read für Ereignisse zu Rückgabeanfragen, lost_reports:read, parcels:read, checkroom:read, loans:read für Ereignisse zu Geräten, visitors:read für Ereignisse zu Besuchen, Besucherarten, Kiosken und Kurieren und people:read für Ereignisse zu Personen und zur Personenliste). Ein Schlüssel listet und entfernt nur die Adressen, die er selbst erstellt hat; unter Einstellungen oder von einem anderen Schlüssel hinzugefügte Adressen sind für ihn nicht sichtbar.
| Anfrage | Was sie tut | Scope |
|---|---|---|
| GET/webhooks | Die Adressen, die dieser Schlüssel erstellt hat, und ihre Ereignisse. | webhooks:manage |
| POST/webhooks | Eine Adresse hinzufügen: url (öffentliches HTTPS auf Port 443) und events, eine Liste der obigen Ereignisse, die der Schlüssel lesen kann. | webhooks:manage |
| DELETE/webhooks/{id} | Eine Adresse entfernen, die dieser Schlüssel erstellt hat, und ihren Zustellverlauf. | webhooks:manage |
Zustellverlauf
Unter Einstellungen, Für Entwickler, sind alle Zustellungen an jede Adresse der letzten 30 Tage aufgeführt, mit ihrem Ergebnis, und jede davon kann mit derselben Vfound-Delivery-ID erneut gesendet werden. Dort können Sie auch eine Adresse bearbeiten, eine pausierte wieder einschalten und ein neues Signaturgeheimnis erstellen. Eine Adresse, bei der 15 Zustellungen in Folge fehlschlagen, wird pausiert, und der Inhaber des Standorts erhält eine E-Mail.
Datenfeed für Berichte (Power BI)
Ein Inhaber oder Manager erstellt unter Berichte & Analysen, bei Power-BI-Datenfeed, einen Feed-Link für die Produkte, die er auswählt. Der Link wird nur einmal angezeigt. Wählen Sie in Power BI „Daten abrufen“, dann „Web“, und fügen Sie ihn ein. Jeder Link liest nur einen Standort und hört sofort auf zu funktionieren, wenn er widerrufen wird, wenn die Person, die ihn erstellt hat, nicht mehr Inhaber oder Manager des Standorts ist oder wenn der Standort pausiert oder geschlossen wird.
GET /api/feeds/reports/{token}/{dataset} liefert die Zeilen eines Datensatzes: equipment_loans, equipment_activity, visits oder checkroom_tickets. Wählen Sie den Zeitraum mit days (1 bis 366, 90, wenn weggelassen) oder from und to (YYYY-MM-DD, nach der Uhr des Standorts). GET /api/feeds/reports/{token}/saved/{id} liefert einen gespeicherten Bericht, der mit dem ganzen Standort geteilt wird, für den eigenen Zeitraum dieses Berichts; days, from und to ändern ihn nicht. Sie können den Token auch als Authorization: Bearer <token> an /api/feeds/reports/{dataset} oder /api/feeds/reports/saved/{id} senden. Eine Antwort enthält bis zu 100,000 Zeilen in value, sodass „Daten abrufen“, „Web“ das ganze Ergebnis liest; wandeln Sie dann die Liste value in eine Tabelle um. Die Antwort endet mit total und truncated: Wenn mehr Zeilen passen, als eine Antwort fasst, ist truncated true und @odata.nextLink nennt den Rest ($top und $skip blättern durch sie, für Werkzeuge, die ihm folgen); „Daten abrufen“, „Web“ folgt ihm nicht, wählen Sie daher einen kürzeren Zeitraum. Wenn die Zeilen eines Berichts mehr als 400,000 gelesene Zeilen oder mehr als 20 Sekunden bräuchten, endet die Antwort mit error, total null und truncated true; ein gruppierter gespeicherter Bericht antwortet stattdessen mit 422 und dem Grund. Die Zeilen kommen in der Reihenfolge, in der sie erfasst wurden. Zeiten in Zeilen sind UTC (ISO 8601); ein nach einem Datum gruppierter gespeicherter Bericht bezeichnet jede Gruppe nach Tag, Woche, Monat, Wochentag oder Stunde nach der Uhr des Standorts. E-Mail-Adressen sowie Name und Zimmer eines Garderobengastes bleiben weg, es sei denn, der Link wurde mit Kontaktdaten erstellt.
KI-Assistenten (MCP)
vFound ist ein Model-Context-Protocol-Server unter https://vfound.io/api/mcp, damit KI-Assistenten Dinge nachschlagen und am Empfang helfen können. Verbinden Sie einen auf eine von zwei Arten: Mit vFound anmelden, für Assistenten, deren Konnektoren sich mit OAuth anmelden, oder mit einem API-Schlüssel, für Clients, die einen Header senden, etwa Claude Code, Cursor und Visual Studio Code. In beiden Fällen sieht er nur die Werkzeuge, die seine Scopes erlauben, für die Produkte, die Ihr Standort geöffnet hat. Ein mit einem API-Schlüssel verbundener Client darf auch X-Acting-User senden; jedes Werkzeug läuft dann als dieses Teammitglied, im Rahmen seiner Rolle.
# 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_…"}}}}
| Werkzeug | Was sie tut | Scope |
|---|---|---|
search_found_items | Fundsachen mit Wörtern wie „schwarzes iPhone“ suchen | items:read |
list_expected_visitors | Eingeladene Besucher, die noch nicht da sind | visitors:read |
list_visitors_on_site | Jetzt angemeldete Besucher | visitors:read |
list_visitor_types | Besucherarten und ihre Regeln | visitors:read |
visitor_analytics | Summen, Muster und durchschnittliche Aufenthaltsdauer der Besucher | visitors:read |
visitor_registration_link | Der Link des Standorts zur Selbstregistrierung | visitors:read |
list_couriers_on_site | Über Visitors angemeldete Kuriere | parcels:read |
list_waiting_parcels | Pakete, die auf Abholung warten | parcels:read |
detect_parcel_tracking | Eine Sendungsnummer normalisieren und ihren Versanddienst erkennen | parcels:read |
parcel_pickup_queue | Personen, die an der Paketausgabe warten | parcels:read |
parcel_shelves | Kapazität und Belegung der Paketregale | parcels:read |
parcel_analytics | Paketmenge, Versanddienste und Leistung bei der Abholung | parcels:read |
list_outgoing_parcels | Ausgehende Pakete und ihr Stand der Übergabe | parcels:read |
list_parcel_rounds | Zustellrunden und Stopps für Pakete | parcels:read |
list_checkroom_exit_queue | Tickets, deren Gäste am Ausgang warten | checkroom:read |
mark_checkroom_ready | Ein wartendes Ticket als bereit markieren und den Gast benachrichtigen | checkroom:write |
list_checkroom_stations | Garderobenstationen und Nummernbereiche | checkroom:read |
list_checkroom_events | Vergangene und kommende Veranstaltungen der Garderobe | checkroom:read |
checkroom_report | Menge in der Garderobe, Rückgabezeit und Summen der Gebühren | checkroom:read |
list_queue_lines | Warteschlangen, wartende Personen und die geschätzte Wartezeit jetzt | queue:read |
list_queue_waiting | Heute wartende Personen, in der Reihenfolge des Aufrufs | queue:read |
queue_report | Summen der Queue und mittlere Warte- und Servicezeit in Minuten | queue:read |
call_next_in_queue | Die nächste Person an einen Schalter aufrufen | queue:write |
mark_queue_ticket_served | Die Person am Schalter als bedient markieren | queue:write |
list_overdue_equipment | Geräte, deren Rückgabezeit überschritten ist, und wer sie hat | loans:read |
list_equipment_kits | Gespeicherte Gruppen von Geräten | loans:read |
create_equipment_kit | Ein wiederverwendbares Set von Geräten speichern, ohne es auszugeben | loans:write |
list_equipment_reservations | Reservierungen nach Zeit und Status | loans:read |
reserve_equipment | Ein Gerät oder eine Kategorie reservieren, ohne es auszugeben | loans:write |
book_repeating_reservation | Ein Gerät, eine Kategorie oder einen Platz jeden Tag oder jede Woche buchen | loans:write |
move_reservation | Eine Reservierung auf neue Zeiten oder ein anderes Gerät ihrer Kategorie verschieben | loans:write |
list_waitlist | Die Personen, die auf eine vergebene Zeit warten | loans:read |
join_waitlist | Jemanden auf die Warteliste setzen | loans:write |
list_space_bookings | Jeder Raum, Arbeitsplatz oder Parkplatz und seine Buchungen zwischen zwei Zeiten | loans:read |
book_space | Einen Raum oder Platz für eine Person und Zeit buchen; er wird nie ausgegeben | loans:write |
list_equipment_rules | Ausgaberegeln des Standorts und der Kategorien | loans:read |
save_equipment_rule | Eine Kategorieregel erstellen oder ersetzen | loans:write |
list_equipment_maintenance | Wartungsverlauf der Geräte und anstehende Arbeit | loans:read |
list_equipment_service_plans | Wiederkehrende Pläne für Wartung, Kalibrierung, Sicherheitsprüfung, Inspektion und Reinigung und welche fällig sind | loans:read |
update_equipment_work_order | Einen Arbeitsauftrag für ein Gerät ändern oder abschließen | loans:write |
get_equipment_maintenance_costs | Kosten für Wartung, Reparatur und Reinigung je Gerät | loans:read |
get_equipment_valuation | Der Wert der Geräte an einem Datum nach Abschreibung (Inhaber und Manager) | loans:read |
list_equipment_substances | Das Gefahrstoffverzeichnis: Stoff, Ort, Gefahrenklassen und Prüftermine (ein Verzeichnis, keine Sicherheitsberatung) | loans:read |
get_equipment_funding | Was jeder Fonds, jeder Zuschuss oder jede Kostenstelle gekauft hat und welche Arbeit ihnen belastet wurde (Inhaber und Manager) | loans:read |
get_equipment_planner | Geplante Arbeit und offene Arbeitsaufträge nach dem eigenen Tag des Standorts | loans:read |
list_equipment_licences | Lizenzen für die Geräte mit Plätzen und Enddaten (Inhaber und Manager) | loans:read |
get_equipment_expiries | Versicherungen und Lizenzen, die bald enden oder bereits beendet sind (Inhaber und Manager) | loans:read |
log_equipment_maintenance | Wartung, Kalibrierung, eine Sicherheitsprüfung, eine Inspektion, Reinigung, eine Reparatur oder eine Notiz erfassen | loans:write |
list_equipment_stocktakes | Aktuelle Inventuren und ihre Zählungen | loans:read |
start_equipment_stocktake | Eine Inventur starten | loans:write |
scan_equipment_stocktake | Ein Gerät in einer offenen Inventur erfassen | loans:write |
scan_many_equipment_stocktake | Viele Codes in einer offenen Inventur auf einmal zählen | loans:write |
finish_equipment_stocktake | Eine Inventur abschließen und zurückgeben, was fehlt | loans:write |
list_equipment_transfers | Eingehende und ausgehende Übergaben ohne Angaben zur Person | loans:read |
preview_equipment_import | Eine CSV-Datei mit Geräten prüfen, ohne sie zu speichern | loans:write |
find_person | Jemanden in der Personenliste nachschlagen | people:read |
export_people | Die Personenliste als formelsicheres CSV exportieren | people:read |
directory_sync_status | Die gespeicherte CSV-Verbindung und ihren letzten Lauf prüfen | people:read |
run_directory_sync | Die gespeicherte CSV-Verbindung jetzt ausführen | people:write |
email_my_vfound | Einer Person ihre signierte private Seite per E-Mail senden | people:write |
invite_visitor | Einen Besucher einladen, der per E-Mail einen Pass erhält | visitors:write |
approve_visit | Eine ausstehende Besuchsanfrage freigeben | visitors:write |
list_free_workplace_spaces | Freie Arbeitsplätze, Besprechungsräume oder Parkplätze für eine Zeit finden | visitors:read |
book_workplace_space | Einen Arbeitsplatz, Besprechungsraum oder Parkplatz für eine Person buchen | visitors:write |
request_visit_catering | Catering zu einem Besuch anfragen, aus den Optionen, die der Standort auflistet | visitors:write |
list_appointment_pages | Die Terminseiten des Standorts auflisten und ob jede für Besucher offen ist | visitors:read |
list_staff_on_site | Personen aus der Liste der Mitarbeitenden auflisten, die jetzt angemeldet sind, im Büro oder remote | visitors:read |
sign_staff_in_or_out | Eine Person aus der Liste der Mitarbeitenden an- oder abmelden | visitors:write |
list_visitor_assets_not_returned | Dinge auflisten, die Besuchern übergeben und noch nicht als zurück markiert wurden | visitors:read |
issue_visitor_asset | Ein Ding erfassen, das einem erwarteten oder angemeldeten Besuch übergeben wurde | visitors:write |
return_visitor_asset | Ein einem Besuch übergebenes Ding als zurückgegeben markieren | visitors:write |
start_roll_call | Die aktive Anwesenheitskontrolle starten oder zurückgeben | visitors:write |
mark_visitor_safe | Einen Besucher als in Sicherheit markieren | visitors:write |
create_kiosk_pairing | Einen Kopplungscode für einen Kiosk erstellen, der zehn Minuten gilt | visitors:write |
log_parcel | Ein Paket erfassen und dem Empfänger eine E-Mail senden | parcels:write |
remind_parcel | Einen Empfänger daran erinnern, ein Paket abzuholen | parcels:write |
remind_parcels | Bis zu 200 ausgewählte Paketempfänger erinnern | parcels:write |
log_outgoing_parcel | Ein ausgehendes Paket zum Kurierbuch hinzufügen | parcels:write |
create_parcel_round | Eine Zustellrunde aus wartenden Paketen erstellen | parcels:write |
extend_loan | Einer Person mehr Zeit geben | loans:write |
Jedes Werkzeug führt die obige API-Anfrage mit denselben Prüfungen aus, sodass ein Assistent nie mehr tun kann als sein Schlüssel oder seine Verbindung. Es gibt keine Werkzeuge, die etwas übergeben, jemanden an- oder abmelden, über eine Rückgabeanfrage entscheiden oder etwas löschen. Jede Antwort zählt auf die 120 Anfragen pro Minute des Schlüssels oder der Verbindung.
Mit vFound anmelden
Fügen Sie https://vfound.io/api/mcp in Ihrem eigenen Assistenten als Konnektor hinzu. Der Assistent findet selbst heraus, wie er sich anmeldet, und öffnet eine vFound-Seite, auf der sich ein Inhaber oder Manager wie gewohnt in seinem Arbeitsbereich anmeldet, den Standort wählt, in einfachen Worten sieht, was der Assistent darf, und alles abwählen kann. Mitarbeitende und Mitglieder nur mit Leserechten können keinen Assistenten verbinden. Der Assistent gehört Ihrem Standort: Ihr Abonnement beim Anbieter bezahlt seine KI, und vFound erhält nur die Werkzeuganfragen, die er sendet.
Eine Verbindung handelt als die Person, die sie erlaubt hat, mit denselben Prüfungen wie ein API-Schlüssel: Sie funktioniert nicht mehr, wenn diese Person den Standort nicht mehr verwaltet oder der Standort nicht aktiv ist, sie ändert nichts, solange das Abonnement pausiert ist, und sie sieht Werkzeuge nur für geöffnete Produkte. Ihr Zugriffstoken gilt eine Stunde und der Assistent erneuert es selbst; eine Verbindung, die 30 Tage nicht genutzt wird, meldet sich erneut an. Sehen Sie unter Einstellungen, Für Entwickler jede einzelne, wer sie verbunden hat und wann sie zuletzt genutzt wurde; dort beendet Trennen sie sofort. Der Token funktioniert nur am MCP-Endpunkt, nicht in der REST-API; eine App, die die REST-API braucht, verbindet sich, wie der nächste Abschnitt es beschreibt.
Für Entwickler von Clients: OAuth 2.1, wie es die MCP-Autorisierungsspezifikation beschreibt, nur mit dem Authorization-Code-Ablauf und PKCE (S256). Discovery: /.well-known/oauth-protected-resource (RFC 9728, resource https://vfound.io/api/mcp) und /.well-known/oauth-authorization-server (RFC 8414); eine Anfrage ohne Token erhält einen WWW-Authenticate-Header, der den ersten nennt. Clients registrieren sich selbst unter /oauth/register (RFC 7591) als öffentliche Clients ohne Geheimnis; Weiterleitungsadressen müssen https verwenden, oder http nur für localhost oder 127.0.0.1, und müssen dann genau übereinstimmen. Dann /oauth/authorize, /oauth/token (Codes gelten 60 Sekunden und funktionieren einmal; Refresh-Tokens werden bei jeder Verwendung ersetzt, und die Wiederverwendung eines alten trennt den Assistenten) und /oauth/revoke (RFC 7009). Scopes verwenden die oben genannten Namen der API-Schlüssel; senden Sie resource=https://vfound.io/api/mcp (RFC 8707).
Mit vFound für andere Apps anmelden
Eine App, die kein KI-Assistent ist, etwa ein Bestands-, Buchungs- oder Personalsystem, kann sich auf dieselbe Weise statt mit einem API-Schlüssel mit der REST-API verbinden: Senden Sie resource=https://vfound.io/api/v1 an /oauth/authorize und /oauth/token, mit Scopes in den Namen der API-Schlüssel, außer webhooks:manage, das einer App nicht gegeben werden kann. Ein Inhaber oder Manager meldet sich an, sieht den Namen der App und in einfachen Worten, was sie darf, kann alles abwählen und erlaubt sie. Die Verbindung handelt als diese Person mit denselben Prüfungen wie ein API-Schlüssel: Sie funktioniert nicht mehr, wenn die Person den Standort nicht mehr verwaltet oder der Standort nicht aktiv ist, sie ändert nichts, solange das Abonnement pausiert ist, und sie darf wie ein Schlüssel 120 Anfragen pro Minute stellen. X-Acting-User funktioniert nur mit einem API-Schlüssel. Ihr Zugriffstoken funktioniert nur in der REST-API, nie am MCP-Endpunkt, und eine für das eine gezeigte Einwilligung genehmigt nie das andere. Sie wird unter Einstellungen, Für Entwickler als App aufgeführt, die die vFound API nutzt; dort beendet Trennen sie sofort. Discovery: /.well-known/oauth-protected-resource/api/v1; der Rest ist der obige Ablauf.
Fehler
Fehler sind JSON mit einer message; Validierungsfehler fügen errors nach Feld hinzu. 401 bedeutet, dass kein gültiger Schlüssel vorliegt, 403 einen fehlenden Scope, einen Schlüssel, dessen Ersteller den Standort nicht mehr verwaltet, ein Teammitglied in X-Acting-User, das kein aktives Mitglied ist oder dessen Rolle den Scope nicht erlaubt, einen Standort, der nicht aktiv ist, oder eine Änderung, die gesendet wurde, während das Abonnement pausiert ist, 404 nicht gefunden an Ihrem Standort, 422 ungültige Eingabe und 429 zu viele Anfragen.
Wenn eine Änderung wegen des aktuellen Zustands des Datensatzes nicht möglich ist, lautet die Antwort 422, ebenfalls mit einem stabilen code. Die Codes ändern nie ihren Namen:
| Code | Was er bedeutet |
|---|---|
parcel_not_waiting | Das Paket wartet nicht mehr: Es wurde bereits abgeholt, zurückgesendet oder zugestellt. |
tracking_duplicate | Ein Paket mit dieser Sendungsnummer wartet hier bereits. |
no_email | Die Person oder der Besucher hat keine E-Mail-Adresse, daher kann nichts gesendet werden. |
capacity_full | Jede Nummer der Garderobe ist in Gebrauch. |
already_checked_in | Das Garderobenticket ist bereits angenommen. |
already_handed_back | Das Garderobenticket wurde bereits zurückgegeben. |
nothing_to_hand_back | Beim Garderobenticket gibt es nichts zurückzugeben. |
number_in_use | Diese Nummer der Garderobe ist bereits in Gebrauch. |
ticket_closed | Nur ein offenes Garderobenticket kann per E-Mail gesendet werden. |
item_out | Das Gerät ist bei jemandem. Nehmen Sie es zuerst zurück. |
item_in_repair | Das Gerät ist für eine Reparatur beiseitegelegt. |
item_retired | Das Gerät ist ausgemustert und kann daher weder ausgegeben noch reserviert werden. |
reservation_conflict | Jemand hat das Gerät oder das letzte freie seiner Kategorie in dieser Zeit reserviert, oder es wird erwartet, dass es noch ausgegeben ist. |
already_back | Das Gerät wurde bereits zurückgenommen. |
not_out | Das Gerät ist nicht ausgegeben und kann daher weder mehr Zeit noch eine Erinnerung erhalten noch als nicht zurückkommend markiert werden. |
borrower_overdue | Die Person hat überfällige Geräte, und der Standort oder die Kategorie erlaubt nichts weiter, bis sie zurück sind. |
borrower_item_limit | Damit hätte die Person mehr Geräte, als der Standort oder die Kategorie gleichzeitig erlaubt. |
reservation_not_ready | Die Reservierung ist noch nicht genehmigt, oder sie wurde bereits abgeholt oder storniert. |
reservation_item_mismatch | Die Ausgabe enthält nicht das Gerät, für das die Reservierung gilt. |
reservation_category_mismatch | Die Ausgabe enthält ein Gerät außerhalb der reservierten Kategorie. |
reservation_borrower_mismatch | Die Reservierung gehört einer anderen Person. |
reservation_too_long | Die Reservierung ist länger, als die Kategorie ausgegeben werden kann. Nur Reservierungen aus My vFound sind auf diese Weise begrenzt. |
reservation_daily_limit | Die Person hat in den letzten 24 Stunden bereits 5 Reservierungen aus My vFound vorgenommen. |
booking_notice | Die Reservierung beginnt früher, als es der Mindestvorlauf der Kategorie erlaubt. |
booking_too_far_ahead | Die Buchung, die Ausgabe oder die neue Rückgabezeit endet später, als die Kategorie im Voraus gebucht werden kann. |
desk_closed | Die Reservierung würde an einem Tag beginnen, an dem der Geräteempfang geschlossen ist. |
kit_unavailable | Ein Teil eines Sets oder Warenkorbs ist für diese Zeit nicht verfügbar, daher wurde nichts reserviert. Das Feld unavailable listet jedes Teil und den Grund. |
borrower_not_in_group | Der Standort lässt nur Personen mit einer Nutzerart Geräte nutzen oder buchen, und diese Person hat keine (oder wurde eingetippt, statt aus der Personenliste gewählt zu werden). |
category_not_allowed | Keine der Nutzerarten der Person erlaubt diese Kategorie. |
borrower_on_hold | Die Ausgabe an diese Person ist pausiert: Das Team hat eine Sperre verhängt, der Standort pausiert die Ausgabe nach wiederholten verspäteten Rückgaben, oder sie schuldet mindestens den Betrag, ab dem der Standort sperrt (Art charges). Das Feld hold nennt die Art und bis wann. |
space_too_small | Mehr Personen, als der Raum oder Platz fasst (seine Kapazität). |
kit_locked | Das Gerät gehört zu einem gesperrten Set, das nur als Ganzes hinausgeht: Nehmen Sie jedes benannte Gerät des Sets auf. |
approval_not_yours | Der Standort hat Genehmigende in einer Reihenfolge festgelegt, und diese Person ist nicht die nächste (oder der Standort lässt niemanden einen Schritt für sie überspringen). |
project_not_approved | Die Buchung gehört zu einem Projekt, das noch nicht genehmigt ist, daher kann nichts abgeholt werden. |
not_enough_credits | Der Standort nutzt Buchungsguthaben, und diese Person hat keines mehr. Geben Sie ihr zuerst welches. Eine Buchung, die storniert oder nie abgeholt wird, gibt ihr Guthaben zurück. |
risk_assessment_pending | Die Buchung hat eine Risikobewertung, die nicht genehmigt wurde, daher kann nichts abgeholt werden. |
series_unavailable | Eine wiederkehrende Buchung konnte nicht erstellt werden, weil mindestens einer ihrer Termine vergeben ist oder gegen eine Buchungsregel verstößt, daher wurde nichts reserviert. Das Feld skipped listet jeden Termin und den Grund. |
time_available | Die Zeit, auf die jemand warten wollte, ist frei; buchen Sie sie daher, statt sich auf die Warteliste zu setzen. |
space_not_handed_out | Ein Raum oder Platz wird für seine Zeit gebucht und nie ausgegeben, daher kann er weder ausgegeben noch abgeholt werden. |
stock_short | Von diesem Bestandsartikel ist am genannten Ort (und in der genannten Charge) nicht genug da, daher hat sich nichts geändert. Das Feld available nennt die Menge dort. |
stock_issue_closed | Alles aus dieser Ausgabe von Bestand ist bereits zurück oder abgeschrieben. |
order_closed | Eine Bestellung ist abgeschlossen oder storniert und kann sich nicht ändern. |
order_over_received | Es wurde mehr eingegeben, als eine Bestellzeile noch erwartet. |
order_not_placed | Bestand kann nicht gegen eine Bestellung gebucht werden, die noch ein Entwurf ist. |
fees_off | Gebühren sind für diesen Standort aus. Schalten Sie sie zuerst in den Richtlinien für Empfang und Ausgabe ein. |
entry_closed | Dieser Gebühreneintrag oder diese Rechnung kann sich auf diese Weise nicht mehr ändern: Die Gebühr ist beglichen oder erlassen, die Zahlung ist ungültig gemacht, die Kaution wurde zurückgegeben oder einbehalten, oder die Rechnung ist ungültig. |
on_invoice | Die Gebühr steht auf einer ausgestellten Rechnung. Machen Sie zuerst die Rechnung ungültig und erlassen Sie dann die Gebühr. |
not_late | Die Ausgabe kam nach den Regeln des Standorts für Verspätungsentgelte nicht verspätet zurück, oder sie ist noch draußen. |
nothing_to_invoice | Die Person hat in dieser Währung keine offene Gebühr, die nicht schon auf einer ausgestellten Rechnung steht. |
charge_unavailable | Eine der gewählten Gebühren ist nicht offen, steht auf einer anderen Rechnung oder gehört einer anderen Person. |
desk_kept | Der Arbeitsplatz ist an einem der gewünschten Tage für eine andere Person reserviert. |
desk_has_bookings | Den Arbeitsplatz für diese Person zu reservieren würde an diesen Tagen mit offenen Buchungen anderer kollidieren. Stornieren Sie diese zuerst. |
booking_closed | Die Buchung des Arbeitsplatzes, Raums oder Parkplatzes wurde storniert oder freigegeben und kann daher nicht angemeldet werden. |
check_in_closed | Die Anmeldung öffnet 15 Minuten vor Beginn einer Buchung und schließt, wenn sie endet. |
item_service_due | Der Standort lässt Geräte, die Arbeit brauchen, nicht hinausgehen, und der Wartungstermin dieses Geräts ist erreicht oder einer seiner Pläne ist fällig. Erfassen Sie zuerst die Arbeit. |
item_failed_inspection | Der Standort lässt Geräte, die Arbeit brauchen, nicht hinausgehen, und die letzte Prüfung dieses Geräts ist fehlgeschlagen. Erfassen Sie zuerst eine bestandene. |
work_order_closed | Dieser Arbeitsauftrag ist bereits abgeschlossen und kann nicht geändert werden. |
already_disposed | Dieses Gerät ist bereits ausgeschieden. |
not_disposed | Dieses Gerät ist nicht ausgeschieden, daher gibt es nichts rückgängig zu machen. |
item_disposed | Dieses Gerät ist ausgeschieden. Machen Sie den Abgang rückgängig, bevor Sie es wieder verwenden. |
training_required | Eine Kategorieregel oder das Gerät verlangt eine Schulung, die die Person nicht hat oder nur nach ihrem Ablaufdatum hat. Das Feld training nennt, was fehlt. |
stocktake_open | Eine Inventur ist bereits offen. Schließen Sie sie zuerst ab. |
item_unavailable | Das Gerät ist nicht verfügbar oder für eine Reparatur beiseitegelegt und kann daher keine Übergabe starten. |
transfer_open | Das Gerät hat bereits eine offene Übergabe. |
transfer_not_ready | Nur eine vorbereitete Übergabe kann gesendet werden. |
transfer_not_in_transit | Nur Geräte unterwegs können entgegengenommen oder mit einem Problem markiert werden. |
transfer_already_sent | Eine gesendete Übergabe kann nicht mehr abgebrochen oder abgelehnt werden. |
already_signed_in | Der Besucher ist bereits angemeldet. |
visit_closed | Der Besuch ist abgeschlossen. Melden Sie den Besucher als neuen Besuch an. |
not_signed_in | Der Besucher ist nicht angemeldet. |
not_expected | Nur ein erwarteter Besuch kann storniert werden oder einen Pass erhalten. |
approval_required | Der Besuch braucht eine Freigabe, bevor sich der Besucher anmelden kann. |
visit_not_valid_today | Der Pass kann heute nicht noch einmal verwendet werden, oder heute liegt außerhalb seiner Daten. |
plus_one_not_allowed | Der Pass erlaubt keine Begleitung, oder er ist nicht mehr freigegeben, erwartet oder gültig. |
plus_one_limit | Der Besucher hat jede Begleitung hinzugefügt, die der Pass erlaubt. |
nobody_to_sign_in | Niemand aus der Gruppe des Besuchs wird heute erwartet. |
visitor_capacity_full | Die Anmeldung des Besuchers würde das Limit des Standorts oder der Besucherart für gleichzeitig angemeldete Besucher überschreiten. |
Die Anmeldung eines Besuchers am Empfang antwortet mit 409 und einem code, wenn der Besucher zuerst eine Prüfung durch ein Teammitglied braucht. Die Antwort nennt nur die Art des Treffers (blocklist, building, restricted_party oder answers); der Eintrag, sein Name und sein Grund sind für das Team des Standorts bestimmt und stehen nie in einer API-Antwort. Senden Sie die Anfrage erneut mit screening_reviewed auf true erst, wenn ein Teammitglied den Treffer geprüft hat. Das erfordert einen Schlüssel mit dem Scope visitors:screening (standardmäßig aus, ebenso wie der Zugriff jedes anderen Schlüssels darauf), und ein Schlüssel, der ein Teammitglied in X-Acting-User nennt, braucht eines, dessen Rolle über Besuche entscheidet. Die Bestätigung wird als die des Schlüssels mit seinem Namen erfasst, nie als die des Teammitglieds, das den Schlüssel erstellt hat. Ohne den Scope lautet die Antwort 403 mit screening_scope. Dasselbe gilt für die Freigabe eines Besuchs, den ein Treffer zurückhält:
| Code | Was er bedeutet |
|---|---|
screening_match | Der Besucher stimmt mit einer der Sperrlisten des Standorts, einer Prüfung durch das Team oder der Prüfliste überein. Ein Teammitglied muss bestätigen, dass es den Treffer geprüft hat, bevor der Besucher angemeldet wird. |
screening_scope | Die Anfrage bestätigt oder genehmigt einen Treffer der Prüfung, und der Schlüssel hat den Scope visitors:screening nicht (oder das in X-Acting-User genannte Teammitglied entscheidet nicht über Besuche). |
Checklisten für Abläufe
Ein Standort mit vFound Enterprise kann die Schritte festlegen, die seine Mitarbeitenden in einem entscheidenden Moment bestätigen: eine Fundsache erfassen, übergeben, spenden oder entsorgen; ein Paket übergeben oder zurücksenden; in der Garderobe annehmen oder zurückgeben; Geräte ausgeben oder zurücknehmen; und einen Besucher an- oder abmelden. Solange eine gilt, nehmen diese Anfragen ein Feld checklist an: [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}] oder ein Objekt aus key mit true oder Notiztext. 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 und POST /visitors/{id}/sign-out akzeptieren es. Ohne die erforderlichen Schritte lautet die Antwort 422 mit dem Code checklist_incomplete und einem Objekt checklist, das die noch zu bestätigenden Schritte nennt, und nichts ändert sich. Gilt keine Checkliste, wird das Feld ignoriert. Die abgeschlossenen Checklisten, mit der Angabe, wer sie wann bestätigt hat, stehen in checklists bei den Antworten zu einzelnen Fundsachen, Rückgabeanfragen, Paketen, Tickets, Ausgaben und Besuchen.
| Code | Was er bedeutet |
|---|---|
checklist_incomplete | 422: Für diesen Schritt gilt eine Checkliste für Abläufe, und ihre erforderlichen Schritte sind nicht bestätigt. |
Wiederholungen mit einem Idempotency-Key-Header können ebenfalls mit einem code antworten:
| Code | Was er bedeutet |
|---|---|
idempotency_key_invalid | 400: Der Header ist nicht 1 bis 191 sichtbare ASCII-Zeichen lang. |
idempotency_key_reused | 422: Dieser Schlüssel wurde bereits für eine andere Anfrage verwendet. |
idempotency_in_progress | 409: Die erste Anfrage mit diesem Schlüssel läuft noch. Versuchen Sie es in Kürze erneut. |
offline_in_progress | Die erste Kopie dieser Offline-Aktion wird noch gespeichert. Das Gerät sendet sie in Kürze erneut. |
Eine Anfrage, die ein Teammitglied in X-Acting-User nennt, kann ebenfalls mit einem code antworten:
| Code | Was er bedeutet |
|---|---|
acting_user_refused | 403: Der Header nennt nicht genau ein aktives Teammitglied dieses Standorts, oder der Schlüssel ist eine durch Anmeldung erstellte Verbindung. |
acting_user_role | 403: Das genannte Teammitglied kann den Scope dieser Operation mit seiner Rolle am Standort nicht nutzen. |