Integraties
Prioriteit voor de doelgroep
| Fase | Koppeling | Waarom eerst/later |
|---|---|---|
| 1 | Google Workspace (Gmail, Agenda) | Veel zzp/mkb; agenda + mail = meeste dagelijkse waarde |
| 1 | Microsoft 365 (Outlook, Agenda) | Standaard bij iets grotere mkb'ers; één Graph API voor mail+agenda |
| 1 | Moneybird | Populair bij zzp/klein mkb; nette REST API + webhooks; contacten/offertes/facturen |
| 1 | HubSpot of Pipedrive | Groeiende bedrijven met salesproces; Pipedrive veel bij installateurs |
| 2 | Exact Online | Veel gebruikt door installatie/bouw; strengere limieten en tokenvernieuwing |
| 2 | AFAS | Middelgrote bedrijven; per klant connectors inrichten |
| 2 | Mollie | Aanbetalingen/betaallinks bij offertes (AI mag nooit betalen) |
| 2 | WhatsApp Business Platform | Alleen officiële Cloud API (Meta); kosten per bericht; templates nodig |
| 2 | n8n (webhooks) | Klantspecifieke uitzonderingen |
| Op aanvraag | Salesforce, Dynamics 365, Odoo, WooCommerce/Shopify | Enterprise/maatwerk, tegen meerprijs |
Integratielaag (src/lib/integrations/)
- Catalogus (
catalog.ts): naam, categorie, authenticatie, prioriteit, objecten, aandachtspunten, API-docs. - Connector-contract (
connector.ts):testConnection()ensync(); elke leverancier implementeert dit. Het dashboard praat met het contract, niet met de leverancier → geen lock-in. - Demo-connector: doet niets extern en logt dat letterlijk.
- HubSpot-connector: echt voorbeeld (alleen lezen) met een private app token.
- Retries:
withRetry()met exponentiële wachttijd; statusfout+ teller + logboek; platformbeheer kan opnieuw proberen of de klant vragen opnieuw te autoriseren. - Kluis (
vault.ts): AES-256-GCM-versleuteling van tokens; sleutel uit de omgeving. - Per klant configureren: dashboard → Integraties (aantal volgens pakket), platformbeheer ziet status van alles.
Productie-opzet per koppeling (stappenplan)
- App registreren bij de leverancier (Google Cloud Console, Entra ID, Moneybird, HubSpot developer, Exact App Center).
- OAuth-flow:
/api/oauth/<provider>/start(state + PKCE, tenant in de state) → callback → tokens versleuteld opslaan. - Webhooks ontvangen op
/api/webhooks/<provider>met handtekeningcontrole; verwerken in een wachtrij (bijv. Supabase Queues of Inngest) per tenant. - Synchronisatie: incrementeel (sinds laatste sync), idempotent (externe id's bewaren), conflictregel vastleggen.
- Monitoring: foutpercentage per koppeling, alert bij herhaalde 401/429.
Let op voorwaarden: Google-scopes voor Gmail zijn "restricted" (verificatie, mogelijk security assessment); Microsoft vraagt soms beheerderstoestemming; Exact en AFAS hebben limieten per minuut/dag; WhatsApp kent kosten per bericht en templategoedkeuring. Gebruik uitsluitend officiële API's.