Documentatie

Documentatie voor Community

Referentiedata beheren en beschikbaar stellen.

Installeer en beheer refrncr Community, richt datasets in en publiceer gecontroleerde versies. Vraag actuele of historische gegevens op via de REST API voor leestoegang.

Community-editiePython 3.12+SQLite of PostgreSQLREST API v1

Installatie

Installatie publieke bètaRefrncr is momenteel als pre-release beschikbaar voor pilotgebruikers en testers. De optie --pre is verplicht totdat de stabiele versie 0.1.0 verschijnt.

Voor een snelle lokale installatie gebruik je pipx. Bij het starten maakt refrncr een blijvende SQLite-database aan en voert het alle Community-migraties uit voordat het verzoeken verwerkt.

Terminal
pipx install --pre refrncr
refrncr start

Open http://127.0.0.1:8000. Voor deze eerste installatie heb je geen Docker of PostgreSQL nodig.

Gebruik in productieVoor gelijktijdig gebruik door meerdere gebruikers raden we PostgreSQL aan. Gebruik HTTPS wanneer refrncr bereikbaar is via een reverse proxy of vanaf andere computers.

De eerste beheerder aanmaken

Open bij een nieuwe installatie /setup. Vul een e-mailadres, weergavenaam en een wachtwoord van minimaal 12 tekens in. Zodra de eerste gebruiker bestaat, is deze route niet meer beschikbaar.

Alternatief via de opdrachtregel
refrncr user create-admin \
  --email [email protected] \
  --display-name "Beheerder"

Het commando vraagt apart om het wachtwoord, zodat dit niet in de opdrachtgeschiedenis terechtkomt. Volgende gebruikers maak je aan onder Settings → Users in de applicatie.

Configuratie

Opties op de opdrachtregel gaan voor omgevingsvariabelen. Omgevingsvariabelen gaan op hun beurt voor de standaardwaarden.

InstellingOptieOmgevingsvariabele
Database-URL--database-urlREFRNCR_DATABASE_URL
SQLite-bestand--database-path—
Luisteradres--hostREFRNCR_HOST
HTTP-poort--portREFRNCR_PORT
Logniveau--log-levelREFRNCR_LOG_LEVEL
Vertrouwde proxy's--trusted-proxyREFRNCR_TRUSTED_PROXIES
Pepper voor API-sleutels—REFRNCR_API_KEY_PEPPER

Zonder REFRNCR_API_KEY_PEPPER zijn API-sleutels uitgeschakeld en is de REST API niet te gebruiken. Lees bij API-sleutels hoe je de pepper aanmaakt en bewaart.

Starten met SQLite
refrncr start --database-path ./refrncr.db
Starten met PostgreSQL
# .env in de map waarin je refrncr start
REFRNCR_DATABASE_URL=postgresql+psycopg://refrncr:WACHTWOORD@localhost/refrncr
REFRNCR_API_KEY_PEPPER=...

refrncr start
Houd geheimen uit commando's en logbestandenZet wachtwoorden en de pepper in omgevingsvariabelen of in een beveiligd .env-bestand, niet als optie op de opdrachtregel. Refrncr leest .env uit de map waarin je het start en overschrijft geen variabelen die al zijn ingesteld. Zet .env niet in versiebeheer.

Datasets

Een dataset is een beheerde referentielijst met een vaste sleutel, actuele beschrijvende metadata, één verantwoordelijk team en een schema met een vaste veldvolgorde. Gepubliceerde gegevens zijn onveranderlijk; wijzigingen voer je door in een afzonderlijke draft.

De identiteit van een dataset

  • Sleutel: een vaste, machineleesbare identificatie voor URL's en API-paden.
  • Naam en beschrijving: actuele metadata voor de weergave.
  • Verantwoordelijk team: het team dat de dataset onderhoudt en publiceert.
  • Recordidentificatie: één of meer geschikte velden die samen ieder record uniek identificeren.

