De Reonic REST API gebruiken

De API is bedoeld voor ontwikkelaars en eigenaren van integraties die zelfgebouwde systemen, BI-tools, niche-CRM's of eigen dashboards met Reonic verbinden. Ze dekt residentiële en commerciële projecten, contacten, taken, teams, bestanden, afspraken, componenten, activiteiten, statussen, labels, opmerkingen, planning- en aanbodsjablonen, sjablonen voor controlelijsten, leadbronnen, Kanban-borden, wiki-inhoud, fotogrammetrie en tijdregistratie.

Heeft het systeem dat je wilt koppelen een eigen integratie onder Instellingen > Bedrijfsinstellingen > Integraties (HubSpot, Pipedrive, Lexoffice, Hero, Google, Around Home en andere), gebruik die dan: die is al voorbereid en wordt ondersteund. Voor no-code-automatiseringen en uitgaande gebeurtenismeldingen zie je de handleidingen voor Zapier en webhooks.

Voordat je begint

• Je hebt admin-rechten in je Reonic-Workspace nodig om API-sleutels aan te maken.
• De API is beschikbaar in elke Workspace. Verschijnt het paneel voor API-sleutels niet in je instellingen, neem dan contact op met de Reonic-support.
• Reonic laat gedurende een overgangsperiode een huidige API-versie en de vorige naast elkaar draaien. Bouw alle nieuwe integraties op de huidige versie.
• Je hebt een scripthost, BI-tool of ander systeem nodig dat HTTPS-verzoeken kan versturen.

De API-instellingenpagina vinden

1. Open Instellingen > API / Developers (ontwikkelaars). Deze staat los van de pagina met kant-en-klare integraties onder Instellingen > Bedrijfsinstellingen > Integraties.
2. Open de pagina API om sleutels aan te maken en te beheren. De pagina Webhooks ernaast bevat de uitgaande webhooks en de Zapier-hooks.
3. Heeft je Workspace nog sleutels op de vorige API-versie, dan toont de pagina API een tabblad per versie, met de huidige versie vooraf geselecteerd.

Een API-sleutel aanmaken

1. Klik op de pagina API op Nieuw aanmaken om een nieuwe API-sleutel te maken.
2. Geef de sleutel een beschrijvende naam waaruit blijkt waarvoor hij dient, zoals een alleen-lezen sleutel voor je datawarehouse of een productiesleutel voor Zapier. De naam verschijnt in het activiteitenlogboek.
3. Kies het bereik: Alleen-lezen, Lezen en schrijven of Alleen leads aanmaken. Met de laatste kun je alleen residentiële projecten, contacten en opmerkingen aanmaken; deze is bedoeld voor inkomende leadbronnen.
4. Kopieer de gegenereerde sleutel meteen naar je opslag voor geheimen. Raak je een sleutel kwijt, maak dan een nieuwe aan en verwijder de oude.

Reonic herkent je Workspace aan de sleutel zelf, dus een aparte Workspace-header is niet nodig. De API-sleutel is het geheim waarmee elk verzoek wordt geauthenticeerd. Je client-ID is de identificatie van je Workspace: enkele partnerintegraties vragen erom als apart veld, en de Reonic-support kan je de jouwe bevestigen.

Verzoeken authenticeren

Reonic gebruikt een eigen authenticatieheader in plaats van de standaardheader Authorization. De endpointreferentie noemt de exacte header.

1. Stel in je HTTP-client de Reonic-authenticatieheader in op je API-sleutel.
2. Stuur het verzoek naar het endpoint.
3. Wordt het verzoek als niet-geauthenticeerd geweigerd, controleer dan of je de Reonic-header hebt gebruikt en niet Authorization, en of je de volledige sleutel hebt gekopieerd.

Je eerste API-aanroep doen

