Museum360

Legacy API Referentie

Dit zijn de gemigreerde REST API-endpoints van het Museum360-platform. Deze endpoints zijn een 1:1 recreatie van de oorspronkelijke .NET API, zodat de bestaande VR/WebGL-client alleen de base URL hoeft te wijzigen.

Endpoints

Categorieën

JWT

Authenticatie

Overzicht per categorie

Categorie	Endpoints	Beschrijving
Token	1	Authenticatie & tokens
Unity	5	VR/WebGL client data
Question	3	Antwoorden controleren
UserStatistic	7	Statistieken & bezoeken
User	2	Registratie & controle
GoldCube	1	Puzzel letters

Snel starten

Volg deze 3 stappen om je eerste API-aanroep te doen. Alles wat je nodig hebt is een API key en een terminal.

Vraag een access token aan

Stuur een POST-verzoek naar /token met je API key en inloggegevens. Dit geeft een JWT token terug dat je bij alle volgende aanroepen gebruikt.

curl -X POST https://api-accp.museum360.nl/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&apikey=YOUR_API_KEY&Username=your_user&Password=your_pass&language=nl"

Je krijgt een JSON-response met een access_token veld. Kopieer deze waarde.

Haal de lijst met venues op

Gebruik je token om de lijst van alle beschikbare venues (musea) op te halen.

curl https://api-accp.museum360.nl/Unity/GetPointOfInterests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Dit geeft een object terug met languages (beschikbare talen) en pointOfInterests (alle venues).

Haal venue-details op

Haal de volledige data van een specifieke venue op, inclusief verdiepingen, kamers, items, vragen en media.

curl https://api-accp.museum360.nl/Unity/GetPointOfInterest/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Vervang /1 door het legacy ID van de venue die je wilt opvragen.

Tip: Voor snelle tests zonder inloggegevens kun je de guest grant gebruiken: grant_type=guest&apikey=YOUR_KEY&guest_id=test123&language=nl

Typische API-flow

POST /token

