Koppelen

Verbinden doe je één keer, daarna werkt het. Je hebt maar één ding nodig: het adres van je eigen Zakenmaat met /api/mcp erachter. Dat adres staat in de app onder Instellingen › Koppelingen: klik op de kaart van je AI op Verbinden, dan staat het in het venster met een kopieerknop ernaast, samen met de stappen voor die client.

Deze pagina gaat over wat voor alle clients hetzelfde is: de sleutels, controleren of het werkt, en wat er gebeurt als er iets bij komt.

Per AI, waar je het adres invult

De weg naar dat ene veld heet per AI anders, en dat is precies waar het misgaat. Bij Claude heet het een connector, bij ChatGPT een plug-in. Zoek je in het ene menu naar het woord van het andere, dan vind je niets.

Elke client heeft daarom zijn eigen pagina, klik voor klik, met de plek waar het bij die client meestal misgaat:

• Claude, in je browser of in Claude Code. Geen sleutel nodig.
• ChatGPT, als plug-in. Geen sleutel nodig, net als bij Claude.
• Gemini, via de app Google Antigravity. Geen sleutel nodig; Gemini in je browser kan het niet.

Een andere AI? De koppeling volgt de gewone MCP-standaard, dus in principe werkt elke client die daarmee overweg kan. Het recept is overal hetzelfde: hetzelfde adres, en dan óf de inlogweg óf een sleutel als Bearer-token. Waar je die instelling vindt staat in de handleiding van dat programma en niet hier.

Verbinden met een sleutel

Kan je client niet inloggen, dan geef je in plaats daarvan een sleutel mee. Dat geldt ook als je de REST-API rechtstreeks gebruikt.

1. Klik in het blok Je sleutels op Nieuwe sleutel en geef hem een naam waaraan je hem herkent, bijvoorbeeld “Claude op mijn laptop”.
2. Kies of hij verloopt: niet, na 30 dagen, na 90 dagen of na een jaar.
3. Klik op Aanmaken. Je krijgt hem één keer te zien; kopieer hem meteen. Je kunt er tien tegelijk actief hebben; zit je aan dat aantal, trek er dan eerst een in.
4. Geef hem in je client mee als Bearer-token bij hetzelfde adres.

Zolang de sleutel in beeld staat, staan de voorbeeldcommando’s eronder compleet ingevuld met jouw sleutel erin. Sluit je dat weg, dan zie je er weer JOUW_SLEUTEL staan en moet je hem zelf invullen.

Een sleutel begint altijd met zm_. Ziet je client hem niet als geldig, controleer dan of je hem volledig hebt geplakt.

De REST-API, voor een ander systeem

Wil je een ander pakket zelf met Zakenmaat laten praten, zoals je boekhouding of een planningssysteem, dan gebruik je de REST-API. Je stuurt dezelfde sleutel mee als Bearer-token, naar /api/v1/ in plaats van /api/mcp. Op de kaart Een andere AI, of de REST-API bij Koppelingen staat een regel waarmee je je sleutel test, en de leesroutes die je met jouw rol kunt aanroepen.

Voor de tijdlijn, de mijlpalen en Hoe staat het zijn er deze routes:

• GET /api/v1/tijdlijn: de tijdlijn van een project of klant, met project_id of klant_id. Smaller maken kan met van, tot, zoek, soorten als lijst met komma’s, en limit tot 100. Staat meer op true, vraag de volgende pagina dan op met cursor, gevuld met volgende_cursor uit het vorige antwoord.
• POST /api/v1/tijdlijn: een notitie, besluit, contactmoment of oordeel schrijven.
• PATCH /api/v1/tijdlijn/<id>: een eigen regel bijwerken, of weghalen met "weghalen": true.
• POST /api/v1/mijlpalen: een mijlpaal zetten, verzetten, hernoemen, bereiken of weghalen, op het project en de naam van de mijlpaal. Een onbekende naam geeft een fout met de namen die er wel zijn, tenzij je "maak_aan": true meestuurt. Zo maakt een systeem dat het twee keer probeert geen tweede mijlpaal.
• PATCH /api/v1/mijlpalen/<id>: hetzelfde, op het id van de mijlpaal.
• GET /api/v1/projecten/<id>/gezondheid: hoe het project ervoor staat, met dezelfde stand en signalen als de kaart Hoe staat het.