1. Kies een leesendpoint met weinig risico, zoals de lijst met residentiële projecten of contacten. De endpointreferentie geeft je het exacte pad.
2. Stuur de aanroep met je API-sleutel in de Reonic-authenticatieheader.
3. Lees het JSON-antwoord. Lijstendpoints geven een data-array terug plus een pagineringsblok.
4. Controleer onder Instellingen > Bedrijfsinstellingen > Integraties dat de aanroep met een geslaagde status is vastgelegd.

Pagineren, filteren en wijzigingen ophalen

Lijstendpoints gebruiken paginering op paginanummer. Geef een paginanummer en paginagrootte mee en volg de links naar de volgende en vorige pagina in het antwoord om de volledige set te doorlopen. Enkele endpoints wijken af (een vaste paginagrootte bij tijdregistratie, endpoints met één antwoord zoals teams en labels, een verschuivend tijdvenster bij kalendergebeurtenissen); de endpointreferentie vermeldt elk geval.

Voor delta-ophalingen geven residentiële projecten een tijdstempel van de laatste bewerking, die je als hoogwatermerk kunt gebruiken. Bij andere endpoints bewaar je de hoogste wijzigingstijdstempel uit je vorige antwoord en haal je vanaf dat punt opnieuw op.

Omgaan met rate limits en caching

De API kent een rate limit per Workspace, met aparte limieten per gebruiker en per IP-adres. Alle sleutels van dezelfde Workspace delen één budget, dus maak meerdere sleutels aan voor duidelijke namen en controle, niet voor extra doorvoer.

1. Vraagt Reonic je om te vertragen, wacht dan even voordat je het opnieuw probeert. Exponentiële backoff (2, 4, 8, 16 seconden) is een veilig patroon.
2. Spreid bij grote ophalingen je aanroepen en voeg een korte pauze tussen pagina's in. Een bulkophaling die vroeger op volle snelheid draaide, kan nu op een limiet stuiten; spreid haar dus in plaats van hard opnieuw te proberen.
3. Herhaalde leesacties worden uit een kortlevende cache bediend. Heb je bij een specifieke aanroep de allernieuwste gegevens nodig, dan laat de endpointreferentie zien hoe je een verse leesactie aanvraagt.

Fouten afhandelen

Reonic geeft gestructureerde HTTP-fouten terug met de standaardbetekenis van 4xx en 5xx.

• Niet geauthenticeerd (401): ontbrekende of ongeldige sleutel. Controleer de header en de sleutel.
• Toegang geweigerd (403): het bereik van de sleutel dekt de bewerking niet.
• Ongeldig verzoek (400): het verzoek verwijst naar iets dat niet van jou is, of een veld is onjuist opgebouwd.
• Niet gevonden (404): het record bestaat niet of is al verwijderd.
• Verzoek om te vertragen (429): wacht even en probeer het opnieuw.
• Serverfout (5xx): behandel dit als tijdelijk en probeer het opnieuw met backoff. Blijft de fout bestaan, meld die dan met het tijdstip bij de support.

Behandel 4xx-antwoorden als definitief: pas het verzoek aan in plaats van het ongewijzigd opnieuw te sturen.

Veelvoorkomende voorbeelden

Een aanvraag aanmaken

Gebruik het create-endpoint voor residentiële projecten voor leads voor zonnepanelen, warmtepompen en laadpalen, en het create-endpoint voor commerciële projecten voor de commerciële pipeline. Het antwoord geeft de ID van het nieuwe project terug.

Om de lead op de kaart te laten verschijnen, geef je een adres mee dat Reonic opzoekt of een set coördinaten die je zelf al hebt bepaald. Geef altijd een postcode mee en controleer de teruggegeven coördinaten als exacte nauwkeurigheid belangrijk is. Stel de projectstatus bij het aanmaken in als je een specifieke startstatus wilt; anders komt de aanvraag terecht op de startstatus van je Workspace. Dit is ook het endpoint voor leads uit een systeem zonder eigen integratie, bijvoorbeeld een contactformulier op een website.

