Partner developer kit
Bouw ondertekende financiële en CRM-integraties op de live Beyondtoday v1-API.
Begin met de openbare v1-handleiding, download het OpenAPI- of Power Platform Swagger-artifact, configureer een testwebhook, controleer HMAC-headers en speel financiële of veilig begrensde relatie-events opnieuw af zonder dubbele neveneffecten.
01
Importeer het contract
Gebruik OpenAPI 3.1 voor algemene tools of de Swagger 2.0-variant voor Power Platform custom connectors.
02
Maak een sandboxwebhook
Maak deze via Instellingen > API & koppelingen of roep POST /api/integrations/v1/webhooks aan met een hoofdsleutel met webhooks:write.
03
Controleer de HMAC-headers
Valideer x-beyondtoday-signature tegen <timestamp>.<eventId>.<idempotencyKey>.<raw body> met HMAC-SHA256.
04
Voer replay veilig uit
Sla x-beyondtoday-idempotency-key op vóór neveneffecten en speel daarna één event opnieuw af om te bewijzen dat dubbele leveringen onschadelijk zijn.
Downloaden en importeren
Contract, recepten en voorbeelden
Deze downloads volgen de artifacts uit de repository. Geheimgevoelige waarden blijven geredigeerd; partners gebruiken voor tests hun eigen sandbox-sleutels en endpoints.
Startpunt developerkit
Checklist voor partneronboarding, actuele v1-grenzen, replay- en idempotentierichtlijnen en de artifactindex.
docs/api/partner-developer-kit.md
v1-integratiehandleiding
Overzicht van endpoints, voorbeelden van eventpayloads en HMAC-verificatie, replaysemantiek en actuele beperkingen.
docs/api/integrations-v1.md
OpenAPI 3.1-contract
Canoniek machineleesbaar contract voor algemene API-tools en het genereren van partner-SDK’s.
docs/api/integrations-v1.openapi.yaml
Swagger 2.0-variant
Power Platform-compatibele conversie voor het importeren van Microsoft custom connectors.
docs/api/integrations-v1.swagger.yaml
Make-recept
Ondertekend webhookscenario met routering en idempotente verwerking van leveringen.
docs/api/recipes/make-webhook-scenario.md
n8n-recept
Webhookontvangst met handtekeningcontrole in een Code-node en idempotente routering.
docs/api/recipes/n8n-webhook-workflow.md
Power Platform-recept
Import van een custom connector met richtlijnen voor een pollingflow met een laag eventvolume.
docs/api/recipes/power-platform-custom-connector.md
Configureer een testwebhook
Gebruik voor de veiligste inrichting de beheerpagina van de klant of roep POST /api/integrations/v1/webhooks aan met een hoofdsleutel met webhooks:write. Sla plaintextApiKey en plaintextSigningSecret direct op; ze worden één keer getoond en horen in de secretmanager van de partner.
curl -X POST "$BEYONDTODAY_BASE_URL/api/integrations/v1/webhooks" \
-H "Authorization: Bearer <redacted-parent-api-key>" \
-H "Content-Type: application/json" \
-d '{"name":"Partner sandbox webhook","url":"https://hooks.partner.example/beyondtoday","eventTypes":["factuur.sent","betaling.received","relatie.updated"]}'Ondersteunde eventfamilies
Replay- en idempotentiesemantiek
- Dedupliceer op x-beyondtoday-idempotency-key bij retries en handmatige replaypogingen.
- Behoud x-beyondtoday-event-id als stabiele identiteit van het bedrijfsevent.
- Replay is beperkt tot de webhook van de bearer-sleutel en kan deduped: true retourneren.
Checklist voor partneronboarding
- Bevestig de administratie en vereiste scopes: events:read, events:replay, webhooks:read en/of webhooks:write.
- Importeer het OpenAPI- of Swagger-artifact en controleer bearer-authenticatie in de partnertool.
- Maak een sandboxwebhook met niet-productiegegevens en sla eenmalig getoonde geheimen direct veilig op.
- Activeer elke vereiste eventfamilie en vergelijk de payload met de toegestane voorbeelden.
- Weiger ongeldige handtekeningen, accepteer geldige handtekeningen en leg de idempotentiesleutel vast vóór vervolgschrijfacties.
- Speel één event opnieuw af en controleer dat een dubbele levering geen dubbele bedrijfsregels creëert.
- Documenteer de rotatie van API-sleutels voor de klantbeheerder vóór de overdracht.
Huidige v1-beperkingen
- GET /events biedt begrensde partnerpolling met cursorondersteuning, geen vrije zoekopdracht over alle bronnen.
- GET /webhooks retourneert alleen de webhook van de gebruikte sleutel, geen administratiebrede lijst.
- PATCH /webhooks werkt de webhook van de huidige sleutel bij; een andere onderliggende webhook kan niet via connectionId worden gekozen.
- Make, n8n en Power Platform zijn nu receptgestuurde integraties; native marketplace-apps staan op de roadmap.
- Live aanroepen naar Exact Online en Twinfield blijven afgeschermd in de configuratieflow voor Boekhoudintegraties.