POST en PATCH krijgen een JSON-body, met dezelfde velden als de handelingen van je AI op Wat de AI kan.

Kent je pakket het id van Zakenmaat niet, geef het project dan een eigen kenmerk: het veld extern_ref bij /api/v1/projecten, bijvoorbeeld het projectnummer uit AFAS. Dat kenmerk is uniek in je werkruimte. Een mijlpaal zet je daarna met project_extern_ref in plaats van project_id.

Vraagt Zakenmaat eerst om akkoord, dan krijg je een 409 met bevestiging_nodig en, onder bevestig_met, een bevestig_token. Er is dan nog niets gedaan. In let_op staat een instructie voor een AI: eerst zijn gebruiker vragen of het mag, en pas na een duidelijke ja hetzelfde verzoek nog een keer sturen met dat token in de body. Het token geldt negentig seconden. Past een meegestuurd token niet meer, dan staat er in token_afgewezen waarom en komt er een nieuwe vraag, zie Waarom je twee keer bevestigt. Een 403 betekent dat een onderdeel of een recht van je koppeling het blokkeert, bijvoorbeeld omdat de tijdlijn uit staat in je werkruimte. Mag jij als persoon iets niet, zoals de regel van een ander weghalen, dan krijg je een 400 met de reden in fout. Een 429 betekent dat er te veel verzoeken achter elkaar kwamen, en een 503 dat het aan Zakenmaat lag: probeer het dan later opnieuw.

Geef zo’n koppeling een eigen teamlid

Een sleutel heeft geen eigen, beperkte rechten. Hij mag precies wat de persoon die hem aanmaakte mag, en alles wat ermee gebeurt staat op diens naam. Plak je je eigen sleutel in AFAS, dan kan AFAS dus alles wat jij kunt, ook bij het geld, en staat elke regel die het schrijft op jouw naam in de tijdlijn.

Werk je met de teamfunctie, nodig dan een apart teamlid uit voor de koppeling, op een mailadres dat je zelf leest. Geef het de rol Medewerker en laat Mag bij het geld uit, tenzij het pakket echt bedragen nodig heeft. Neem de uitnodiging aan en vul bij Je voornaam een naam in waaraan je de koppeling herkent, zoals AFAS. Maak daarna, ingelogd als dat lid, de sleutel. In de tijdlijn staat dan AFAS als schrijver, met het teken voor Via een API-sleutel erbij, en je trekt die ene sleutel in zonder dat je eigen koppeling stopt.

Wat de AI mag, bij Wat de AI mag, geldt voor de hele werkruimte en dus ook voor zo’n koppeling. Staat bewerken op eerst vragen, dan krijgt een mijlpaal verzetten een 409. Een pakket dat zonder mens draait kan die vraag aan niemand stellen, en het akkoord is precies bedoeld voor een mens in een gesprek. Zet de groep voor zo’n pakket dus op Mag meteen, wetend dat die schuif voor de hele werkruimte geldt en dus ook voor je AI. Drie handelingen vragen altijd, ook op Mag meteen: een concept versturen (factuur_versturen), een factuur mailen naar een adres buiten de klant (factuur_mailen), en een terugkerende factuur laten versturen (terugkerend_toevoegen of terugkerend_bijwerken). Een pakket zonder mens kan die drie dus niet zelf.

Controleren of het werkt

Vraag je AI iets onschuldigs, bijvoorbeeld hoeveel klanten je hebt of wat er vandaag op je lijst staat. Komt daar een antwoord uit dat klopt met wat je in de app ziet, dan staat de verbinding.

Kijk anders in je instellingen. Een sleutel heeft daar een kolom Laatst gebruikt; staat daar “nog nooit” terwijl je het net hebt geprobeerd, dan is je client niet binnengekomen. Verbindingen via inloggen staan in hun eigen lijstje met de datum erbij.

Werkt het niet, dan zit de fout meestal in het adres: /api/mcp moet erachter staan, in een team gevolgd door het id van je werkruimte, en het moet het adres van je eigen Zakenmaat zijn.

Als er iets nieuws bij komt

Je AI onthoudt de lijst met handelingen die hij mag doen. Die haalt hij op als je verbindt, en daarna niet meer uit zichzelf.

