Module Peppibar: Difference between revisions

Jump to navigation Jump to search

Module Peppibar (view source)

Revision as of 11:19, 9 April 2026

2,643 bytes added ,  6 months ago
m
Changelog
VisualWikitext
mNo edit summary
Tag: 2017 source edit
m (Changelog)
Tag: 2017 source edit
Line 4: Line 4:
     You can edit links on the English source page : Module_Peppibar -->
     You can edit links on the English source page : Module_Peppibar -->
<!-- END interlang links -->
<!-- END interlang links -->
<!-- BEGIN origin interlang links --><!-- You can edit this section but do NOT remove these comments
<!-- BEGIN origin interlang links --><!-- You can edit this section but do NOT remove these comments
     Links below will be automatically replicated on translated pages by PolyglotBot -->[[fr:Module Peppibar FR]]
     Links below will be automatically replicated on translated pages by PolyglotBot -->[[fr:Module Peppibar FR]]
Line 17: Line 18:
|webbuy=
|webbuy=
|status=stable
|status=stable
|minversion=22
|minversion=20
|maxversion=23
|maxversion=23
|note=Requires PHP extensions: curl, dom, json. Requires Dolibarr Invoice module enabled.
|note=Requires PHP extensions: curl, dom, json. Requires Dolibarr Invoice module enabled.
Line 28: Line 29:


==Sending customer invoices==
==Sending customer invoices==
 
* Automatic '''UBL 2.1''' XML generation from Dolibarr invoices and credit notes, compliant with '''Peppol BIS Billing 3.0'''
*Automatic '''UBL 2.1''' XML generation from Dolibarr invoices, compliant with '''Peppol BIS Billing 3.0'''
* Multi-level validation before sending (EN 16931, Peppol rules, UBL schema)
*Multi-level validation before sending (EN 16931, Peppol rules, UBL schema)
* Secure transmission on the PEPPOL network with status tracking (sent, delivered, failed)
*Secure transmission on the PEPPOL network with status tracking (sent, delivered, failed)
* Optional automatic sending upon invoice validation
*Optional automatic sending upon invoice validation
* Full credit note support: UBL CreditNote generation, sending, receiving and validation
*Native PEPPOL tab on each customer invoice card
* Native PEPPOL tab on each customer invoice card
*Detailed sending reports and audit trail
* Detailed sending reports and audit trail
*Option to embed the Dolibarr PDF inside the UBL XML (BT-122/BT-125)
* Option to embed the Dolibarr PDF inside the UBL XML (BT-122/BT-125)


==Receiving supplier invoices==
==Receiving supplier invoices==
 
* Automatic polling of incoming invoices via CRON (configurable frequency)
*Automatic polling of incoming invoices via CRON (configurable frequency)
* Intelligent supplier matching by VAT number, Peppol ID, or company name
*Intelligent supplier matching by VAT number, Peppol ID, or company name
* Duplicate detection to prevent multiple imports
*Duplicate detection to prevent multiple imports
* Refresh button to re-parse stored UBL data without re-downloading from Peppyrus
*UBL vs Dolibarr comparison modal for verifying and synchronizing supplier data
* UBL vs Dolibarr comparison modal for verifying and synchronizing supplier data
*Draft import workflow for user validation before booking
* Draft import workflow for user validation before booking
*Automatic PDF and UBL XML attachment to imported invoices
* Automatic PDF and UBL XML attachment to imported invoices


==PEPPOL participant directory==
==PEPPOL participant directory==
 
* Multi-criteria search: by name, VAT number, or Peppol ID
*Multi-criteria search: by name, VAT number, or Peppol ID
* SMP (Service Metadata Publisher) lookup for verifying capabilities
*SMP (Service Metadata Publisher) lookup for verifying capabilities
* Document type capability verification per participant
*Document type capability verification per participant
* Direct integration: apply lookup results to third-party records in Dolibarr
*Direct integration: apply lookup results to third-party records in Dolibarr


==Belgian accounting exports==
==Belgian accounting exports==
 
* ZIP generation containing PDFs and UBL files for custom periods
*ZIP generation containing PDFs and UBL files for custom periods
* Full export history with traceability and re-download
*Full export history with traceability and re-download


==Dashboard and monitoring==
==Dashboard and monitoring==
 
