KoppelingenMoneybird
Moneybird API koppelen aan je website.
Met een koppeling op de Moneybird API wordt een bestelling of aanvraag op je website direct een contact en een factuur in je boekhouding. Is de factuur betaald, dan meldt Moneybird dat terug, zodat je site en je administratie hetzelfde zeggen.
Vertrouwd door
200+ bedrijven en webshops
Wat het oplevert
Wat een koppeling met Moneybird je oplevert.
Geen overtypwerk. Klantgegevens en regels komen uit je eigen formulier of checkout, met de juiste grootboekrekening en het juiste btw-tarief erbij.
Betaald is betaald, op beide plekken. Een webhook van Moneybird zet de order of het dossier op je site op betaald zodra de factuur dat is.
Eén contact per klant. We zoeken eerst op je eigen klantnummer, dus een terugkerende klant wordt niet voor de tweede keer aangemaakt.
Technisch
De koppeling in het kort.
- Vorm van de koppeling
- De REST API v2 op moneybird.com/api/v2/ met het id van je administratie erachter, in JSON, met contacten, verkoopfacturen, externe facturen, producten en webhooks
- Authenticatie
- OAuth2 of een persoonlijke API-token, mee als Bearer-token in de Authorization-header
- Richting
- Beide kanten op
- Verversing
- Per aanroep, plus webhooks bij statuswijzigingen; binnen 150 aanvragen per 5 minuten per IP-adres
- Wij bouwen het op
- WordPress, Next.js, Maatwerk
Waar het misgaat
- De limiet geldt per IP-adres, niet per account. Moneybird staat 150 aanvragen per 5 minuten toe, en 50 per 5 minuten voor de rapportages. Daarboven volgt een 429 met een Retry-After-header die zegt wanneer je weer mag. Voor een webshop met tientallen orders per dag is dat ruim. Voor een eerste import van een jaar aan orders niet, en draait je site op een server die zijn IP-adres deelt met andere toepassingen die met Moneybird praten, dan deel je ook die ruimte. Wij zetten de aanroepen daarom in een wachtrij die netjes wacht.
- Controleer niet met een GET of het gelukt is. Moneybird cachet aanvragen en raadt letterlijk af om met een GET na te gaan of iets is aangemaakt, omdat het resultaat dan onvolledig kan zijn. De statuscode van de aanroep zelf is de controle: een 201 betekent dat de factuur er staat. Wie na het aanmaken de lijst met facturen opvraagt om te kijken, ziet soms niets en maakt hem dan nog een keer aan.
- De ID's zijn te groot voor JavaScript. Elk object in Moneybird heeft een groot getal als ID, in de voorbeelden van Moneybird achttien cijfers lang, en een getal van die lengte verliest in JavaScript zijn laatste cijfers zonder foutmelding. Moneybird adviseert de ID's als tekst te behandelen. Doe je dat niet, dan wijst je Next.js-site naar een factuur die niet bestaat, en dat merk je pas als iemand gaat zoeken.
- Een webhook kan twee keer komen, en moet je controleren. Geeft je server geen 200 terug, dan probeert Moneybird het tot 10 keer opnieuw. Elke levering heeft een eigen Idempotency-Key, zodat je dezelfde betaling niet twee keer verwerkt. En elke levering is ondertekend in de header Moneybird-Signature. Het geheim om die te controleren geeft de API maar één keer terug, bij het aanmaken van de webhook. Daarna staat het alleen nog in Moneybird zelf, achter een extra verificatie.
Moneybird koppelen
Wat je moet weten voor je begint.
Wat is Moneybird?
Moneybird is online boekhoudsoftware voor zzp en mkb. Je maakt er offertes en facturen in, koppelt je bank, schrijft uren en doet je btw-aangifte. Veel ondernemers doen hun administratie zelf in Moneybird en laten een boekhouder meekijken.
Moneybird heeft een eigen overzicht van koppelingen. Een groot deel daarvan bouwt Moneybird niet zelf: externe partijen gebruiken de open API en Moneybird vermeldt dat ook zo op de pagina's. De API zelf is beschikbaar voor elke Moneybird-gebruiker, zonder extra kosten.
Voor een website is één vraag de kern: waar ontstaat de verkoop? Is dat een formulier, een checkout of een aanmeldflow op je eigen site, dan is dat ook de plek waar de factuur hoort te beginnen. Werk je met een ander pakket, dan bouwen we hetzelfde op Exact Online, SnelStart of e-Boekhouden.nl.
Hoe de Moneybird API werkt
De Moneybird API is REST, versie 2 is de enige versie, en hij spreekt JSON of XML. Het adres bevat het id van je administratie, hetzelfde nummer dat je in de adresbalk ziet als je in Moneybird werkt. Heb je meer administraties, dan kies je per aanroep welke.
Toegang loopt via OAuth2 of via een persoonlijke API-token. Moneybird zegt er zelf bij dat zo'n token werkt als een wachtwoord en toegang geeft tot je hele account. Je kunt de rechten beperken met scopes, zoals sales_invoices, documents, bank en settings, en het helpcenter raadt een token met alleen leesrechten aan als de koppeling niets hoeft te schrijven. Wij zetten de token op de server en nooit in de browser.
Testen doe je in een sandbox-administratie. Die maak je gratis aan met een gewoon Moneybird-account, je hebt er alle functies in, en facturen krijgen een watermerk. Zo kunnen we de hele stroom doorlopen zonder dat er een echte factuur naar een klant gaat.
Factuur of externe factuur
Moneybird kent twee soorten verkoopfacturen in de API, en de keuze bepaalt wie de factuur maakt.
Bij een verkoopfactuur (sales_invoices) maakt Moneybird de factuur, met jouw opmaak en nummering, en verstuurt hem per e-mail of via Peppol. De factuur staat eerst als concept en wordt open zodra hij is verstuurd. Dit past bij een offerteaanvraag, een aanmelding of een dienst waar je achteraf factureert.
Bij een externe verkoopfactuur (external_sales_invoices) is de factuur al ergens anders gemaakt, bijvoorbeeld door je webshop bij het afrekenen, en zet je hem in Moneybird voor de boekhouding. Met een source_url erbij klik je vanuit Moneybird door naar de order.
In beide gevallen hoort er een contact bij. We slaan je eigen klantnummer op in het veld customer_id en zoeken daar eerst op, zodat een bestaande klant wordt bijgewerkt. En elke regel krijgt een ledger_account_id en een tax_rate_id. Die leggen we één keer vast in de inrichting, per productgroep of dienst, zodat de omzet op de goede rekening en met het goede btw-tarief binnenkomt.
Betaalstatus terug naar je site
Een koppeling die alleen facturen maakt, is half werk. Je site wil ook weten wanneer er betaald is, om een order vrij te geven, een account te activeren of een project te starten.
Daarvoor registreren we een webhook met de events sales_invoice_state_changed_to_paid en external_sales_invoice_state_changed_to_paid, en waar nodig payment_registered voor deelbetalingen. Moneybird roept dan een adres op je server aan. Bij het aanmelden controleert Moneybird meteen of dat adres een 200 teruggeeft. Na binnenkomst vragen we de factuur zelf nog op en zetten de order pas op betaald als de status ook echt paid is.
Betaalt je klant via Mollie op je eigen site, dan is er nog een stap. Moneybird kan uitbetalingen van Mollie zelf aan facturen koppelen. Voor betalingen buiten Moneybird werkt dat alleen als de factuur via de API is gemaakt en de betaling daarop is geregistreerd met het transactie-id van Mollie. Hoe de betaling zelf op je site komt, lees je bij Mollie koppelen.
Moneybird en WooCommerce: plugin of eigen koppeling
Wil je Moneybird koppelen aan WooCommerce, dan is er een bestaande koppeling in het overzicht van Moneybird. Die is gebouwd door Combidesk, een externe partij. Een nieuwe order wordt daarmee een factuur of verkoopboeking, de klant wordt een contact, en de betaalstatus kan worden doorgegeven. Voor een standaardwinkel is dat vaak genoeg, en dan raden we dat ook aan.
Een eigen koppeling is logisch als je verkoop niet in een standaardcheckout zit. Denk aan een offertetool, een aanmeldflow voor cursussen, een Next.js-shop, of omzet die per productgroep op een andere grootboekrekening moet. Of aan meer websites die in één administratie boeken.
Het verschil zit ook in eigenaarschap. Een eigen koppeling is code die bij jou hoort, met de keuzes die bij jouw administratie passen, in plaats van een instelscherm waar je omheen moet werken.
Moneybird koppelen met WordPress of met maatwerk
Op WordPress met WooCommerce of een formulierplugin komt er een kleine uitbreiding op de server. Die reageert op de order of de inzending, maakt het contact en de factuur, en zet de aanroepen in een wachtrij zodat de limiet nooit een order laat vallen. Het adres voor de webhooks staat op dezelfde site.
Op een maatwerksite in Next.js is het een eigen serverroute met dezelfde wachtrij, waarin de ID's van Moneybird als tekst worden bewaard. Dat is de route voor een klantportaal of abonnementsflow waarin de betaalstatus meer bepaalt dan een vinkje bij een order.
Koppelingen en maatwerk als dit vallen bij ons onder Design & Development.
Bijgewerkt op
Specialist voor koppelingen
JosDesign & Development085 83 30 533jos@klubb.nlVeelgestelde vragen
Hoe kan ik Moneybird automatisch koppelen?
Je koppelt Moneybird automatisch via een bestaande koppeling uit het overzicht van Moneybird, of via een eigen koppeling op de Moneybird API. Een bestaande koppeling werkt voor standaardpakketten zoals WooCommerce. Een eigen koppeling is nodig als je verkoop op je website in een eigen formulier, offertetool of maatwerkshop ontstaat. Dan maakt je site zelf het contact en de factuur aan.
Hoe maak ik een API-koppeling met Moneybird?
Een API-koppeling met Moneybird maak je met een API-token of OAuth2, het id van je administratie en een server die de aanroepen doet. Je maakt eerst een contact, daarna een verkoopfactuur met grootboekrekening en btw-tarief per regel, en je registreert een webhook voor de betaalstatus. Testen kan in een gratis sandbox-administratie, waarin facturen een watermerk krijgen.
Hoe kan ik een Stripe-koppeling maken met Moneybird?
Voor Stripe staat in het overzicht van Moneybird een koppeling die door Combidesk is gebouwd, een externe partij. Die stuurt transacties en betaalstatussen van Stripe naar Moneybird. Betaalt je klant via Stripe op je eigen site, dan kan een eigen koppeling de factuur aanmaken en de betaling er direct op registreren, zodat de factuur meteen op betaald staat.
Is de Moneybird API gratis?
Ja. De Moneybird API is beschikbaar voor elke Moneybird-gebruiker en Moneybird rekent er geen extra kosten voor. Wel geldt een limiet van 150 aanvragen per 5 minuten per IP-adres. Een sandbox-administratie om te testen is ook gratis. Wat een koppeling kost, zit dus in het bouwen en niet in het gebruik van de API.
Waar vind ik mijn Moneybird API-token?
Een Moneybird API-token maak je aan in je gebruikersaccount, onder Ontwikkelaars. Daar kies je ook welke rechten de token krijgt, zoals facturen, documenten of bank. Een token geeft toegang tot je hele account, dus hij hoort op de server en niet in code die in de browser draait. Voor koppelingen die alleen lezen is een token met leesrechten genoeg.
Kan ik de Moneybird API testen zonder echte facturen?
Ja, in een sandbox-administratie. Die maak je gratis aan met een gewoon Moneybird-account en hij heeft alle functies, zonder abonnement. Facturen in een sandbox krijgen een watermerk, dus er kan niets per ongeluk als echte factuur naar een klant. Wij bouwen en testen elke Moneybird-koppeling eerst daarin.
Hoeveel aanvragen mag een Moneybird-koppeling doen?
Een Moneybird-koppeling mag 150 aanvragen per 5 minuten doen, per IP-adres, en 50 per 5 minuten voor rapportages. Daarboven volgt een 429 met een Retry-After-header. Voor gewone orders en aanvragen is dat ruim. Bij een grote import of een gedeelde server zetten we de aanroepen in een wachtrij die netjes wacht.
Werkt een Moneybird-koppeling ook met WooCommerce?
Ja. Voor WooCommerce is er een bestaande koppeling van Combidesk die orders als factuur of verkoopboeking in Moneybird zet. Wil je omzet per productgroep op een eigen grootboekrekening, of heb je naast de shop ook offertes of aanmeldingen, dan bouwen we een eigen koppeling vanuit WooCommerce.
Komt de betaalstatus uit Moneybird terug op mijn website?
Ja, via webhooks. Moneybird roept een adres op je server aan zodra een factuur op betaald gaat, en wij zetten de order of het dossier op je site dan ook op betaald. Elke melding is ondertekend en heeft een eigen sleutel, zodat we kunnen controleren dat hij van Moneybird komt en hem nooit twee keer verwerken.
Kan ik Moneybird koppelen aan Mollie?
Ja. Moneybird heeft een eigen koppeling met Mollie die uitbetalingen automatisch aan de juiste facturen koppelt. Betaalt je klant via Mollie op je eigen website, dan werkt dat alleen als de factuur via de API is gemaakt en de betaling erop is geregistreerd met het transactie-id van Mollie. Dat doet een koppeling van je site.
Wat is het verschil tussen een factuur en een externe factuur in Moneybird?
Een verkoopfactuur maakt en verstuurt Moneybird zelf, met jouw opmaak en nummering. Een externe verkoopfactuur is al ergens anders gemaakt, bijvoorbeeld door je webshop, en zet je alleen in Moneybird voor de boekhouding. Voor een offerte of dienst kies je meestal het eerste, voor een webshop met eigen facturen het tweede.
Let's work together.
Je facturen in Moneybird, zonder overtypen.