GET /Unity/*

Venue data laden

POST /Question/*

Antwoorden checken

POST /UserStatistic/*

Voortgang opslaan

GET /GoldCube/*

Puzzel ontgrendelen

Authenticatie

De meeste endpoints vereisen een Bearer token in de Authorization header. Tokens worden verkregen via het /token endpoint.

Authorization: Bearer <access_token>

Authenticatie niveaus

Public

Geen token vereist. De aanroep is open voor iedereen.

Bearer Token

Een geldig JWT token is verplicht in de Authorization header.

Optional Auth

Token is optioneel. Kan ook localUsername als query parameter gebruiken.

Tokens verlopen na 24 uur (86400 seconden). Vraag een nieuw token aan als je een 401-response krijgt.

Token

1 endpoint

OAuth-achtig token endpoint voor authenticatie. Alle grant types vereisen een geldige API key. Dit is altijd de eerste stap: zonder token kun je geen andere endpoints aanroepen.

Vraag een access token aan. Ondersteunde grant_types: password, guest, vredvr, wix, password+loginType=card.

Content-Type: application/x-www-form-urlencoded

De apikey parameter is verplicht en wordt vergeleken met LEGACY_API_KEY. De card grant maakt automatisch een account aan als de gebruiker nog niet bestaat.

Unity

5 endpoints

Endpoints voor de VR/WebGL client om venue-data, vertalingen en publieke ruimte-informatie op te halen. Dit is de kern van de API — hier laadt de VR-ervaring alle content.

Redirect (302) naar het CSV-vertaalbestand voor de VR/WebGL client UI-teksten. Dit bestand bevat alle interface-vertalingen die de VR-client toont.

Controleert of een venue (point of interest) bestaat en toegankelijk is. Gebruik dit om te checken of de gebruiker een venue mag betreden voordat je de volledige data laadt.

Haalt de publieke ruimte (public square) data op. Dit is het startpunt/lobby van de VR-ervaring. Geeft null + 404 als er geen publieke ruimte is geconfigureerd.

Haalt ALLE venues op met bijbehorende talen. Dit is de eerste data-aanroep die de VR-client doet na authenticatie — het toont de lijst van beschikbare musea/locaties.

Haalt een enkele venue op met ALLE details: verdiepingen, kamers, items, vragen, antwoorden, audio, video, highlights, promoties, en meer. Dit is de grootste response in de API.

Haalt een venue op met versiecontrole. Gebruik dit om bandbreedte te besparen: als de client al de juiste versie heeft, stuurt de API alleen een kort bericht in plaats van de volledige data.

Als versionNumber > huidige versie, retourneert 400 'Invalid version number'. Gebruik latestVersion uit GetPointOfInterests om de juiste versie mee te sturen.

Question

3 endpoints

Endpoints voor het controleren van antwoorden op vragen bij items in een venue. Er zijn twee types vragen: meerkeuze (AnswersCheck) en open vragen (OpenAnswerCheck).

Controleert meerkeuze-antwoorden. Stuur de vraag-ID en de gekozen antwoorden. Geeft true als ALLE antwoorden correct zijn, anders false.

questionId en answerId zijn legacy integer IDs. Een antwoord is correct als answerChoice precies overeenkomt met het is_correct veld in de database voor elk antwoord.

Haalt het eerder opgeslagen open antwoord op voor een open vraag. Retourneert de tekst die de gebruiker eerder heeft ingevuld, of null als er nog geen antwoord is.

Werkt alleen voor vragen van type 5 (open antwoord). Retourneert 404 voor andere vraagtypen.

Slaat een open antwoord op. Maakt of updatet een user_statistic record met de antwoordtekst. Retourneert altijd true (open antwoorden zijn niet goed/fout).

UserStatistic

7 endpoints

Endpoints voor gebruikersstatistieken, bezoeken en locatiebeheer. Hier wordt de voortgang van de gebruiker opgeslagen: welke vragen zijn beantwoord, welke kamers bezocht, en waar de gebruiker gebleven is.

Haalt geaggregeerde statistieken op voor een venue: hoeveel vragen correct beantwoord, totaal aantal vragen, en welke GoldCube-letters ontgrendeld zijn.

Haalt statistieken op via een item ID. Zoekt automatisch de bijbehorende venue op via de keten: item → kamer → verdieping → venue.

Haalt alle beantwoorde vragen op voor een venue. Geeft een array terug met voor elke beantwoorde vraag of het correct was en eventuele open-antwoord tekst.

Haalt de laatst opgeslagen locatie van de gebruiker op: welke venue, verdieping en kamer. Gebruik dit om de gebruiker terug te brengen naar waar ze gebleven waren.

Slaat een antwoordstatistiek op. Als de gebruiker deze vraag al beantwoord heeft, wordt het record bijgewerkt (upsert). Retourneert een lege 200 response.

Voor guest/vredvr grant types wordt body.username gebruikt; voor normale gebruikers wordt het username uit het token gebruikt.

Registreert een bezoek aan een venue of item. Dedupliceert per dag: maximaal één bezoek per dag per type, zodat de statistieken nauwkeurig zijn.

Slaat de huidige locatie van de gebruiker op, zodat ze later kunnen terugkeren waar ze gebleven waren. Overschrijft de vorige locatie (upsert).

User

2 endpoints

Endpoints voor gebruikersregistratie en mobiel nummer controle. Gebruikt voor het aanmaken van nieuwe accounts via de VR-client of Wix-integratie.

Registreert een nieuwe gebruiker op basis van mobiel nummer. Maakt een Supabase Auth gebruiker + user record aan. Het mobiele nummer wordt het username.

Retourneert 409 als het mobiele nummer al bestaat. productId en transactionId zijn optioneel.

Controleert of een mobiel nummer al geregistreerd is. Gebruik dit voordat je Register aanroept om een duidelijke foutmelding te tonen.

GoldCube

1 endpoint

Endpoint voor de GoldCube-puzzel. In elke kamer van een venue kan een letter verborgen zijn. Als de gebruiker alle vragen in een kamer correct beantwoordt, wordt de letter ontgrendeld. Alle letters samen vormen een woord.

Haalt alle GoldCube-letters op voor een venue. Ontgrendelde letters worden getoond, vergrendelde letters zijn leeg. De volgorde (letterSequence) bepaalt het woord.

Lege letter string = nog niet ontgrendeld. De gebruiker moet alle vragen in de bijbehorende kamer correct beantwoorden om de letter te ontgrendelen.

Foutafhandeling

De API retourneert standaard HTTP-statuscodes. Er zijn twee foutformaten: OAuth2 (voor /token) en general (voor alle andere endpoints).

Token fouten (OAuth2 formaat)

{
  "error": "invalid_client",
  "error_description": "Invalid API key."
}

Algemene fouten

{
  "error": "Invalid id"
}

Code	Betekenis	Wat te doen
`200`	Succesvol	Verwerk de response normaal
`302`	Redirect	Volg de redirect URL (alleen TranslationFile)
`400`	Ongeldige aanvraag	Controleer je parameters en request body
`401`	Ongeautoriseerd	Token verlopen of ongeldig — vraag een nieuw token aan
`404`	Niet gevonden	Het gevraagde item/venue/vraag bestaat niet
`409`	Conflict	Resource bestaat al (bijv. duplicate registratie)
`503`	Service niet beschikbaar	LEGACY_API_KEY is niet geconfigureerd op de server

Opmerkingen

Alle ID-parameters in URL-paden zijn legacy integer IDs uit het oorspronkelijke systeem, niet UUIDs. Gebruik de IDs die je krijgt van GetPointOfInterests.

JSON-responses strippen automatisch null-waarden om het legacy .NET NullValueHandling.Ignore gedrag na te bootsen. Dit betekent dat ontbrekende velden gewoon niet in de response staan, in plaats van null te zijn.
Het /token endpoint accepteert zowel application/x-www-form-urlencoded als ruwe tekst body. Beide formaten worden correct geparsed.
De API vereist dat LEGACY_API_KEY en LEGACY_JWT_SECRET geconfigureerd zijn als environment variables. Zonder deze configuratie retourneren alle legacy endpoints een 503 error.
File URLs in responses gebruiken LEGACY_FILE_BASE_URL als basis. Zorg ervoor dat deze correct is ingesteld voor je omgeving (development, staging, production).