* Real-time statistics (today / this month / this year)
*Real-time statistics (today / this month / this year)
* Color-coded visual indicators by status (pending, delivered, failed, received)
*Color-coded visual indicators by status (pending, delivered, failed, received)
* Recent activity log
*Recent activity log
* Instant API connection status check
*Instant API connection status check


==Audit and diagnostics==
==Audit and diagnostics==
 
* Complete audit log of all actions (sends, receipts, exports)
*Complete audit log of all actions (sends, receipts, exports)
* Expert/Debug mode with API connection testing, UBL validation testing, SMP search testing, detailed log viewer with filtering, system information
*Expert/Debug mode with API connection testing, UBL validation testing, SMP search testing, detailed log viewer with filtering, system information


==Supported standards==
==Supported standards==
* '''UBL 2.1''' - Universal Business Language (Invoice and CreditNote)
* '''Peppol BIS Billing 3.0''' - PEPPOL billing profile
* '''EN 16931''' - European electronic invoicing standard
* '''PEPPOL Schemes supported''' (Benelux):
** Belgium: 9925 (VAT number), 0208 (BCE/KBO enterprise number)
** Netherlands: 0106 (KvK), 0190 (OIN)
** Luxembourg: 9915 (VAT number), 0183 (Matricule RCS)
** International: 0088 (EAN), 0193 (UBL.BE), 0199 (LEI)


*'''UBL 2.1''' - Universal Business Language
==Languages==
*'''Peppol BIS Billing 3.0''' - PEPPOL billing profile
* English (en_US)
*'''EN 16931''' - European electronic invoicing standard
* French (fr_BE)
*'''PEPPOL Schemes supported''': 9925 (Belgian VAT number), 0208 (BCE/KBO enterprise number)
* Dutch - Belgium (nl_BE)
* Dutch - Netherlands (nl_NL)


=Installation=
=Installation=
Line 81: Line 87:


==Prerequisites==
==Prerequisites==
 
* '''Dolibarr''': 20.0.x to 23.0.x (validated on 23.0.2)
*'''Dolibarr''': 22.0.x to 23.0.x
* '''PHP''': 7.4 or higher (validated on PHP 8.2.30)
*'''PHP''': 7.4 or higher (validated on PHP 8.2)
* '''PHP extensions''': <code>curl</code>, <code>dom</code>, <code>json</code>
*'''PHP extensions''': <code>curl</code>, <code>dom</code>, <code>json</code>
* '''Dependency''': Dolibarr Invoice module (<code>modFacture</code>) must be enabled
*'''Dependency''': Dolibarr Invoice module (<code>modFacture</code>) must be enabled
* '''Peppyrus account''': Free registration at [https://peppyrus.be https://peppyrus.be]
*'''Peppyrus account''': Free registration at https://peppyrus.be


=Setup=
=Setup=
Line 92: Line 97:


==Setup of Peppyrus API==
==Setup of Peppyrus API==
1) Create a free account at https://peppyrus.be
1) Create a free account at [https://peppyrus.be https://peppyrus.be]


2) From your Peppyrus dashboard, retrieve your '''API Key'''
2) From your Peppyrus dashboard, retrieve your '''API Key'''
Line 101: Line 106:
2) Fill in the following fields:
2) Fill in the following fields:


*'''Environment''': Select <code>Test</code> (sandbox) or <code>Production</code>
* '''Environment''': Select <code>Test</code> (sandbox) or <code>Production</code>
*'''Peppyrus API Key''': Paste the API key from your Peppyrus dashboard
* '''Peppyrus API Key''': Paste the API key from your Peppyrus dashboard
*'''Your PEPPOL ID''': Your company identifier on the PEPPOL network (e.g. your Belgian VAT number)
* '''Your PEPPOL ID''': Your company identifier on the PEPPOL network (e.g. your Belgian VAT number)
*'''PEPPOL Scheme''': Select the scheme matching your PEPPOL ID:
* '''PEPPOL Scheme''': Select the scheme matching your PEPPOL ID:
**<code>9925</code> - Belgian VAT number (most common for Belgian companies)
** <code>9925</code> - Belgian VAT number (most common for Belgian companies)
**<code>0208</code> - BCE/KBO enterprise number
** <code>0208</code> - BCE/KBO enterprise number


