Je levert je openstaande posten op drie manieren aan: via de API (per post, zodra er iets verandert), via een bestand dat POM voor je ophaalt (de complete lijst, meestal elke nacht) of via een koppeling met je boekhoudpakket. Welke manier past, hangt af van je systeem en of je een IT-team hebt. Wat de portal daarna met de posten doet, lees je in Collection Sync uitgelegd.
De drie manieren naast elkaar
| Manier | Voor wie | Wat je aanlevert | Wie bouwt |
|---|---|---|---|
| API | Organisaties met een eigen IT-team of integratiepartner | Eén post per aanroep, op het moment dat er iets verandert | Jij, met de API-documentatie |
| Bestand | Organisaties die een export uit hun systeem kunnen maken, maar geen API willen bouwen | De complete lijst met openstaande posten, als CSV- of tekstbestand op een beveiligde server | POM richt de verwerking in |
| Boekhoudkoppeling | Organisaties met een online boekhoudpakket | Niets; POM haalt de lijst dagelijks op | POM, jij logt eenmalig in |
Het belangrijkste verschil zit in wat er gebeurt met een post die niet meer in je lijst staat:
- Lever je de complete lijst aan (bestand of boekhoudkoppeling), dan weet de portal welke lopende processen ontbreken. Die komen op Betaald.
- Lever je per post aan (API), dan is er geen moment waarop de lijst compleet is. Een proces sluit je dan door het bedrag 0 door te geven. Een post die je niet meer meestuurt, blijft lopen.
Via de API
De API heeft een apart synchronisatie-endpoint: POST /v3/collection_orders/sync. Je roept het steeds opnieuw aan met de actuele stand van één klant en één betaalkenmerk. De portal maakt het proces aan als het nog niet bestaat, past de facturen aan als het bedrag is veranderd en sluit het proces als er niets meer openstaat. De volledige documentatie staat op api.pom.eu/docs.
Zo werkt het
- Vraag toegang tot de API aan bij POM. Je krijgt een client ID en client secret voor je omgeving. Test eerst in je testomgeving.
- Zorg dat de klant bestaat. Maak of werk de klant bij via
/v3/debtors. Bij een nieuw proces kopieert de portal de contactgegevens van de klant naar het proces. - Stuur per openstaande post een aanroep naar
POST /v3/collection_orders/syncmet het klantnummer, het betaalkenmerk en de facturen die nu openstaan. - Lees het antwoord. Daarin staat wat de portal heeft gedaan en welke gebeurtenissen zijn vastgelegd.
- Herhaal dit elke keer als er in je systeem iets verandert, of op een vast moment per dag.
Velden in de aanroep
| Veld | Verplicht | Betekenis |
|---|---|---|
debtor_number |
Ja | Klantnummer (3 tot 35 tekens) |
payment_reference |
Ja | Betaalkenmerk (3 tot 35 tekens). Samen met het klantnummer bepaalt dit welk proces wordt bijgewerkt. |
invoices |
Ja, voor een nieuw proces | De facturen die nu openstaan. Per factuur: number, description en amount in centen. Optioneel: type, date, due_date, description2, description3, amount2, amount3, quantity. |
concerning |
Nee | Onderwerp van het proces, bijvoorbeeld "Huur april 2025" |
flow_status |
Nee | active, pause of withdraw. Zet de status van het proces gelijk aan de status in je boekhouding. |
payment_modules |
Nee | Betaalmethodes voor het proces. Laat je dit weg, dan krijgt een nieuw proces de standaard betaalmethodes van je omgeving en houdt een bestaand proces zijn betaalmethodes. |
batch_id |
Nee | Naam van de batch, handig om een aanlevering terug te vinden |
return_url |
Nee | Pagina waar de klant na betaling naartoe gaat |
variables |
Nee | Eigen velden variable1 tot en met variable500, te gebruiken in templates en flows |
Het antwoord
| Veld | Betekenis |
|---|---|
action |
Wat er is gebeurd: created (nieuw proces), updated (bedrag of facturen aangepast), closed (op betaald gezet), unchanged (niets veranderd), status_updated (alleen de status is veranderd) of skipped (overgeslagen, bijvoorbeeld bedrag 0 zonder lopend proces) |
collection_order_id |
Het nummer van het proces, als er een is |
events |
De eventcodes van deze aanroep, in volgorde. Zie Collection Sync: gebeurtenissen en eventcodes. |
Goed om te weten bij de API
- Een nieuw proces start in de standaardflow van je omgeving. De eerste flowstap wordt één uur na de aanroep ingepland. Stuur je binnen dat uur een nieuwe stand voor dezelfde post, dan wordt die eerst verwerkt.
- Zijn er meerdere lopende processen met hetzelfde klantnummer en betaalkenmerk, dan werkt de portal het meest recente bij.
- Facturen die nog niet aan het startmoment toe zijn, of die binnen de betaalrespijt via POM zijn betaald, worden overgeslagen.
- De API heeft een limiet van 5000 punten per minuut voor je hele omgeving; een synchronisatie kost 1 punt. In de testomgeving kost elke aanroep 10 punten. Bij overschrijding krijg je status 429 met een wachttijd in de header.
- Loopt er op het proces nog een oude betalingsregeling van vóór de huidige regelingen, dan wordt de aanroep geweigerd met status 422.
- Een endpoint waarmee je processen sluit die niet meer in je complete lijst staan, is in ontwikkeling (gepland). Tot die tijd sluit je een proces via de API door bedrag 0 te sturen.
Via een bestand
Kun je een export maken van je openstaande posten, dan kan POM die voor je ophalen en verwerken. Je hoeft zelf niets te bouwen.
Zo werkt het
- Je spreekt met POM een bestandsindeling af (meestal CSV) en een beveiligde plek waar je het bestand neerzet, bijvoorbeeld een SFTP-server.
- Je zet op een vast moment, bijvoorbeeld elke nacht, de complete lijst met openstaande posten klaar. Per post minimaal: klantnummer, betaalkenmerk, factuurnummer, bedrag en datum. Verder de klantgegevens die je in berichten wilt gebruiken, zoals naam, adres, e-mailadres en telefoonnummer.
- POM haalt het bestand op, zet het om naar het formaat van de portal en verwerkt het met Collection Sync. Het verwerkte bestand wordt op de server in een archiefmap gezet.
- Na verwerking zie je een notificatie in de portal met de aantallen: nieuwe posten, weggevallen posten, gesynchroniseerde posten en overgeslagen posten. Samen is dat het totaal van je lijst, zodat je kunt controleren of alles is opgepakt.
Goed om te weten bij een bestand
- Omdat je de complete lijst aanlevert, komt een proces dat niet meer in het bestand staat op Betaald. Zorg dus dat een mislukte export niet een leeg of half bestand oplevert.
- Je kunt per post een status meegeven (actief, pauze, intrekken), als je systeem die kent.
- Het bestand bepaalt ook de variabelen van het proces; die worden bij elke verwerking ververst.
Via een koppeling met je boekhoudpakket
Werk je met een online boekhoudpakket, dan kan POM de openstaande postenlijst daar dagelijks ophalen. Je logt eenmalig in bij je pakket om toestemming te geven; daarna gaat het vanzelf. De verwerking is gelijk aan die van een bestand: de complete lijst wordt vergeleken en wat ontbreekt komt op betaald.
Ondersteunde pakketten zijn onder andere Exact Online, Twinfield, SnelStart, Yuki, Moneybird, Minox, AFAS Profit, Cash, e-Boekhouden.nl, Exact Multivers, Boekhoud Gemak, Microsoft Dynamics 365 Business Central, Reeleezee, Visma eAccounting en Xero. Vraag POM naar de actuele lijst en de mogelijkheden voor jouw pakket.
Handmatig uploaden
Wil je eenmalig of af en toe een lijst aanleveren, dan kun je die straks zelf uploaden in de portal onder Uploads. Dit onderdeel staat nog op BINNENKORT. Zie Wat komt eraan.