Alle actieve Community-gebruikers kunnen actuele datasets vinden en lezen. Om een dataset aan te maken moet je lid zijn van het verantwoordelijke team. Beheerders kunnen elk team selecteren.

Bij het aanmaken kies je een van de drie datasettypen: referentiedataset, mappingdataset of hiërarchiedataset.

Datasettypen

Alle datasettypen gebruiken hetzelfde beheer: een verantwoordelijk team, drafts, beoordeling, publicatie met een ingangsdatum, auditgeschiedenis, export en de REST API. Het type bepaalt hoe de gegevens zijn opgebouwd en welke extra functies je krijgt.

ReferentiedatasetMappingdatasetHiërarchiedataset
Stelt voorEen lijst met waardenEen vertaling van broncodes naar doelwaardenEen boomstructuur
VoorbeeldLanden, valuta, foutcodesKostenplaats naar rapportageregelOrganisatiestructuur, regio-indeling
OpbouwVelden en recordsBroncode uit een referentiedataset plus doelveldenHoogste niveau, onderdelen en optionele velden
SleutelVerplicht, één of meer veldenDe broncodeOptioneel, voor het laagste niveau
WeergaveTabelTabel met bron- en doelkolommenBoom en tabel
ImporterenVolledige versie uit CSV of ExcelDoelwaarden uit CSV of ExcelBewerkte export als CSV of Excel
Extra in de API—Opzoeken op broncodeVolledige structuur

Referentiedataset

Een referentiedataset is een lijst met waarden die andere systemen gebruiken om gegevens te classificeren. Je legt de velden en datatypen vast en kiest welke velden samen ieder record uniek identificeren.

  • Gebruik voor: codetabellen en stamgegevens zoals landcodes, valuta, meeteenheden, grootboekrekeningen of tarieven.
  • Kies een ander type als: je codes uit twee systemen aan elkaar wilt koppelen (mappingdataset) of waarden wilt groeperen in niveaus (hiërarchiedataset).
  • Voorbeeld: Landen met de sleutel iso_code_3 en de velden naam en regio.
  • Functies: vrij in te richten velden, verplichte en unieke velden, zoeken in tekstwaarden, import van een volledige versie en export.
  • Zo pas je het toe: kies Reference dataset, leg de velden vast, markeer de sleutelvelden, voeg records toe of importeer ze, en publiceer.

Mappingdataset

Een mappingdataset vertaalt de codes van een bestaande referentiedataset naar waarden in een ander systeem. Elke broncode komt één keer voor en heeft één doelwaarde per doelveld. Meerdere broncodes mogen naar dezelfde doelwaarde wijzen.

  • Gebruik voor: vertaaltabellen tussen applicaties, zoals kostenplaatsen naar rapportageregels of ERP-codes naar CRM-segmenten.
  • Kies een ander type als: de lijst niet op een referentiedataset is gebaseerd (referentiedataset) of je niveaus wilt optellen (hiërarchiedataset). Veel-op-veelrelaties en transformatieregels worden niet ondersteund.
  • Voorbeeld: Kostenplaatsen naar rapportage, gebaseerd op de dataset Kostenplaatsen, met de broncode 1001 en de doelwaarde AMS-SALES.
  • Functies: de mapping is gekoppeld aan een vaste gepubliceerde versie van de brondataset. Publiceert de bron een nieuwe versie, dan toont het overzicht dat de mapping kan worden bijgewerkt. Bij het bijwerken in een draft blijven bestaande koppelingen staan, verschijnen nieuwe broncodes zonder doelwaarde en worden verdwenen codes als verwijderd gemarkeerd. Met een filter vind je de codes die nog geen doelwaarde hebben.
  • Zo pas je het toe: kies Mapping dataset, selecteer de brondataset en het veld met de broncode, voeg de doelvelden toe, vul de doelwaarden in of importeer ze, en publiceer.

Wie toegang heeft tot een mapping, ziet ook de broncodes en contextvelden die uit de brondataset zijn overgenomen. Dat geeft geen toegang tot de brondataset zelf.