3) Click '''Test API Connection''' to verify your configuration
3) Click '''Test API Connection''' to verify your configuration
Line 114: Line 119:
{| class="wikitable"
{| class="wikitable"
|-
|-
!Setting!!Description!!Default
! Setting !! Description !! Default
|-
|-
|Auto-send on validation||Automatically send invoices via PEPPOL when they are validated in Dolibarr||Disabled
| Auto-send on validation || Automatically send invoices via PEPPOL when they are validated in Dolibarr || Disabled
|-
|-
|Auto-poll received invoices||Enable automatic polling for incoming supplier invoices||Enabled
| Auto-poll received invoices || Enable automatic polling for incoming supplier invoices || Enabled
|-
|-
|Poll frequency||Interval in minutes between each poll for received invoices||60 minutes
| Poll frequency || Interval in minutes between each poll for received invoices || 60 minutes
|-
|-
|Embed PDF in UBL||Include the Dolibarr-generated PDF inside the UBL XML document (BT-122/BT-125)||Disabled
| Embed PDF in UBL || Include the Dolibarr-generated PDF inside the UBL XML document (BT-122/BT-125) || Disabled
|-
|-
|Debug mode||Log all API requests and responses for troubleshooting||Disabled
| Debug mode || Log all API requests and responses for troubleshooting || Disabled
|}
|}


Line 130: Line 135:
For automatic receiving and status synchronization, enable the scheduled jobs:
For automatic receiving and status synchronization, enable the scheduled jobs:


*Access '''Home > Setup > Scheduled Jobs'''
* Access '''Home > Setup > Scheduled Jobs'''
*Enable the following jobs:
* Enable the following jobs:


{| class="wikitable"
{| class="wikitable"
|-
|-
!Job!!Description!!Recommended frequency
! Job !! Description !! Recommended frequency
|-
|-
|Poll received invoices||Polls Peppyrus for new incoming supplier invoices||Every hour
| Poll received invoices || Polls Peppyrus for new incoming supplier invoices || Every hour
|-
|-
|Sync received invoice statuses||Synchronizes draft/validated state with Dolibarr||Every 5 minutes
| Sync received invoice statuses || Synchronizes draft/validated state with Dolibarr || Every 5 minutes
|-
|-
|Sync sent invoice statuses||Checks delivery status from Peppyrus||Every 6 hours
| Sync sent invoice statuses || Checks delivery status from Peppyrus || Every 6 hours
|}
|}


Line 150: Line 155:


2) In the '''Complementary attributes''' section, fill in:
2) In the '''Complementary attributes''' section, fill in:
 
* '''Default PEPPOL ID''': The customer's PEPPOL participant identifier
*'''Default PEPPOL ID''': The customer's PEPPOL participant identifier
* '''Default PEPPOL Scheme''': The scheme code matching their identifier
*'''Default PEPPOL Scheme''': The scheme code matching their identifier


You can also use the '''PEPPOL Participant Directory''' (accessible from the Peppibar menu) to search and automatically fill these fields.
You can also use the '''PEPPOL Participant Directory''' (accessible from the Peppibar menu) to search and automatically fill these fields.
Line 168: Line 172:


5) The status will update as the invoice progresses through the PEPPOL network:
5) The status will update as the invoice progresses through the PEPPOL network:
 
* '''Pending''' - Invoice submitted to Peppyrus
*'''Pending''' - Invoice submitted to Peppyrus
* '''Delivered''' - Invoice successfully delivered to the recipient
*'''Delivered''' - Invoice successfully delivered to the recipient
* '''Failed''' - An error occurred (details available in the audit log)
*'''Failed''' - An error occurred (details available in the audit log)


If '''Auto-send on validation''' is enabled, steps 2-4 are performed automatically when you validate the invoice.
If '''Auto-send on validation''' is enabled, steps 2-4 are performed automatically when you validate the invoice.
Line 209: Line 212:
The main '''Peppibar''' menu entry opens the dashboard, which provides:
The main '''Peppibar''' menu entry opens the dashboard, which provides:


*Real-time statistics: invoices sent/received today, this month, this year
* Real-time statistics: invoices sent/received today, this month, this year
*Color-coded status overview: pending, delivered, failed, received
* Color-coded status overview: pending, delivered, failed, received
*Recent activity log
* Recent activity log
*Quick API connection status check
* Quick API connection status check


