Manager.VAT

Handleiding — BTW & KvK-controle van klanten en leveranciers via Manager.io

Inhoud

  1. Eerst: Custom Fields handmatig aanmaken (verplicht)
  2. Wat is Manager.VAT
  3. Installatie & starten
  4. Configuratie — API-sleutels
  5. KVK API-sleutel (optioneel)
  6. Meerdere bedrijven & bedrijfswisselaar
  7. Gebruik — klanten & leveranciers
  8. Detailweergave & controles
  9. BTW-controle via VIES
  10. KvK-controle
  11. Peppol ID-controle
  12. Problemen oplossen
  13. Overzicht bestanden
  14. Veiligheid
  15. Licentiecode (jaarlicentie)

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.

  1. Open customfield.html in je browser.
  2. Kies daar Nederlands of Engels (één taal voor alle 7 velden).
  3. Maak de 7 velden exact zo aan bij Customers én Suppliers (Settings → Custom Fields).
  4. 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).
  5. 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

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:

  1. Via de app: klik rechtsboven op het tandwiel-icoon ⚙, plak de sleutel en druk op Opslaan. Het bedrijf wordt automatisch herkend uit de sleutel.
  2. 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>

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.

  1. Voeg een API-sleutel per bedrijf toe via het tandwiel-icoon ⚙.
  2. Kies het bedrijf in de dropdown. De app wisselt, leegt de cache en herlaadt.
  3. 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

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:

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:

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.

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:

Zoeken zonder ingevuld Peppol ID

Is het veld Peppol ID nog leeg, dan zoekt de app automatisch in de Peppol Directory, in deze volgorde:

  1. 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.).
  2. Op KvK-nummer — voor Nederlandse bedrijven staat het KvK-nummer in het participant ID (scheme 0106 of 9944).
  3. 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.

  1. 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.
  2. 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.)
  3. 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

ProbleemOplossing
App toont "Niet verbonden"Controleer of Manager.io Desktop draait en de API op 127.0.0.1:55667 actief is.
API-sleutel wordt geweigerdMaak de sleutel opnieuw aan in Manager.io via Settings → Access Tokens. Elke sleutel hoort bij één bedrijf.
Bedrijf staat niet in de dropdownVoeg 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-veldGewenst: 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 detailpaginaControleer 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-controleDit 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 bezetStop de oude server eerst met fuser -k 4444/tcp en start daarna opnieuw.
Malformed request / foutmelding bij postenHerstart de server (zie §2). Bij aanhoudende problemen: check /tmp/manager_vat.log.

12. Overzicht bestanden

BestandDoel
server_manager_vat.pyHoofdprogramma — webserver + Manager.io/VIES/KVK/Peppol-logica
lockup-blue.pngLogo rechtsboven op de overzichts- en detailpagina en in de print
index.htmlOverzichtspagina met tabbladen en bedrijfswisselaar
detail.htmlDetailpagina met BTW/KvK/Peppol-controleknoppen
handleiding.htmlDeze handleiding
api_config.jsonInstellingen zonder geheimen (bedrijfskeuze, velden, KVK-URL). Oude sleutels erin worden 1x automatisch verhuisd naar .env (backup als .bak; daarna verwijderen).
.envAlle API-sleutels (rechten 600, nooit delen) — wordt aangemaakt bij opslaan.
api_config.example.jsonVoorbeeldconfiguratie zonder geheimen (sleutels horen in .env)
start-manager-vat.shStartscript voor de server
start-manager-vat-handmatig.bat / stop-manager-vat.batWindows: handmatig server starten/stoppen
start-manager-vat.vbs / stop-manager-vat.vbsWindows: start-/stopscripts (achtergrond)
maak-snelkoppeling-in-map.bat / .shMaakt snelkoppelingen ín de map (met pictogram); zelf naar het Bureaublad kopiëren
LEESMIJ-snelkoppeling.txtStappen voor Bureaublad-snelkoppeling (Windows + Linux)
vat.ico / vat-256.pngPictogram voor de snelkoppeling (Windows / Linux)
LEESMIJ.htmlKorte startpagina (Nederlands + Engels)

13. Veiligheid

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).

Vragen over je licentie (bijv. verlengen of een nieuwe code): support@add-ons.online.

Manager.VAT — BTW & KvK- & Peppol-controle via Manager.io API