Hiërarchiedataset

Een hiërarchiedataset beschrijft een boomstructuur met één hoogste niveau. Elk onderdeel heeft één bovenliggend onderdeel en behoudt zijn identiteit als je het hernoemt of verplaatst. Namen zijn uniek binnen de dataset.

  • Gebruik voor: indelingen waarmee je gegevens optelt, zoals een organisatiestructuur, een regio-indeling of een productgroepering.
  • Kies een ander type als: je alleen een platte lijst nodig hebt (referentiedataset). Wil je dezelfde codes op een tweede manier indelen, maak dan een tweede hiërarchiedataset.
  • Voorbeeld: Organisatiestructuur met Organisatie → Commercie → Verkoop → kostenplaats 4200.
  • Functies: een boom- en tabelweergave, velden voor alleen het laagste niveau of voor alle onderdelen, en controles op kringverwijzingen, ontbrekende bovenliggende onderdelen en dubbele namen voordat je publiceert. Een onderdeel verwijderen verwijdert ook alles daaronder.
  • Zo pas je het toe: kies Hierarchy dataset, maak het hoogste niveau en de onderdelen daaronder, voeg zo nodig velden toe, en publiceer. Een afnemer leest de volledige structuur via de API en telt de totalen op langs die structuur.

Velden en datatypen

Velden bepalen het schema, de validatie, de weergavevolgorde en de identificatie van records. Refrncr gebruikt negen datatypen met elk een vaste, canonieke vorm.

IDBetekenisCanonieke vormAls identificatie
stringTekstUnicode in NFC-vorm, zonder spaties aan begin of eindJa
integerGeheel getalDecimaal, zonder duizendtalscheidingJa
numberDecimaal getalExacte decimale waardeJa
floatDrijvendekommagetalEindige binary64-waardeNee
booleanWaar of onwaartrue of falseJa
dateDatumYYYY-MM-DDJa
timeTijdHH:mm:ss[.fraction]Ja
datetimeDatum en tijdLokale datum en tijd volgens ISO-notatieJa
timestampTijdstempelUTC-tijdstempel eindigend op ZJa
Decimale waarden en drijvendekommagetallenGebruik het type Decimal wanneer de decimale waarde exact moet blijven. Float gebruikt een binaire benadering en kan geen onderdeel van een recordidentificatie zijn.

Verplichte velden staan geen null-waarden toe. Unieke velden dwingen uniciteit af op basis van de canonieke waarde. Je kunt een datatype alleen wijzigen zolang het veld geen opgeslagen waarden anders dan null bevat. Refrncr converteert bestaande waarden niet automatisch.

Drafts en versies

Een versie is een volledige, onveranderlijke momentopname van een dataset met een ingangsdatum. Een draft is de werkkopie waarin je de volgende versie voorbereidt. Elke versie geldt vanaf haar ingangsdatum tot de volgende versie ingaat. Op elke datum geldt dus precies één versie.

  1. Maak een draft. Selecteer een gepubliceerde versie als basis.
  2. Werk de gegevens bij. Wijzig velden en records of importeer een volledige versie.
  3. Beoordeel de wijzigingen. Vergelijk de velden en records met de basisversie.
  4. Publiceer. Kies een ingangsdatum en voeg een toelichting toe. De volledige momentopname wordt in één transactie vastgelegd.

Hoe versies op elkaar volgen

Kostenplaats CC-1001 gaat op 1 maart 2026 van Sales naar Operations, en op 1 januari 2027 naar Finance. Bekeken op 1 november 2026:

VersieCC-1001Geldig vanafGeldig totStatus
1Sales1 jan 20261 mrt 2026Verlopen
2Operations1 mrt 20261 jan 2027Actueel
3Finance1 jan 2027—Gepland