==Using expert/debug mode==
==Using expert/debug mode==
Go to '''Peppibar > Expert''' to access diagnostic tools:
Go to '''Peppibar > Expert''' to access diagnostic tools:


*'''API Connection Test''': Verify the connection to Peppyrus
* '''API Connection Test''': Verify the connection to Peppyrus
*'''UBL Validation Test''': Test UBL generation and validation on a specific invoice
* '''UBL Validation Test''': Test UBL generation and validation on a specific invoice
*'''SMP Search Test''': Test the participant directory lookup
* '''SMP Search Test''': Test the participant directory lookup
*'''Log Viewer''': Browse and filter all audit logs
* '''Log Viewer''': Browse and filter all audit logs
*'''System Information''': View module version, PHP configuration, and Dolibarr environment details
* '''System Information''': View module version, PHP configuration, and Dolibarr environment details


=Permissions=
=Permissions=
Line 228: Line 231:
{| class="wikitable"
{| class="wikitable"
|-
|-
!Permission!!Description
! Permission !! Description
|-
|-
|Read||Read PEPPOL data, dashboard and logs
| Read || Read PEPPOL data, dashboard and logs
|-
|-
|Send||Send customer invoices via PEPPOL
| Send || Send customer invoices via PEPPOL
|-
|-
|Receive||Receive supplier invoices via PEPPOL
| Receive || Receive supplier invoices via PEPPOL
|-
|-
|Export||Export accounting data
| Export || Export accounting data
|}
|}