Een aanbod aanmaken vanuit een project

1. Maak het project via de API aan en neem de ID over uit het antwoord.
2. Roep het create-endpoint voor aanbiedingen aan met die project-ID en je variantdefinitie.
3. Gebruik de aanbod-ID uit het antwoord voor latere updates. Laat de aanbodstatus leeg om het aanbod als concept aan te maken.

Contacten aanmaken, ook via bulkimport

Gebruik het create-endpoint voor contacten; contacten hebben geen coördinaten nodig. Voor een bulkimport uit een CSV-bestand of een oud CRM loop je door je records en maak je per aanroep één contact aan, waarbij je de aanroepen spreidt om onder de rate limit te blijven. Bewaar voor elk record de teruggegeven ID.

Opmerkingen of bestanden toevoegen

Met speciale endpoints voeg je een opmerking toe of upload je een bestand (PDF, afbeelding) bij het project, aanbod of contact dat je kiest.

Gegevens exporteren

Vraag het relevante lijstendpoint met paginering op en sla het antwoord op: gewonnen aanbiedingen gefilterd op status, contacten, commerciële projecten, afspraken, componenten, Kanban-borden en kolommen, of leadbronnen. Laad de JSON in Excel, Google Sheets of je BI-tool.

Migreren vanaf de vorige API-versie

Tijdens de overgang draaien beide versies naast elkaar. Plan de migratie zo dat je integraties ruim op de huidige versie draaien voordat de vorige wordt uitgefaseerd; de Reonic-support kan je de uitfaseringsdatum vertellen. De groep migration (migratie) in de endpointreferentie leidt je door de stappen:

1. Maak een nieuwe sleutel aan op de huidige versie. Huidige endpoints verwachten een sleutel van de huidige versie.
2. Werk de parsers voor gepagineerde lijsten bij: elk lijstantwoord bevat een data-array plus een pagineringsblok.
3. Stap over op de endpoints voor residentiële en commerciële projecten, die de oudere endpoints voor aanvragen en aanbiedingen vervangen.
4. Neem de huidige veldnamen over, waaronder de velden voor e-mail, adres en varianten. De endpointreferentie somt ze op.
5. Neem de huidige limieten en het hierboven beschreven cachegedrag over.

De volledige API-referentie openen

De endpointreferentie is een gerenderde documentatiepagina en de gezaghebbende lijst van elk endpoint, het exacte pad, de verzoek- en antwoordvelden en de authenticatieheader. De endpoints vallen in tien gebieden:

• Personen: gebruikers, teams.
• Projecten: residentiële projecten en commerciële projecten.
• Werken aan een project: activiteiten, status, labels, opmerkingen, bestanden, Kanban-borden en kolommen.
• Agenda: afspraken, agendafeeds.
• Catalogus: componenten, fabrikanten, planningpakketten, planningssjablonen, aanbodsjablonen.
• Workspace-inrichting: leadbronnen, sjablonen voor controlelijsten, integraties.
• Wiki: wiki-inhoud.
• Diensten: serviceafspraken.
• API-hulpmiddelen: hulpendpoints.
• Handleidingen: ingebedde pagina's met de migratiehandleiding.

Goed om te weten

• Elke API-aanroep komt in het activiteitenlogboek van de integratie terecht onder Instellingen > Bedrijfsinstellingen > Integraties, met de methode, de status en het tijdstip.
• Een verwijderde sleutel werkt niet meer. Deactiveren, roteren of verwijderen haalt een sleutel uit gebruik.
• Externe agenda's lopen niet via de API. De API geeft Reonic-afspraken vrij; haal Outlook- of Google-agenda's rechtstreeks bij die diensten op.
• Test in je eigen Workspace met een duidelijk benoemde testaanvraag en ruim die daarna op.

Laatst bijgewerkt op 9 november 2026