Troubleshooting Guide

Solutions for common issues with the e-Boekhouden connection module.

---

Connection Issues

Connection Test Fails

Symptoms:

• "Invalid credentials" error
• "Authentication failed" message
• Connection test button shows error

Solutions:

1. Verify credentials:

   • Log into e-Boekhouden.nl
   • Go to Beheer → Instellingen → Koppelingen tab → API/SOAP
   • Copy credentials exactly (including any special characters)
   • Note: Security codes are case-sensitive

2. Check scope:

   • Ensure you're configuring the correct store view
   • Credentials may differ per store view

3. Clear encrypted values:

   • Delete Security Code 1 and 2 fields completely
   • Save config
   • Re-enter the codes fresh
   • Save and test again

4. Check API status:

   • Verify e-Boekhouden API is operational
   • Contact e-Boekhouden support if issues persist

Timeout Errors

Symptoms:

• "Connection timed out" errors
• Sync takes very long then fails

Solutions:

1. Check server connectivity:

   • Verify outbound HTTPS connections are allowed
   • Check firewall rules for e-Boekhouden API endpoints

2. Reduce batch size:

   • Process fewer invoices per cron run
   • Consider more frequent, smaller syncs

---

Sync Issues

Invoices Not Syncing

Symptoms:

• Invoices appear in grid but don't sync
• No entries in Invoice Log
• Success stays empty

Solutions:

1. Check module status:

   • Verify Module Status is "Yes"
   • Verify Connection is "Enabled"

2. Check cron:

   bin/magento cron:run
   

   • Verify Magento cron is running
   • Check cron_schedule table for accounting jobs

3. Check automation:

   • Go to Accounting → General
   • Ensure "Auto add invoices and creditmemos" is Yes

4. Check start date:

   • Invoice date must be after configured Start Date
   • Adjust Start Date if needed

5. Manual push:

   • Go to Accounting → Data → Invoices
   • Click Actions → Push to e-Boekhouden

Invoice Syncs but Shows Error

Symptoms:

• Invoice Log shows Success = No
• Error message in Message column

Common errors and solutions:

"Invalid tax code"

• Go to Accounting → Configuration → Tax Rate Mapping
• Map the missing tax rule to an e-Boekhouden code
• Tax codes are case-sensitive (use HOOG_VERK not hoog_verk)

"Customer email required"

• Order has missing or invalid billing email
• Update customer record with valid email
• Resync the invoice

"Ledger account not found"

• Click "Sync Ledger & Costs from e-Boekhouden" in settings
• Reconfigure ledger mappings
• Verify ledger exists in e-Boekhouden

"Invoice number already exists"

• Invoice was previously synced to e-Boekhouden
• Check e-Boekhouden directly for the invoice
• This is not necessarily an error

"Factuursjabloon not found"

• The configured template doesn't exist in e-Boekhouden
• Go to e-Boekhouden: Beheer → Sjablonen → Factuursjablonen
• Use the exact template name in configuration

Credit Memos Not Syncing

Symptoms:

• Credit memos stuck in queue
• Error: "Invoice not found"

Solutions:

1. Sync original invoice first:

   • Credit memos require the related invoice to be synced
   • Find and sync the original invoice
   • Then resync the credit memo

2. Check credit memo date:

   • Must be after configured Start Date

---

Tax Issues

Wrong Tax Rate in e-Boekhouden

Symptoms:

• Invoice in e-Boekhouden shows wrong VAT percentage
• Tax amounts don't match Magento

Solutions:

1. Check Tax Rate Mapping:

   • Go to Accounting → Configuration → Tax Rate Mapping
   • Find the tax rule used on the invoice
   • Verify correct e-Boekhouden code is mapped

2. Check fallback tax codes:

   • Go to e-Boekhouden.nl → Advanced Settings
   • Verify Default Tax Classes are set correctly

3. Resync after fixing:

   • After correcting mapping, invoice may need manual update in e-Boekhouden
   • Or create a corrective entry

Tax Code Not in Dropdown

Solutions:

1. Import tax codes:

   • Go to Ledger Accounts & Cost Centers
   • Click "Sync Ledger & Costs from e-Boekhouden"
   • Tax codes are imported along with ledgers

2. Check e-Boekhouden account:

   • Verify the tax code exists in your e-Boekhouden account
   • Different account types may have different codes available

---

Customer Issues

Duplicate Customers in e-Boekhouden

Symptoms:

• Same customer appears multiple times as debtor
• Each order creates new customer

Explanation: This can happen intentionally when:

• Customer changes country
• Customer changes VAT number
• Using "Address" sync logic

Solutions:

1. Check sync logic:

   • Go to Accounting → General → Advanced
   • Review Customer Sync Logic setting
   • "Customer" creates fewer duplicates than "Address"

2. Expected behavior:

   • Changes to country_id or vat_number create new debtor
   • This is intentional as these affect tax rates

Customer Not Syncing

Solutions:

1. Check automation:

   • Ensure "Auto add customers" is Yes

2. Check required fields:

   • Customer must have valid email
   • For B2B: Company name and VAT number recommended

3. Manual sync:

   • Go to Accounting → Data → Customers
   • Click Actions → Push to e-Boekhouden

---

Performance Issues

Sync Is Very Slow

Solutions:

1. Optimize cron frequency:

   • More frequent = smaller batches = faster per run
   • Less frequent = larger batches = longer per run

2. Check for errors:

   • Failed syncs retry repeatedly
   • Fix underlying errors first

3. Enable Force Recalculate only when needed:

   • This setting increases processing time
   • Only enable temporarily for migrations

Many Items in Queue

Solutions:

1. Let cron catch up:

   • Initial sync of historical data takes time
   • Consider setting Start Date to recent date

2. Run cron manually:

   bin/magento cron:run --group=accounting
   

---

Debug Mode

Enabling Debug Logging

1. Go to e-Boekhouden.nl → Debug & Logging
2. Set Debug Mode to Yes
3. Save Config
4. Reproduce the issue
5. Check logs:
   • var/log/eboekhouden/debug.log
   • var/log/eboekhouden/error.log

Self Test

1. Go to e-Boekhouden.nl → Debug & Logging
2. Click "Run Self Test"
3. Review results for configuration issues

Log File Locations

Log	Path	Contents
Debug	var/log/eboekhouden/debug.log	Detailed API calls and responses
Error	var/log/eboekhouden/error.log	All errors (always logged)

---

Common Error Messages

Error	Cause	Solution
Invalid credentials	Wrong API credentials	Re-enter credentials from e-Boekhouden
Authentication failed	Expired or invalid codes	Generate new codes in e-Boekhouden
Invalid tax code	Unmapped or wrong tax code	Check Tax Rate Mapping
Ledger not found	Missing ledger account	Sync ledgers from e-Boekhouden
Customer email required	Missing billing email	Add email to order/customer
Invoice already exists	Duplicate sync	Check e-Boekhouden, no action needed
Connection timeout	Network/server issue	Check connectivity, retry later

---

Getting Help

Before Contacting Support

1. Enable Debug Mode and reproduce the issue
2. Download debug.log and error.log
3. Note the specific invoice/customer/credit memo IDs
4. Run Self Test and capture results

Support Resources

Documentation:

• All Help Articles

Support:

• Contact Support

When contacting support, provide:

• Magento version
• Module version (from Version button)
• Error messages from logs
• Steps to reproduce
• Store view/scope where issue occurs