Manager.VAT
Handleiding — BTW & KvK-controle van klanten en leveranciers via Manager.io
Inhoud
0. Eerst: Custom Fields handmatig aanmaken (verplicht)
Dit moet eerst — vóórdat je de Setup doet. Zonder deze velden in Manager.io
heeft Manager.VAT niets om te lezen en werken alle controles (§7–§10) niet.
Belangrijk principe: onze programma's brengen nooit automatisch
wijzigingen aan in Manager.io (volledig read-only). Daarom worden deze velden
door jou, met de hand aangemaakt — zo houd je zelf controle over je
administratie en komt er nooit ongevraagd iets bij.
- Open customfield.html in je browser.
- Kies daar Nederlands of Engels (één taal voor alle 7 velden).
- Maak de 7 velden exact zo aan bij Customers én Suppliers
(Settings → Custom Fields).
- Koppel ze in de app via Setup → Velden automatisch zoeken
(vindt ze op naam; bij twee matches kies je zelf, bij geen match plak je de key).
- Ga daarna pas verder met de Setup hieronder (§3).
1. Wat is Manager.VAT
Manager.VAT is een klein lokaal webprogramma dat de gegevens van klanten en leveranciers
uit Manager.io haalt en controleert of hun BTW-nummer geldig is (via de
Europese VIES-database), of het KvK-nummer bestaat
(via de officiële KVK API) en of hun Peppol-participant
geregistreerd is (via de officiële Peppol Directory).
Alleen lezen. Manager.VAT wijzigt nooit gegevens in Manager.io — het leest
alleen via de API en toont de resultaten. De statusvinkjes (groen gecontroleerd / grijs
nog niet aangevinkt in Manager.io) zijn weergave in de app; schrijven naar Manager.io
gebeurt niet.
2. Installatie & starten
Benodigdheden
- Python 3.9 of hoger — python.org.
Op Linux is Python meestal al geïnstalleerd. Stappenplan: installatie.html.
- Manager.io Desktop met API-toegang (standaard op
http://127.0.0.1:55667).
- Een browser — Chrome, Edge of Firefox.
Server starten
cd /pad/naar/Manager.VAT
./start-manager-vat.sh
Of handmatig:
python3 server_manager_vat.py
Open vervolgens de app in je browser:
http://127.0.0.1:4444
Tip: de server draait op 127.0.0.1:4444 en is alleen vanaf deze
computer bereikbaar (niet vanaf het netwerk).
Server stoppen & herstarten
# Stoppen (port 4444 vrijmaken)
fuser -k 4444/tcp
# Herstarten
cd /pad/naar/Manager.VAT && nohup python3 server_manager_vat.py > /tmp/manager_vat.log 2>&1 &
Windows: starten en stoppen
Dubbelklik start-manager-vat-handmatig.bat om te starten en
stop-manager-vat.bat om te stoppen. Open daarna de app in je browser:
http://127.0.0.1:4444.
Snelkoppeling op het Bureaublad: draai één keer in deze map maak-snelkoppeling-in-map.bat (Windows, map C:\Manager\Manager.VAT) of bash maak-snelkoppeling-in-map.sh (Linux, map ~/Manager/Manager.VAT). Er ontstaan snelkoppelingen ín de map — kopieer die zelf naar het Bureaublad. Linux: daarna per bestand rechtsklik → “Toestaan en starten”. Details: LEESMIJ-snelkoppeling.txt.
3. Configuratie — API-sleutels
Manager.VAT heeft voor elk bedrijf een API-sleutel van Manager.io nodig.
Maak deze aan in Manager.io: Settings → Access Tokens → + en kopieer de sleutel.
Er zijn twee manieren om een sleutel in te voeren:
- Via de app: klik rechtsboven op het tandwiel-icoon ⚙,
plak de sleutel en druk op Opslaan. Het bedrijf wordt automatisch herkend uit de sleutel.
- Handmatig: zet de sleutel in het
.env-bestand (zie hieronder).
Het configuratiebestand
Instellingen staan in api_config.json; alle geheimen (API-sleutels)
staan in .env (rechten 600, alleen leesbaar door de eigenaar).
Een oude api_config.json met sleutels wordt bij het starten eenmalig automatisch
verhuisd naar .env (backup als .bak). Verwijder die .bak
daarna: er kan nog een oud token in staan. Zo ziet de configuratie eruit (zonder geheimen):
{
"active_business": "Mijn Bedrijf",
"kvk_api_url": "https://api.kvk.nl/api",
"fields": { "...": "..." }
}
# .env — 1 regel per geheim:
MANAGER_API_KEY=<standaard API-sleutel>
Mijn Bedrijf=<sleutel bedrijf 1>
Tweede Bedrijf BV=<sleutel bedrijf 2>
KVK_API_KEY=<jouw KVK API-sleutel>
active_business — het bedrijf dat actief is bij het starten.
- Bedrijfssleutels — 1 regel per bedrijf in
.env (Bedrijfsnaam=sleutel).
Alleen bedrijven met een sleutel verschijnen in de wisselaar.
4. KVK API-sleutel (optioneel)
Voor de KvK-controle is een aparte sleutel van de Kamer van Koophandel nodig.
Vraag die aan op developers.kvk.nl
en zet hem in het .env-bestand:
KVK_API_KEY=<jouw KVK API-sleutel>
Zonder sleutel werkt de rest van de app prima; de KvK-controle geeft dan een duidelijke
melding dat er geen sleutel is ingesteld.
Let op: de gratis testomgeving (adres https://api.kvk.nl/test/api)
gebruikt een voorbeeld-sleutel. Voor echte KvK-nummers moet de productie-URL
https://api.kvk.nl/api met een echte sleutel gebruikt worden.
5. Meerdere bedrijven & bedrijfswisselaar
Manager.io kan meerdere bedrijven bevatten. Manager.VAT toont in de bovenbalk een
dropdown om van bedrijf te wisselen. De dropdown verschijnt automatisch
zodra er twee of meer bedrijven een API-sleutel hebben.
- Voeg een API-sleutel per bedrijf toe via het tandwiel-icoon ⚙.
- Kies het bedrijf in de dropdown. De app wisselt, leegt de cache en herlaadt.
- De gegevens, caches en controles zijn per bedrijf gescheiden.
Tip: de actieve bedrijfskeuze wordt bewaard in api_config.json
(active_business), zodat de app bij het volgende starten hetzelfde bedrijf toont.
6. Gebruik — klanten & leveranciers
- Het startscherm heeft twee tabbladen: Leveranciers en Klanten.
- Per bedrijf zie je: bedrijfsnaam, BTW-nummer, KvK-nummer,
Peppol ID en of deze al gecontroleerd zijn.
- Met de knop Vernieuwen haal je de gegevens opnieuw op uit Manager.io.
- De statusbalkjes bovenaan tonen samenvattingen (totaal, BTW ingevuld/gecontroleerd,
KvK ingevuld/gecontroleerd, Peppol ingevuld/gecontroleerd).
- Klik op Bekijken bij een bedrijf om de details en controles te openen.
- Met de vlagknop 🇬🇧 / 🇳🇱 naast het tandwiel schakel je het hoofdscherm tussen Nederlands en Engels.
7. Detailweergave & controles
De detailpagina toont alle opgeslagen gegevens van een klant of leverancier:
rekeningnummer, BTW-nummer, KvK-nummer, Peppol ID, adres, e-mail, telefoon en de overige
aangepaste velden.
Vanuit de detailpagina kun je drie controles starten:
- Controleer BTW — controleert het BTW-nummer bij de Europese VIES-database.
- Controleer KvK — controleert of het KvK-nummer bestaat in het Handelsregister.
- Controleer Peppol — controleert of het Peppol participant ID geregistreerd is.
De resultaten verschijnen direct onder de velden, in een gekleurde box.
Met Terug ga je terug naar het tabblad (Leveranciers of Klanten) waar je vandaan kwam.
8. BTW-controle via VIES
De VIES-controle gebruikt de officiële Europese
VIES-database
van belastingnummers. De app stuurt het nummer (bijv. NL123456789B01) naar VIES en toont:
- Geldig — het nummer bestaat, inclusief de naam en het adres die VIES retourneert.
De app toont ook de naamovereenkomst met Manager.io als percentage
(≥85% komt overeen; 60–85% lijkt overeen te komen, controleer zelf; <60% namen
verschillen). Nummers zijn altijd doorslaggevend — namen uit verschillende
bronnen (VIES, Peppol Directory) verschillen vaak in spelling
(bijv. BV A & D Coating vs AandD Coating BV).
- Ongeldig — het nummer is niet gevonden.
Limiet: VIES staat maximaal 6 verzoeken per 30 seconden toe. Bij te veel
verzoeken toont de app "Te veel verzoeken"; wacht even en probeer opnieuw.
9. KvK-controle
De KvK-controle raadpleegt de officiële
KvK API (Zoeken API).
De app toont of het KvK-nummer bestaat en, indien gevonden, de geregistreerde naam en het adres.
- Gevonden — het KvK-nummer bestaat in het Handelsregister.
- Niet gevonden — geen bedrijf met dit KvK-nummer.
- Geen sleutel — er is geen KVK API-sleutel ingesteld (zie §4).
Voor testomgeving-nummers kan de KVK API een foutmelding geven zoals IPD0005;
de app vertaalt bekende meldingen naar begrijpelijke Nederlandse tekst.
10. Peppol ID-controle
De Peppol-controle raadpleegt de publieke
Peppol Directory van OpenPeppol.
De app zoekt op het volledige participant ID uit het veld Peppol ID
(bijv. iso6523-actorid-upis::0208:1234567890) en toont:
- Gevonden — de deelnemer staat in de Peppol Directory (inclusief naam en land).
Het gevonden Peppol ID (zowel de korte vorm, bijv.
0208:0652993409, als de
volledige vorm iso6523-actorid-upis::0208:0652993409) wordt getoond en kun je
met de knop Kopiëren direct overnemen, bijvoorbeeld om het in het
veld Peppol ID in Manager.io te zetten.
- Niet gevonden — de deelnemer staat niet in de directory.
Let op: publiceren naar de directory is optioneel, dus een
deelnemer kan wél actief zijn op het Peppol-netwerk maar niet in de directory staan.
Zoeken zonder ingevuld Peppol ID
Is het veld Peppol ID nog leeg, dan zoekt de app automatisch in de
Peppol Directory, in deze volgorde:
- Op BTW-nummer — het meest precies; het BTW-nummer (bijv.
0652993409)
staat doorgaans direct in het participant ID (scheme 9925) of het handelsregisternummer
(scheme 0208 bijv.).
- Op KvK-nummer — voor Nederlandse bedrijven staat het KvK-nummer in het
participant ID (scheme
0106 of 9944).
- Op bedrijfsnaam — als er geen BTW- of KvK-nummer beschikbaar is.
De gevonden deelnemer(s) worden getoond, elk met naam, land en hun kopieerbare Peppol ID.
Staat er niets in de directory, dan krijg je de melding dat er geen deelnemer gevonden is.
Peppol gecontroleerd vinkje
Net als bij BTW nummer gecontroleerd en KvK nummer gecontroleerd wordt het
vinkje Peppol gecontroleerd handmatig in Manager.io gezet — de app is
read-only en vinkt dit zelf niet aan.
- Maak in Manager.io bij de Klanten & Leveranciers een
checkbox custom field aan, genaamd bijv. Peppol gecontroleerd
of Peppol ID gecontroleerd — de app herkent beide namen.
- Zet de key van dat veld in
api_config.json onder
fields.peppol_checked. De key vind je terug in Manager.io zelf: open het
aangemaakte veld in Settings → Custom Fields en kopieer de Key uit
de URL of velddetails. (Of gebruik Setup → Velden automatisch zoeken.)
- Herstart de server. Vink daarna in Manager.io het veld aan als je de Peppol-controle
succesvol hebt uitgevoerd en klik op de detailpagina op Verversen; de app
toont het vinkje dan in het overzicht en op de detailpagina.
Neutrale status. Staat het vinkje in Manager.io nog uit, dan toont de app grijs
nog niet aangevinkt in Manager.io (geen fout) en na een geslaagde controle een
herinnering om het vinkje aan te zetten. Lege key: zolang
peppol_checked leeg is (standaard), blijft die status altijd staan. Zodra de key is
ingesteld en het vinkje in Manager.io staat, wordt groen gecontroleerd getoond.
Let op: een bedrijf kan onder meerdere scheme's in de directory
staan (bijv. 0208 voor het handelsregisternummer en 9925 voor het
BTW-nummer). Controleer dat je het juiste ID voor jouw situatie overneemt.
Limiet: de Peppol Directory staat maximaal 2 verzoeken per seconde toe.
De app beperkt het aantal verzoeken daarom ook lokaal; bij te veel verzoeken toont de app
"Te veel verzoeken".
Geen API-sleutel nodig. In tegenstelling tot de KVK-controle heeft de
Peppol-controle geen aparte sleutel nodig — hij gebruikt de publieke Directory.
11. Problemen oplossen
| Probleem | Oplossing |
| App toont "Niet verbonden" | Controleer of Manager.io Desktop draait en de API op 127.0.0.1:55667 actief is. |
| API-sleutel wordt geweigerd | Maak de sleutel opnieuw aan in Manager.io via Settings → Access Tokens. Elke sleutel hoort bij één bedrijf. |
| Bedrijf staat niet in de dropdown | Voeg de API-sleutel van dat bedrijf toe via het tandwiel-icoon ⚙ of als Bedrijfsnaam=sleutel-regel in .env. |
| BTW-controle geeft "Te veel verzoeken" | Wacht 30 seconden en probeer opnieuw (VIES-limiet is 6 verzoeken/30s). |
| KvK-controle meldt "Geen KVK API-sleutel" | Vraag een sleutel aan op developers.kvk.nl en zet KVK_API_KEY in .env. |
| Peppol-controle geeft "Te veel verzoeken" | Wacht even en probeer opnieuw (Directory-limiet is 2 verzoeken/seconde). |
| Peppol-controle vindt niets ondanks leeg ID-veld | Gewenst: bij een leeg veld zoekt de app automatisch op bedrijfsnaam. Komt er een ander resultaat, controleer dan dat de bedrijfsnaam goed in Manager.io staat. |
| Peppol ID komt niet op de detailpagina | Controleer dat het veld Peppol ID in Manager.io is ingevuld en dat peppol_field juist is in api_config.json. Ook zonder ingevuld veld kun je de Controleer Peppol-knop gebruiken; dan zoekt de app op bedrijfsnaam. |
Melding certificaat verify failed / _ssl.c:1002 / SSL: CERTIFICATE_VERIFY_FAILED bij BTW-, KvK- of Peppol-controle | Dit is een PC-specifiek probleem van Python (de CA-wortels van de server overheidssl-websites ontbreken lokaal). Los het op met: python -m pip install certifi op een opdrachtprompt en herstart daarna de server (stop-manager-vat.bat / start-manager-vat.bat of de knoppen in de app). |
| Poort 4444 is bezet | Stop de oude server eerst met fuser -k 4444/tcp en start daarna opnieuw. |
| Malformed request / foutmelding bij posten | Herstart de server (zie §2). Bij aanhoudende problemen: check /tmp/manager_vat.log. |
12. Overzicht bestanden
| Bestand | Doel |
| server_manager_vat.py | Hoofdprogramma — webserver + Manager.io/VIES/KVK/Peppol-logica |
| lockup-blue.png | Logo rechtsboven op de overzichts- en detailpagina en in de print |
| index.html | Overzichtspagina met tabbladen en bedrijfswisselaar |
| detail.html | Detailpagina met BTW/KvK/Peppol-controleknoppen |
| handleiding.html | Deze handleiding |
| api_config.json | Instellingen zonder geheimen (bedrijfskeuze, velden, KVK-URL). Oude sleutels erin worden 1x automatisch verhuisd naar .env (backup als .bak; daarna verwijderen). |
| .env | Alle API-sleutels (rechten 600, nooit delen) — wordt aangemaakt bij opslaan. |
| api_config.example.json | Voorbeeldconfiguratie zonder geheimen (sleutels horen in .env) |
| start-manager-vat.sh | Startscript voor de server |
| start-manager-vat-handmatig.bat / stop-manager-vat.bat | Windows: handmatig server starten/stoppen |
| start-manager-vat.vbs / stop-manager-vat.vbs | Windows: start-/stopscripts (achtergrond) |
| maak-snelkoppeling-in-map.bat / .sh | Maakt snelkoppelingen ín de map (met pictogram); zelf naar het Bureaublad kopiëren |
| LEESMIJ-snelkoppeling.txt | Stappen voor Bureaublad-snelkoppeling (Windows + Linux) |
| vat.ico / vat-256.png | Pictogram voor de snelkoppeling (Windows / Linux) |
| LEESMIJ.html | Korte startpagina (Nederlands + Engels) |
13. Veiligheid
- Manager.VAT bindt alleen aan
127.0.0.1:4444 en is dus alleen lokaal bereikbaar.
- API-sleutels staan alleen in
.env (rechten 600) en worden nooit in de webpagina of logs gezet.
- De app is read-only ten opzichte van Manager.io: er worden nooit gegevens gewijzigd of verwijderd.
- Ingediende waarden worden gevalideerd en veilig weergegeven (XSS-bescherming).
- Deel
.env nooit met anderen en zet het niet in een openbare git-repository.
14. Licentiecode (jaarlicentie)
Manager.VAT werkt met een persoonlijke jaarlicentie per programma
(niet overdraagbaar). Plak de code uit je bestelling in de app via het tandwiel-icoon
⚙ → Licentie-code → Opslaan.
De code wordt bij het opslaan online gecontroleerd en daarna bij elk
gebruik opnieuw (via https://add-ons.online/api/verify).
- Zonder geldige code kun je alleen kijken, niet controleren: het overzicht
en de detailpagina blijven zichtbaar, maar de knoppen
Controleer BTW / KvK / Peppol geven NO LICENCE
tot er een geldige code staat.
- Geen internet? Met dezelfde code en een geslaagde online check van
maximaal 30 dagen geleden werkt alles door (offline-venster).
Elke geslaagde online check zet de 30 dagen opnieuw op nul. Expliciet afgekeurd
(verkeerde code, verlopen, ingetrokken, ander programma) blokkeert altijd.
- Opnieuw controleren: via Setup → Opnieuw controleren
(zet ook een afwijkende licentieserver als dat nodig is).
- Zorg dat de systeemtijd van je computer klopt — bij een verkeerde datum
kan de controle mislukken.
Vragen over je licentie (bijv. verlengen of een nieuwe code): support@add-ons.online.
Manager.VAT — BTW & KvK- & Peppol-controle via Manager.io API
Manager.VAT
Manual — VAT & CoC checks of customers and suppliers via Manager.io
Contents
0. First: create Custom Fields manually (required)
This comes first — before doing the Setup. Without these fields in Manager.io,
Manager.VAT has nothing to read and none of the checks (§7–§10) work.
Important principle: our programs never change anything in Manager.io
automatically (fully read-only). That is why you create these fields
yourself, by hand — so you stay in control of your accounts.
- Open customfield.html in your browser.
- Choose Dutch or English (one language for all 7 fields).
- Create the 7 fields exactly as shown under Customers and Suppliers
(Settings → Custom Fields).
- Link them in the app via Setup → Find fields automatically
(finds them by name; with two matches you choose yourself, with no match you paste the key).
- Only then continue with the Setup below (§3).
1. What is Manager.VAT
Manager.VAT is a small local web program that fetches customer and supplier
data from Manager.io and checks whether their VAT number is valid (via the
European VIES database), whether the CoC number exists
(via the official CoC API) and whether their Peppol participant
is registered (via the official Peppol Directory).
Read-only. Manager.VAT never changes data in Manager.io — it only reads
via the API and shows the results. The status ticks (green checked / grey
not ticked yet in Manager.io)
are display in the app; nothing is written to Manager.io.
2. Installation & starting
Requirements
- Python 3.9 or higher — python.org.
On Linux Python is usually already installed. Step-by-step: installatie.html.
- Manager.io Desktop with API access (default at
http://127.0.0.1:55667).
- A browser — Chrome, Edge or Firefox.
Starting the server
cd /path/to/Manager.VAT
./start-manager-vat.sh
Or manually:
python3 server_manager_vat.py
Then open the app in your browser:
http://127.0.0.1:4444
Tip: the server binds to 127.0.0.1:4444 and is only reachable from this
computer (not from the network).
Stopping & restarting the server
# Stop (free port 4444)
fuser -k 4444/tcp
# Restart
cd /path/to/Manager.VAT && nohup python3 server_manager_vat.py > /tmp/manager_vat.log 2>&1 &
Windows: starting and stopping
Double-click start-manager-vat-handmatig.bat to start and
stop-manager-vat.bat to stop. Then open the app in your browser:
http://127.0.0.1:4444.
Desktop shortcut: run maak-snelkoppeling-in-map.bat (Windows, folder
C:\Manager\Manager.VAT) or bash maak-snelkoppeling-in-map.sh (Linux, folder
~/Manager/Manager.VAT) once in this folder. Shortcuts are created inside the folder —
copy them to the Desktop yourself. Linux: per file right-click → "Allow and launch". Details:
LEESMIJ-snelkoppeling.txt.
3. Configuration — API keys
Manager.VAT needs a Manager.io API key for each business.
Create one in Manager.io: Settings → Access Tokens → + and copy the key.
There are two ways to enter a key:
- Via the app: click the gear icon ⚙ at the top right,
paste the key and press Save. The business is recognized automatically from the key.
- Manually: put the key in the
.env file (see below).
The configuration file
Settings live in api_config.json; all secrets (API keys)
live in .env (permissions 600, readable only by the owner).
An old api_config.json containing keys is moved to .env automatically
once at startup (backup as .bak). Delete that .bak afterwards: it may
still contain an old token. The configuration looks like this (without secrets):
{
"active_business": "My Business",
"kvk_api_url": "https://api.kvk.nl/api",
"fields": { "...": "..." }
}
# .env — 1 line per secret:
MANAGER_API_KEY=<default API key>
My Business=<key business 1>
Second Business Ltd=<key business 2>
KVK_API_KEY=<your CoC API key>
active_business — the business active at startup.
- Business keys — 1 line per business in
.env (BusinessName=key).
Only businesses with a key appear in the switcher.
4. CoC API key (optional)
The CoC check needs a separate key from the Chamber of Commerce.
Request one at developers.kvk.nl
and put it in the .env file:
KVK_API_KEY=<your CoC API key>
Without a key the rest of the app works fine; the CoC check then clearly reports
that no key is set.
Note: the free test environment (address https://api.kvk.nl/test/api)
uses a sample key. For real CoC numbers use the production URL
https://api.kvk.nl/api with a real key.
5. Multiple businesses & business switcher
Manager.io can hold multiple businesses. Manager.VAT shows a
dropdown in the top bar to switch business. The dropdown appears automatically
once two or more businesses have an API key.
- Add one API key per business via the gear icon ⚙.
- Pick the business in the dropdown. The app switches, clears the cache and reloads.
- Data, caches and checks are separated per business.
Tip: the active business choice is stored in api_config.json
(active_business), so the app shows the same business next time.
6. Use — customers & suppliers
- The start screen has two tabs: Suppliers and Customers.
- Per business you see: business name, VAT number, CoC number,
Peppol ID and whether these have been checked.
- Use Refresh to fetch the data from Manager.io again.
- The summary bars at the top show totals (total, VAT filled/checked,
CoC filled/checked, Peppol filled/checked).
- Click View at a business to open the details and checks.
- With the flag button 🇬🇧 / 🇳🇱 next to the gear you switch the main screen between Dutch and English.
7. Detail view & checks
The detail page shows all stored data of a customer or supplier:
account number, VAT number, CoC number, Peppol ID, address, email, phone and the other
custom fields.
From the detail page you can start three checks:
- Check VAT — verifies the VAT number against the European VIES database.
- Check CoC — verifies that the CoC number exists in the Trade Register.
- Check Peppol — verifies that the Peppol participant ID is registered.
The results appear directly below the fields, in a coloured box.
Back returns you to the tab (Suppliers or Customers) you came from.
8. VAT check via VIES
The VIES check uses the official European
VIES
database of tax numbers. The app sends the number (e.g. NL123456789B01) to VIES and shows:
- Valid — the number exists, including the name and address VIES returns.
The app also shows the name match with Manager.io as a percentage
(≥85% matches; 60–85% seems to match, verify yourself; <60% names
differ). Numbers always decide — names from different
sources (VIES, Peppol Directory) often differ in spelling
(e.g. BV A & D Coating vs AandD Coating BV).
- Invalid — the number was not found.
Limit: VIES allows at most 6 requests per 30 seconds. With too many
requests the app shows "Too many requests"; wait a moment and try again.
9. CoC check
The CoC check queries the official
CoC API (Search API).
The app shows whether the CoC number exists and, if found, the registered name and address.
- Found — the CoC number exists in the Trade Register.
- Not found — no business with this CoC number.
- No key — no CoC API key is set (see §4).
For test-environment numbers the CoC API may return an error such as IPD0005;
the app translates known messages into understandable English text.
10. Peppol ID check
The Peppol check queries the public
Peppol Directory of OpenPeppol.
The app searches for the full participant ID from the Peppol ID field
(e.g. iso6523-actorid-upis::0208:1234567890) and shows:
- Found — the participant is in the Peppol Directory (including name and country).
The found Peppol ID (both the short form, e.g.
0208:0652993409, and the
full form iso6523-actorid-upis::0208:0652993409) is shown and can be
copied with the Copy button, for example to put it in the
Peppol ID field in Manager.io.
- Not found — the participant is not in the directory.
Note: publishing to the directory is optional, so a
participant can be active on the Peppol network without being listed.
Searching without a filled Peppol ID
If the Peppol ID field is still empty, the app searches the
Peppol Directory automatically, in this order:
- By VAT number — most precise; the VAT number (e.g.
0652993409)
is usually directly in the participant ID (scheme 9925) or the trade register number
(scheme 0208).
- By CoC number — for Dutch businesses the CoC number is in the
participant ID (scheme
0106 or 9944).
- By business name — if no VAT or CoC number is available.
Found participant(s) are shown, each with name, country and copyable Peppol ID.
If nothing is in the directory, you get a message that no participant was found.
Peppol checked tick
Just like VAT number checked and CoC number checked, the
Peppol checked tick is set manually in Manager.io — the app is
read-only and does not tick it itself.
- Create a checkbox custom field under Customers & Suppliers,
named e.g. Peppol checked or Peppol ID checked — the app recognises both.
- Put the field's key in
api_config.json under
fields.peppol_checked. Find the key in Manager.io itself: open the
created field in Settings → Custom Fields and copy the Key from
the URL or field details — or use Setup → Find fields automatically.
- Restart the server. Then tick the field in Manager.io once you have run the Peppol check
successfully and click Verversen (Refresh) on the detail page; the app will show the
tick in the overview and detail page.
Neutral status. If the tick is still off in Manager.io, the app shows grey
not ticked yet in Manager.io (not an error) and, after a successful check, a reminder to
turn the tick on. Empty key: while peppol_checked is empty
(default), that status stays. Once the key is set and the tick is on in Manager.io, green
checked is shown.
Note: a business can be listed under multiple schemes
(e.g. 0208 for the trade register number and 9925 for the
VAT number). Check that you copy the right ID for your situation.
Limit: the Peppol Directory allows at most 2 requests per second.
The app therefore limits requests locally too; with too many requests the app shows
"Too many requests".
No API key needed. Unlike the CoC check, the Peppol check needs no separate key — it uses the public Directory.
11. Troubleshooting
| Problem | Solution |
| App shows "Not connected" | Check that Manager.io Desktop runs and the API at 127.0.0.1:55667 is active. |
| API key is refused | Create the key again in Manager.io via Settings → Access Tokens. Each key belongs to one business. |
| Business is not in the dropdown | Add that business's API key via the gear icon ⚙ or as a BusinessName=key line in .env. |
| VAT check says "Too many requests" | Wait 30 seconds and try again (VIES limit is 6 requests/30s). |
| CoC check reports "No CoC API key" | Request a key at developers.kvk.nl and set KVK_API_KEY in .env. |
| Peppol check says "Too many requests" | Wait a moment and try again (Directory limit is 2 requests/second). |
| Peppol check finds nothing despite empty ID field | Expected: with an empty field the app searches automatically by business name. If you get a different result, check that the business name is correct in Manager.io. |
| Peppol ID missing on the detail page | Check that the Peppol ID field is filled in Manager.io and that peppol_field is correct in api_config.json (or use Find fields automatically). Without a filled field you can still use the Check Peppol button; the app then searches by business name. |
Message certificate verify failed / _ssl.c:1002 / SSL: CERTIFICATE_VERIFY_FAILED during VAT, CoC or Peppol checks | This is a PC-specific Python problem (the CA roots for government SSL sites are missing locally). Fix with: python -m pip install certifi in a command prompt, then restart the server (stop-manager-vat.bat / start-manager-vat.bat or the buttons in the app). |
| Port 4444 is busy | First stop the old server with fuser -k 4444/tcp and restart. |
| Malformed request / error on posting | Restart the server (see §2). If problems persist: check /tmp/manager_vat.log. |
12. File overview
| File | Purpose |
| server_manager_vat.py | Main program — web server + Manager.io/VIES/CoC/Peppol logic |
| lockup-blue.png | Logo at the top right of the overview and detail pages and in the print |
| index.html | Overview page with tabs and business switcher |
| detail.html | Detail page with VAT/CoC/Peppol check buttons |
| customfield.html | Which Custom Fields to create in Manager.io (NL/EN) |
| handleiding.html | This manual |
| api_config.json | Settings without secrets (business choice, fields, CoC URL). Old keys inside are moved once automatically to .env (backup as .bak; delete it afterwards). |
| .env | All API keys (permissions 600, never share) — created on saving. |
| api_config.example.json | Example configuration without secrets (keys belong in .env) |
| start-manager-vat.sh | Start script for the server |
| start-manager-vat-handmatig.bat / stop-manager-vat.bat | Windows: start/stop the server manually |
| start-manager-vat.vbs / stop-manager-vat.vbs | Windows: background start/stop scripts |
| maak-snelkoppeling-in-map.bat / .sh | Creates shortcuts inside the folder (with icon); copy to the Desktop yourself |
| LEESMIJ-snelkoppeling.txt | Steps for a Desktop shortcut (Windows + Linux) |
| vat.ico / vat-256.png | Icon for the shortcut (Windows / Linux) |
| LEESMIJ.html | Short start page (Dutch + English) |
13. Security
- Manager.VAT binds only to
127.0.0.1:4444 and is therefore only reachable locally.
- API keys live only in
.env (permissions 600) and are never put in the web page or logs.
- The app is read-only towards Manager.io: data is never changed or deleted.
- Submitted values are validated and displayed safely (XSS protection).
- Never share
.env with others and never put it in a public git repository.
- Licence codes live only in
.env as LICENCE_CODE and are never logged.
14. Licence code (yearly licence)
Manager.VAT works with a personal yearly licence per program
(non-transferable). Paste the code from your order into the app via the gear icon
⚙ → Licence code → Save.
The code is checked online on saving and again with each use
(via https://add-ons.online/api/verify).
- Without a valid code you can only look, not check: the overview
and detail page stay visible, but the Check VAT / CoC / Peppol buttons
return NO LICENCE until a valid code is stored.
- No internet? With the same code and a successful online check at most
30 days ago everything keeps working (offline window).
Every successful online check resets the 30 days. Explicitly rejected
(wrong code, expired, revoked, other program) always blocks.
- Recheck: via Setup → Recheck online.
- Make sure your computer's system time is correct — a wrong date
can make the check fail.
Questions about your licence (e.g. renewal or a new code): support@add-ons.online.
Manager.VAT — VAT & CoC & Peppol checks via Manager.io API