Geldig tot is de ingangsdatum van de volgende versie, en die dag hoort al bij de volgende versie. Op 1 januari 2027 wordt Versie 3 actueel en Versie 2 verlopen, zonder dat iemand iets hoeft te doen.

  • Actueel (Current): de versie die vandaag geldt. Opvragingen gebruiken haar, tenzij je om een andere datum of versie vraagt.
  • Gepland (Scheduled): gepubliceerd, met een ingangsdatum in de toekomst.
  • Verlopen (Expired): gold eerder en is vervangen door een latere versie.
  • Geannuleerd (Cancelled): een geplande versie die vóór haar ingangsdatum is ingetrokken. Ze gaat nooit gelden. Zou Versie 3 hierboven geannuleerd worden, dan blijft Versie 2 gelden zonder einddatum.

Regels

  • De ingangsdatum is vandaag of later. Gepubliceerde versies veranderen nooit, dus wat er op een datum in het verleden gold, blijft altijd zo.
  • Op één ingangsdatum kan maar één versie beginnen.
  • Een dataset heeft hoogstens één geplande versie. Zolang die er is, kun je geen nieuwe versie publiceren. Dat kan pas als de geplande versie actueel is geworden of geannuleerd is.
  • Een dataset zonder actuele versie verschijnt niet in de gewone leesweergaven.

Gegevens op een datum

Vraag de versie op die op die datum gold. In de API geeft effective_date=2026-02-15 Versie 1 (Sales), en effective_date=2026-03-15 Versie 2 (Operations). Zonder datum krijg je de actuele versie. Zie Versies selecteren en pagineren.

Gegevens over een periode

Een rapport over januari tot en met juni 2026 beslaat twee versies: Versie 1 voor januari en februari, Versie 2 vanaf maart. Haal beide versies op (version=1, version=2) en koppel elk record aan de versie waarvan de periode de datum bevat. De ingangsdatums staan op de pagina Versions van de dataset.

Importeren en exporteren

In een draft kun je een volledige versie importeren uit een CSV- of Excelbestand. Je koppelt de kolommen aan de velden en controleert het voorstel: welke records worden toegevoegd, gewijzigd of verwijderd. Pas na je bevestiging wordt de draft bijgewerkt. Gepubliceerde versies kun je exporteren als Excel, CSV of JSON, bijvoorbeeld voor gebruik in kantoorapplicaties. Zie Importeren en exporteren voor de details.

Records

Een record bevat één waarde per veld en wordt teruggevonden via zijn unieke code. De vaste regels van de datatypen bepalen validatie, gelijkheid, uniciteit en sortering.

  • Records zijn alleen bewerkbaar binnen een actieve draft.
  • Verwijderde records blijven vóór publicatie zichtbaar bij het beoordelen van wijzigingen.
  • Gepubliceerde versies zijn alleen-lezen en behouden hun oorspronkelijke schema en waarden.
  • De basiszoekfunctie doorzoekt tekstwaarden met Unicode-normalisatie en zonder onderscheid tussen hoofdletters en kleine letters.

Importeren en exporteren

Je importeert een CSV- of Excelbestand (XLSX) in een draft. Kies het bestand en eventueel een werkblad, koppel de kolommen aan de velden, controleer de bronformaten en controleer het voorstel. Pas na je bevestiging wordt de import in één transactie vastgelegd.

  • Een import beschrijft de volledige gewenste versie. Records die niet in het bestand staan, worden verwijderd nadat je het aantal verwijderingen hebt bevestigd.
  • Het schema van de dataset blijft leidend. Koppel alle verplichte velden en sleutelvelden; optionele velden die je niet koppelt, behouden hun waarde.
  • Alle controles vinden plaats vóór het opslaan. Een ongeldige waarde voorkomt de import.
  • Heeft de dataset al een versie, dan kun je per draft één import uitvoeren, en alleen zolang je de draft nog niet met de hand hebt gewijzigd.
  • Bij een mappingdataset werkt een import alleen de doelwaarden bij. Een hiërarchiedataset importeer je vanuit de bewerkte export van die hiërarchie.

Exporteren

