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.
Installatie
--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.
pipx install --pre refrncr refrncr start
Open http://127.0.0.1:8000. Voor deze eerste installatie heb je geen Docker of PostgreSQL nodig.
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.
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.
| Instelling | Optie | Omgevingsvariabele |
|---|---|---|
| Database-URL | --database-url | REFRNCR_DATABASE_URL |
| SQLite-bestand | --database-path | — |
| Luisteradres | --host | REFRNCR_HOST |
| HTTP-poort | --port | REFRNCR_PORT |
| Logniveau | --log-level | REFRNCR_LOG_LEVEL |
| Vertrouwde proxy's | --trusted-proxy | REFRNCR_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.
refrncr start --database-path ./refrncr.db
# .env in de map waarin je refrncr start
REFRNCR_DATABASE_URL=postgresql+psycopg://refrncr:WACHTWOORD@localhost/refrncr
REFRNCR_API_KEY_PEPPER=...
refrncr start.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.
| Referentiedataset | Mappingdataset | Hiërarchiedataset | |
|---|---|---|---|
| Stelt voor | Een lijst met waarden | Een vertaling van broncodes naar doelwaarden | Een boomstructuur |
| Voorbeeld | Landen, valuta, foutcodes | Kostenplaats naar rapportageregel | Organisatiestructuur, regio-indeling |
| Opbouw | Velden en records | Broncode uit een referentiedataset plus doelvelden | Hoogste niveau, onderdelen en optionele velden |
| Sleutel | Verplicht, één of meer velden | De broncode | Optioneel, voor het laagste niveau |
| Weergave | Tabel | Tabel met bron- en doelkolommen | Boom en tabel |
| Importeren | Volledige versie uit CSV of Excel | Doelwaarden uit CSV of Excel | Bewerkte export als CSV of Excel |
| Extra in de API | — | Opzoeken op broncode | Volledige 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_3en 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
1001en de doelwaardeAMS-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.
| ID | Betekenis | Canonieke vorm | Als identificatie |
|---|---|---|---|
string | Tekst | Unicode in NFC-vorm, zonder spaties aan begin of eind | Ja |
integer | Geheel getal | Decimaal, zonder duizendtalscheiding | Ja |
number | Decimaal getal | Exacte decimale waarde | Ja |
float | Drijvendekommagetal | Eindige binary64-waarde | Nee |
boolean | Waar of onwaar | true of false | Ja |
date | Datum | YYYY-MM-DD | Ja |
time | Tijd | HH:mm:ss[.fraction] | Ja |
datetime | Datum en tijd | Lokale datum en tijd volgens ISO-notatie | Ja |
timestamp | Tijdstempel | UTC-tijdstempel eindigend op Z | Ja |
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.
- Maak een draft. Selecteer een gepubliceerde versie als basis.
- Werk de gegevens bij. Wijzig velden en records of importeer een volledige versie.
- Beoordeel de wijzigingen. Vergelijk de velden en records met de basisversie.
- 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:
| Versie | CC-1001 | Geldig vanaf | Geldig tot | Status |
|---|---|---|---|---|
| 1 | Sales | 1 jan 2026 | 1 mrt 2026 | Verlopen |
| 2 | Operations | 1 mrt 2026 | 1 jan 2027 | Actueel |
| 3 | Finance | 1 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.
| Handeling | Gebruiker | Gebruiker met export- of API-toewijzing | Verantwoordelijk team | Beheerder |
|---|---|---|---|---|
| Gepubliceerde gegevens lezen in de app | Ja | Ja | Ja | Ja |
| Exporteren en de API gebruiken | Afhankelijk van de instelling | Ja | Ja | Ja |
| Draft onderhouden | Nee | Nee | Ja | Ja |
| Publiceren of annuleren | Nee | Nee | Ja | Ja |
| Toewijzingen beheren | Nee | Nee | Afhankelijk van de instelling | Ja |
| Verantwoordelijk team wijzigen | Nee | Nee | Nee | Ja |
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.
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.
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.
| Methode | Pad | Antwoord |
|---|---|---|
| GET | /api/v1/datasets | Samenvattingen 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}/records | Records, 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}/hierarchy | Hië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.
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.
| Parameter | Betekenis |
|---|---|
effective_date=YYYY-MM-DD | De laatste niet-geannuleerde publicatie die op of vóór deze datum is ingegaan. |
version=N | De opgegeven onveranderlijke versie, ook als deze gepland staat. |
| Beide | De opgegeven versie moet geldig zijn op de meegegeven datum. |
| Geen van beide | De actuele publicatie. |
Voor verzamelingen gebruik je offset (standaard 0) en limit (standaard 50, maximaal 100).
Fouten en voorwaardelijke verzoeken
| Status | Foutcode | Betekenis |
|---|---|---|
| 400 | invalid_request | Ongeldige parameters |
| 401 | invalid_api_credentials | Ontbrekende of ongeldige toegangsgegevens |
| 404 | not_found | De bron bestaat niet of is niet toegankelijk |
| 405 | method_not_allowed | Niet-ondersteunde methode |
| 503 | service_unavailable | Operationele 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 /healthzgeeft aan of het proces actief is.GET /readyzcontroleert 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.dbof~/.local/share/refrncr/refrncr.db. - macOS:
~/Library/Application Support/refrncr/refrncr.db. - Windows:
%LOCALAPPDATA%\refrncr\refrncr.db.
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.