Dat heeft een prettige en een vervelende kant. De prettige: verbeteringen in wat een handeling doet krijg je meteen, zonder iets te doen. Wordt er een fout gerepareerd, dan geldt dat vanaf dat moment ook voor jou. De vervelende: komt er een nieuwe handeling bij, of verandert er een naam, dan ziet je AI dat pas als je opnieuw verbindt.

Onder aan de kaart API-sleutels, in het blok Je sleutels van je instellingen, zie je daarom welke versie er nu draait en wanneer die lijst voor het laatst wijzigde. Is er iets nieuws waarvoor je moet bijwerken, dan staat dat er met zoveel woorden bij. Onder Bekijk wat er is veranderd lees je per versie wat er anders is. Versies waarvoor je echt opnieuw moet verbinden dragen daar het label opnieuw verbinden; staat dat er niet bij, dan krijg je die verbetering vanzelf.

Komt er een versie waarvoor je moet bijwerken, dan zie je dat ook op je dashboard, direct onder de groet, in een melding met het kopje AI-koppeling. Zakenmaat kan niet zien of je AI zijn lijst al opnieuw heeft opgehaald, dus de melding blijft staan tot je hem wegklikt met het kruisje. Daarna komt hij pas terug bij de volgende versie waarvoor je moet bijwerken. Heb je je API-sleutel na die versie gemaakt, dan krijg je hem niet.

Hoe je bijwerkt hangt af van je AI. In claude.ai klik je bij de connector die je voor Zakenmaat hebt toegevoegd op de drie puntjes en kies je Refresh tools list; de melding op het dashboard linkt direct naar je connectors daar. Bij een andere AI gaat het hetzelfde als de eerste keer: loskoppelen en het adres er opnieuw in zetten.

Soms duurt het even voor je AI zijn lijst echt vernieuwt. Vraag hem daarom daarna of hij de nieuwe handeling kent, en noemt hij hem niet, ververs dan nog een keer. De status van de koppeling helpt je daar niet bij: dat antwoord komt van Zakenmaat zelf en noemt altijd de versie die nu draait, ook als je AI nog met de oude lijst werkt.

Je raakt niets kwijt door opnieuw te verbinden. Je gegevens staan in Zakenmaat, niet in de koppeling.

In een team

In een werkruimte met een team koppelt iedereen een eigen AI, met een eigen abonnement. Je AI werkt onder jouw naam en mag wat jij mag in je rol: een medewerker zonder toegang tot het geld krijgt ook via de AI geen factuur te zien. Krijg je een andere rol, dan geldt die bij de volgende vraag aan je AI.

Staat de teamfunctie aan, dan heeft de werkruimte een eigen adres: /api/mcp/ met het id van de werkruimte erachter. In het venster bij Verbinden staat het onder “Het adres van deze werkruimte is voor alle clients hetzelfde”. Zit je in twee werkruimtes, dan koppel je ze elk apart, met elk hun eigen adres. Een koppeling die je al had op het adres zonder id blijft werken.

Bij het inloggen staat op het toestemmingsscherm je rol en wat je AI daarmee mag. Plakte je het adres van een werkruimte waar je geen lid van bent, dan krijg je Verbinden kan niet. Kopieer dan bij Koppelingen het adres van een werkruimte waar je wel in werkt. Werk je er wel, dan ben je waarschijnlijk met een ander account ingelogd: log uit in Zakenmaat en verbind opnieuw vanuit je AI.

Wat je AI met je collega’s kan, zoals een taak aan iemand geven, staat op Wat de AI kan.

Loskoppelen

Een sleutel trek je in met de knop Intrekken in de sleutellijst. Een verbinding via inloggen verbreek je met Loskoppelen. Allebei zijn ze meteen van kracht: de gekoppelde AI kan daarna niets meer.

Doe dat sowieso als je een sleutel ergens hebt geplakt waar hij niet hoort, of als je stopt met een client. Een nieuwe maken kost tien seconden.

Wat er daarna gebeurt

Een verse koppeling mag niet meteen alles. Lezen en aanmaken staan standaard aan, maar bij bewerken, bij verwijderen, bij alles met geld en bij mailen vraagt de assistent eerst om akkoord. Dat stel je zelf in op Wat de AI mag.