Gebruikers met exportrechten kunnen gepubliceerde versies downloaden als Excel, CSV of JSON, bijvoorbeeld om ze te gebruiken in kantoorapplicaties. Wie mag exporteren, lees je bij Teams en toegang.

Teams en toegang

Teams vertegenwoordigen datadomeinen. Iedere dataset heeft precies één verantwoordelijk team.

HandelingGebruikerGebruiker met export- of API-toewijzingVerantwoordelijk teamBeheerder
Gepubliceerde gegevens lezen in de appJaJaJaJa
Exporteren en de API gebruikenAfhankelijk van de instellingJaJaJa
Draft onderhoudenNeeNeeJaJa
Publiceren of annulerenNeeNeeJaJa
Toewijzingen beherenNeeNeeAfhankelijk van de instellingJa
Verantwoordelijk team wijzigenNeeNeeNeeJa

Exporteren en de API gebruiken is één recht. Een API-sleutel heeft altijd dezelfde exportrechten als de gebruiker die de sleutel heeft aangemaakt. Een gebruiker met een export- of API-toewijzing kan de toegewezen datasets lezen en exporteren, maar geen drafts onderhouden of publiceren.

Wie mag exporteren en de API gebruiken

Beheerders kiezen onder Settings → Dataset access één instelling voor de hele installatie:

  • Iedereen (standaard): elke actieve gebruiker mag exporteren en de API gebruiken. Toewijzingen blijven bewaard, maar hebben geen effect.
  • Verantwoordelijk team en toegewezen gebruikers, teamleden wijzen toe: beheerders, leden van het verantwoordelijke team en toegewezen gebruikers of teams mogen exporteren. Teamleden beheren de toewijzingen op het tabblad Access van de dataset.
  • Verantwoordelijk team en toegewezen gebruikers, alleen beheerders wijzen toe: dezelfde gebruikers mogen exporteren, maar alleen beheerders beheren de toewijzingen.

Wijzigingen in toewijzingen, teamlidmaatschap of deze instelling gelden vanaf het volgende API-verzoek. Inactieve en verwijderde gebruikers hebben geen rechten. Een team kan niet worden verwijderd zolang het verantwoordelijk is voor een dataset.

Auditgeschiedenis

Actieve beheerders kunnen het auditlog bekijken via Settings → Audit log. Zakelijke wijzigingen en structurele auditgebeurtenissen worden in dezelfde transactie vastgelegd. Recordwaarden, geheimen en willekeurige aangeleverde metadata worden niet opgenomen. Validatiefouten, geweigerde acties, conflicten door verouderde gegevens en teruggedraaide transacties leveren geen succesgebeurtenis op.

API-sleutels

Persoonlijke API-sleutels geven toegang tot de REST API voor het lezen van gegevens. Gebruikers maken hun sleutels aan onder Settings → API keys. Een sleutel geeft toegang tot dezelfde datasets die de eigenaar mag exporteren; een verzoek voor een andere dataset geeft 404.

Om sleutelbeheer in te schakelen stel je een vaste geheime waarde in, de pepper: 32 bytes weergegeven als 64 hexadecimale tekens. Maak de waarde één keer aan en bewaar hem in de beveiligde configuratie, zodat elke herstart dezelfde pepper gebruikt.

Terminal
export REFRNCR_API_KEY_PEPPER="$(openssl rand -hex 32)"
refrncr start

Gebruik je een .env-bestand, maak het dan aan met umask 077 zodat alleen jij het kunt lezen.

Bescherm de pepperSla deze waarde niet op in versiebeheer of logbestanden. Bij wijziging of verlies worden alle bestaande API-sleutels ongeldig.
Verzoek met authenticatie
curl -H 'Authorization: Bearer YOUR_API_KEY' \
  http://127.0.0.1:8000/api/v1/datasets

REST API-endpoints

De Community-API biedt onder /api/v1 alleen leestoegang tot gepubliceerde datasets van alle drie de typen.

