YusralAPI en MCP
Je eigen software met je gegevens laten werken, of een AI-assistent koppelen.
De API en MCP zitten in het abonnement Professional.
Er zijn twee manieren om andere software met Yusral te laten werken:
- De API: voor je eigen software of een koppeling die een ontwikkelaar bouwt, zoals cases aanmaken vanuit je website of relaties bijwerken vanuit een boekhoudpakket.
- MCP: voor AI-assistenten zoals Claude of ChatGPT. Die kunnen dan je cases, taken en klanten lezen en bijwerken als je dat vraagt, en antwoorden voorbereiden die jij nakijkt en verstuurt.
Alles staat onder Instellingen > Integraties > API.
Een AI-assistent koppelen (MCP)
- Kopieer het MCP-adres onder Een AI-assistent koppelen. Het is
https://app.yusral.com/mcp. - Voeg het adres toe als connector in je AI-assistent.
- De assistent vraagt je in te loggen bij Yusral en toegang te geven. Het scherm zegt wat de app mag: je cases, taken, notities, relaties en contacten lezen, aanmaken en wijzigen, en een antwoord voorstellen dat jij nakijkt en zelf verstuurt. Lees het en klik op Toegang geven.
Een API-sleutel heb je daarvoor niet nodig. De koppeling staat op naam van wie ze goedkeurt en werkt met diens rechten: wat jij niet mag zien of doen, kan de assistent ook niet. Ben je lid van meer dan één organisatie, dan geldt de toegang voor al je organisaties, en vraagt de assistent eerst in welke hij moet werken.
Wat een assistent kan
| Tool | Wat het doet |
|---|---|
find_cases | Cases zoeken, met vrije tekst en filters zoals status of behandelaar |
get_case | Eén case lezen, met de recentste notities, berichten en alle taken |
find_tasks | Taken zoeken in de hele organisatie |
search_everything | Zoeken in cases, relaties, contacten en taken tegelijk, ook in de tekst van notities en berichten |
get_customer | Eén relatie lezen met haar contacten en recentste cases, of één contact met zijn relaties |
get_vocabulary | De statussen, prioriteiten, types, categorieën, bronnen en leden van je organisatie |
create_case | Een case openen |
update_case | Een case wijzigen; elke wijziging staat in de historiek op jouw naam |
add_case_note | Een interne notitie toevoegen, alleen voor collega's |
draft_reply | Een antwoord aan de klant voorbereiden, zie hieronder |
create_task | Een taak maken, bij een case of los |
update_task | Een taak wijzigen of afvinken |
save_relation | Een relatie toevoegen of wijzigen |
save_contact | Een contact toevoegen of wijzigen, en aan relaties koppelen |
list_organisations | Je organisaties tonen, alleen als je lid bent van meer dan één |
Wat een assistent niet kan: verwijderen, samenvoegen, instellingen, leden of facturatie wijzigen, of zelf e-mail versturen.
Antwoorden die de assistent voorbereidt
Vraag je de assistent om een klant te antwoorden, dan schrijft hij een concept. Er gaat niets naar de klant. Het concept wacht in de case, bij Opstellen, als Concept van je AI-assistent. Lees het, kies Gebruiken om het in de editor te zetten en pas het aan waar nodig, en verstuur het zelf. Met Verwerpen gooi je het weg. Een nieuw concept voor dezelfde case vervangt het vorige.
Toegang intrekken doe je bij Profiel > Verbonden apps, zie Outlook-agenda en verbonden apps.
Een API-sleutel maken
Een sleutel maak je als Eigenaar of Admin.
- Klik onder API-sleutels op Nieuwe sleutel.
- Geef de sleutel een Naam die zegt waarvoor ze dient, zoals Koppeling met Exact.
- Kies de Geldigheid: Na 30 dagen, Na 90 dagen (standaard), Na een jaar of Verloopt niet. Kies alleen Verloopt niet voor een koppeling die echt blijvend moet werken.
- Vink bij Rechten aan wat de sleutel mag. Geef niet meer dan nodig.
- Klik op Sleutel aanmaken en kopieer de sleutel meteen. Je ziet hem alleen nu. Kwijt? Maak een nieuwe en trek de oude in.
Deze rechten kun je aan een sleutel geven:
| Onderdeel | Rechten | In de API |
|---|---|---|
| Cases | Bekijken, Ook cases van collega's bekijken, Aanmaken, Bewerken | ticket:read, ticket:readAll, ticket:create, ticket:update |
| Taken | Bekijken, Ook taken van collega's bekijken, Aanmaken, Bewerken | task:read, task:readAll, task:create, task:update |
| Notities | Bekijken, Aanmaken | note:read, note:create |
| Relaties | Bekijken, Aanmaken, Bewerken | company:read, company:create, company:update |
| Contacten | Bekijken, Aanmaken, Bewerken | contact:read, contact:create, contact:update |
Een sleutel werkt met de rechten van wie ze maakte
Een sleutel kan nooit meer dan de collega die ze aanmaakte. Krijgt die persoon minder rechten, dan werkt de sleutel vanaf het volgende verzoek ook met minder rechten. Verlaat hij de organisatie, dan staat bij Gemaakt door Voormalig lid. Maak sleutels voor vaste koppelingen dus aan met een account dat blijft.
Je sleutels beheren
In de lijst zie je per sleutel de Sleutel, de Toegang, wie hem maakte (Gemaakt door), wanneer hij Laatst gebruikt is en de Status: Actief, Ingetrokken of Verlopen.
- Intrekken: de sleutel werkt vanaf het volgende verzoek niet meer. Dat kun je niet ongedaan maken. Hij blijft in de lijst staan, zodat je nog ziet wanneer hij laatst gebruikt is.
- Verwijderen: de sleutel verdwijnt uit de lijst, met de datum waarop hij laatst gebruikt is. Achteraf nagaan wat hij deed, kan dan niet meer.
Voor ontwikkelaars
De volledige referentie, met elk endpoint en elk veld, staat op de API-documentatie. Daar probeer je ook meteen een verzoek uit. De OpenAPI-specificatie importeer je in Postman of Insomnia, of gebruik je om een client te genereren. Beide vind je ook onder De API gebruiken, met de Basis-URL: https://app.yusral.com/api/v1.
| Endpoint | Wat het doet |
|---|---|
GET /me | De organisatie, het abonnement en de rechten die je sleutel echt heeft |
GET /vocabulary | Alle geldige statussen, prioriteiten, types, categorieën, bronnen en leden |
GET, POST /cases | Cases opvragen of aanmaken |
GET, PATCH /cases/{id} | Eén case lezen of wijzigen |
GET /cases/{id}/messages | De mails van een case |
GET, POST /cases/{id}/notes | De notities van een case lezen of er een toevoegen |
GET /cases/{id}/tasks | De taken van een case |
GET, POST /tasks | Taken opvragen of aanmaken |
GET, PATCH /tasks/{id} | Eén taak lezen of wijzigen |
GET, POST /relations | Relaties opvragen of aanmaken |
GET, PATCH /relations/{id} | Eén relatie lezen of wijzigen |
GET, POST /contacts | Contacten opvragen of aanmaken |
GET, PATCH /contacts/{id} | Eén contact lezen of wijzigen |
Een paar dingen die je vooraf wilt weten:
Authenticatie. Stuur de sleutel mee als Authorization: Bearer <sleutel> of als x-api-key: <sleutel>. Begin met GET /api/v1/me: dat toont wat je sleutel echt mag.
Een korte lijst zonder foutmelding. Een sleutel zonder ticket:readAll ziet alleen de cases die toegewezen zijn aan de collega die hem maakte. Dat geldt ook als die collega een rol heeft zonder Ook cases van collega's bekijken, zie Alleen eigen werk. Hetzelfde geldt voor taken met task:readAll. restrictedToOwnCases in GET /api/v1/me vertelt of dat zo is.
Relaties en contacten. Een nieuwe relatie krijgt dezelfde controles als in de app: een naam en een e-maildomein komen maar één keer voor in je organisatie, en een particulier heeft geen btw-nummer of e-maildomein. Zie Relaties en contacten.
Namen in plaats van ids. Bij het schrijven mag je een status, prioriteit of type meegeven zoals een mens het ziet, zoals "status": "In afwachting". GET /api/v1/vocabulary geeft alle geldige waarden in één keer.
Pagineren. Elke lijst werkt met een cursor: stuur nextCursor terug als cursor tot die null is.
Veilig opnieuw proberen. Stuur een Idempotency-Key mee bij een POST. Probeer je opnieuw na een time-out, dan wordt niets dubbel aangemaakt.
Niet te snel. Stuur je te veel verzoeken na elkaar, dan krijg je een 429 met in Retry-After hoeveel seconden je moet wachten.
Importeren zonder meldingen. Wijs je bij een import duizenden cases of taken toe, stuur dan "notify": false mee. Anders krijgt de behandelaar voor elke case een melding en een mail.