Line 242: Line 245:
The development of this module is managed by [https://dazax.io Dazax.io].
The development of this module is managed by [https://dazax.io Dazax.io].


*Support: peppibar@dazax.io
* Support: peppibar@dazax.io
*License: GPL-3.0+
* License: GPL-3.0+


=Changelog=
=Changelog=
==Version 1.0.6 (2026-04-09)==
* Fixed invoice preview modal: Total TTC now shows TaxInclusiveAmount instead of PayableAmount (fixes incorrect 0.00 display for prepaid invoices)
* Invoice preview now displays PrepaidAmount, Amount Due and BuyerReference (BT-10)
* CRON receive: stored total_amount now uses TaxInclusiveAmount instead of PayableAmount
* Added refresh button on received invoices to re-parse stored UBL data without re-downloading
==Version 1.0.5 (2026-03-31)==
* Full credit note support: CreditNote UBL generation, sending, receiving and validation across all classes
* Dutch language support: complete nl_BE and nl_NL translation files (450+ keys) for full Benelux coverage
* Full UI internationalization: all user-facing pages now use <code>$langs->trans()</code>
* Fixed international Peppol IDs: PartyIdentification schemeID now auto-derived from country code (fixes PEPPOL-COMMON-R043 and NL-R-003 for Dutch clients)
* CreditNote UBL amounts now positive per Peppol specification (fixes BR-27)
* CreditNote DueDate moved to PaymentMeans/PaymentDueDate (fixes UBL 2.1 XSD validation)
==Version 1.0.4 (2026-03-28)==
* Benelux support: added Peppol schemes for Netherlands (0106 KvK, 0190 OIN) and Luxembourg (9915 VAT, 0183 Matricule RCS)
==Version 1.0.3 (2026-03-13)==
* Fixed duplicate Peppol sends after API timeout: status set to <code>sending</code> before API call, with Peppyrus verification before allowing resend
* New "Check Peppol status" button when invoice is stuck in <code>sending</code> state
* Receive invoices from both Peppol schemes (0208 and 9925) by removing redundant receiver filter
==Version 1.0.2 (2026-03-12)==
* Line-level discounts now generate AllowanceCharge blocks in UBL XML (fixes PEPPOL-EN16931-R120)
* EN 16931 validator now checks item name (BT-153) instead of description (BT-154 is optional)
* HTML tags stripped from line descriptions and item names before UBL generation


==Version 1.0.1 (2026-02-20)==
==Version 1.0.1 (2026-02-20)==
 
* Added option to embed the Dolibarr invoice PDF inside the UBL XML transmitted via PEPPOL (BT-122/BT-125, per Peppol BIS Billing 3.0 section 6.8)
*Added option to embed the Dolibarr invoice PDF inside the UBL XML transmitted via PEPPOL (BT-122/BT-125, per Peppol BIS Billing 3.0 section 6.8)
* New admin configuration setting <code>PEPPIBAR_EMBED_PDF_IN_UBL</code>
*New admin configuration setting <code>PEPPIBAR_EMBED_PDF_IN_UBL</code>


==Version 1.0.0 (2026-01-31)==
==Version 1.0.0 (2026-01-31)==
 
* Initial stable release
*Initial stable release
* Full PEPPOL integration: UBL 2.1 generation and multi-level validation (EN 16931, Peppol BIS Billing 3.0, UBL schema)
*Full PEPPOL integration: UBL 2.1 generation and multi-level validation (EN 16931, Peppol BIS Billing 3.0, UBL schema)
* Send customer invoices and receive supplier invoices via PEPPOL network
*Send customer invoices and receive supplier invoices via PEPPOL network
* SMP participant directory search
*SMP participant directory search
* Belgian accounting exports (ZIP with PDFs and UBL files)
*Belgian accounting exports (ZIP with PDFs and UBL files)
* Dashboard with real-time statistics
*Dashboard with real-time statistics
* Expert/debug tools
*Expert/debug tools
* CRON jobs for automatic polling and status synchronization
*CRON jobs for automatic polling and status synchronization
* Complete audit log
*Complete audit log
* Security: encrypted API key storage, permission-based access control
*Security: encrypted API key storage, permission-based access control
* Languages: English (en_US), French (fr_BE), Dutch (nl_BE, nl_NL)
*Languages: English (en_US) and French (fr_BE)


=Troubleshooting=
=Troubleshooting=


==API connection fails==
==API connection fails==
 
* Verify your API key is correctly entered in the module configuration
*Verify your API key is correctly entered in the module configuration
* Check that your server can reach <code>https://peppyrus.be</code> (no firewall blocking outbound HTTPS)
*Check that your server can reach <code>https://peppyrus.be</code> (no firewall blocking outbound HTTPS)
* Ensure PHP <code>curl</code> extension is installed and enabled
*Ensure PHP <code>curl</code> extension is installed and enabled
* Try enabling '''Debug mode''' in the configuration to see detailed API logs
*Try enabling '''Debug mode''' in the configuration to see detailed API logs


==Invoice sending fails validation==
==Invoice sending fails validation==
 
* Check that all mandatory fields are filled on the invoice (customer VAT number, addresses, etc.)
*Check that all mandatory fields are filled on the invoice (customer VAT number, addresses, etc.)
* Verify the customer's PEPPOL ID and scheme are correctly set on their third-party card
*Verify the customer's PEPPOL ID and scheme are correctly set on their third-party card
* Review the validation errors displayed in the PEPPOL tab - they indicate which EN 16931 or Peppol rule failed
*Review the validation errors displayed in the PEPPOL tab - they indicate which EN 16931 or Peppol rule failed
* Common issues: missing VAT number, missing postal address, invalid tax category
*Common issues: missing VAT number, missing postal address, invalid tax category


==Supplier not matched during import==
==Supplier not matched during import==
 
* The module tries to match by: VAT number, then Peppol ID, then company name
*The module tries to match by: VAT number, then Peppol ID, then company name
* If no match is found, you can manually select the supplier during import
*If no match is found, you can manually select the supplier during import
* Ensure your supplier third-party records have their VAT numbers correctly filled in Dolibarr
*Ensure your supplier third-party records have their VAT numbers correctly filled in Dolibarr


==CRON jobs not running==
==CRON jobs not running==
 
* Verify the scheduled jobs are marked as '''Scheduled''' in Dolibarr admin
*Verify the scheduled jobs are marked as '''Scheduled''' in Dolibarr admin
* Check that the Dolibarr CRON system is properly configured (security key generated, system cron or webcron set up)
*Check that the Dolibarr CRON system is properly configured (security key generated, system cron or webcron set up)
* Review the CRON execution logs in '''Home > Setup > Scheduled Jobs > Logs'''
*Review the CRON execution logs in '''Home > Setup > Scheduled Jobs > Logs'''
Dazax
5

edits

Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/65843"

Navigation menu