MethodePadAntwoord
GET/api/v1/datasetsSamenvattingen van datasets en paginering
GET/api/v1/datasets/{dataset_key}Samenvatting van een dataset en de velden in volgorde
GET/api/v1/datasets/{dataset_key}/recordsRecords, versie en paginering
GET/api/v1/datasets/{dataset_key}/records/{identifier}Eén record en de versie
GET/api/v1/datasets/{dataset_key}/lookup?source={broncode}Mappingdataset: het record voor één broncode
GET/api/v1/datasets/{dataset_key}/hierarchyHiërarchiedataset: alle onderdelen met hun bovenliggende onderdeel

Gebruik voor het opvragen van een record de volledige identificatie die de API teruggeeft. Behandel deze als een ondoorzichtige waarde en pas URL-codering toe.

De opzoeking op broncode is bedoeld voor één waarde, niet als algemeen filter. Een broncode zonder doelwaarde geeft 200 met lege doelvelden; een onbekende broncode geeft 404. Het hierarchy-endpoint geeft de volledige structuur als platte lijst; de afnemer bouwt daaruit de boom op.

Afbakening van API v1Zoeken, getypeerde filters, sorteeropties, schrijven, imports en exports vallen buiten REST API v1. Gebruik voor exports de app.

De interactieve Swagger-documentatie is beschikbaar op /api/docs. Het gegenereerde OpenAPI 3.1-document staat op /api/openapi.json.

Versies selecteren en pagineren

Bij alle data-endpoints kun je een peildatum, een versienummer of beide meegeven.

ParameterBetekenis
effective_date=YYYY-MM-DDDe laatste niet-geannuleerde publicatie die op of vóór deze datum is ingegaan.
version=NDe opgegeven onveranderlijke versie, ook als deze gepland staat.
BeideDe opgegeven versie moet geldig zijn op de meegegeven datum.
Geen van beideDe actuele publicatie.

Voor verzamelingen gebruik je offset (standaard 0) en limit (standaard 50, maximaal 100).

Fouten en voorwaardelijke verzoeken

StatusFoutcodeBetekenis
400invalid_requestOngeldige parameters
401invalid_api_credentialsOntbrekende of ongeldige toegangsgegevens
404not_foundDe bron bestaat niet of is niet toegankelijk
405method_not_allowedNiet-ondersteunde methode
503service_unavailableOperationele storing

Succesvolle antwoorden bevatten een sterke ETag en een Last-Modified op basis van de publicatie. Gebruik bij voorkeur If-None-Match om betrouwbaar te controleren of een opgeslagen antwoord nog geldig is. Succesvolle antwoorden zijn privé en moeten opnieuw worden gevalideerd. Foutantwoorden gebruiken private, no-store.

Status en logging

  • GET /healthz geeft aan of het proces actief is.
  • GET /readyz controleert de databaseverbinding en of de migraties gereed zijn.

Elk antwoord bevat X-Request-ID. In een interactieve terminal is de loguitvoer compact. Omgeleide uitvoer bestaat uit JSON-regels die de privacy beschermen. Ondersteunde logniveaus zijn DEBUG, INFO, WARNING, ERROR en CRITICAL.

Opslag en back-ups

Standaardlocaties voor SQLite:

  • Linux: $XDG_DATA_HOME/refrncr/refrncr.db of ~/.local/share/refrncr/refrncr.db.
  • macOS: ~/Library/Application Support/refrncr/refrncr.db.
  • Windows: %LOCALAPPDATA%\refrncr\refrncr.db.
Verantwoordelijkheid van de technisch beheerderRefrncr levert geen back-updienst. Als beheerder ben je verantwoordelijk voor de planning, beschermde opslag, versleuteling, bewaartermijnen en het testen van herstel. Stop schrijvende processen en maak een herstelbare back-up voordat je een geplande upgrade uitvoert.

Word lid van de refrncr-community

Stel vragen, deel ervaringen en praat mee over de ontwikkeling van refrncr. Iedereen kan zich aanmelden. Nieuwe accounts worden door een beheerder goedgekeurd.

Aanmelden bij de community →