B2Brouter for WooCommerce user guide

Table of Contents

1. Introduction
2. Requirements and Installation
3. Testing the plugin in a staging environment
4. Initial Configuration
5. Invoice Generation
6. Tax Configuration
7. NIF/VAT Collection
8. Webhook Configuration
9. PDF Management
10. Customer Experience
11. Troubleshooting

---

Introduction

B2Brouter for WooCommerce is a plugin that automates the generation and sending of electronic invoices from your WooCommerce store using the B2Brouter platform.

Main Benefits

• Legal Compliance: Automatic compliance with electronic invoicing regulations in multiple countries.
• Time Saving: Automatic generation of electronic invoices without manual intervention.
• Professionalism: Invoices structured in standard formats (UBL, CII, XML, etc.)
• Cross-border: Support for international B2B and B2C transactions.
• Full Integration: Works seamlessly with WooCommerce without affecting your workflow.

---

Requirements and Installation

Prerequisites

Before installing the B2Brouter plugin, make sure you have:

• WordPress 5.8 or higher
• WooCommerce 5.0 or higher, installed and active
• PHP 7.4 or higher
• A B2Brouter account with an active eDocExchange subscription

If you don’t have WooCommerce installed yet, go to Plugins → Add New, search for “WooCommerce”, install it and activate it before continuing.

Installing the B2Brouter Plugin

Recommended option — from the official WordPress repository

1. In the WordPress admin, go to Plugins → Add New.
2. Search for “B2Brouter for WooCommerce”.
3. Click Install Now and then Activate.

Alternatives — manual download

If you prefer to install it manually, you can download the ZIP file from:

• The official WordPress repository
• The GitHub releases page

Once you have the ZIP, go to Plugins → Add New → Upload Plugin, select the file, and click Install Now and Activate.

---

Once activated, the plugin’s welcome page will appear with the initial instructions. In the sidebar menu you will see the new Invoices section.

From here you can proceed with the initial configuration.

---

Testing the plugin in a staging environment

⚠️ Important — do not use the Sandbox on your production store

The B2BRouter Sandbox generates documents marked as “Not valid” and its webhooks are completely independent from the production ones. If you configure the plugin with a sandbox key (test_…) on your real WooCommerce store:

• Your real customers’ orders would generate invoices with no legal validity.
• Status changes (invoice issued, registered, etc.) would not reach your WooCommerce, because production and sandbox webhooks do not communicate with each other.
• You would lose numbering traceability and quota.

The Sandbox is intended exclusively for testing environments. Before configuring the plugin against your real account, we recommend testing it in a staging environment.

Why it is worth testing first

Before connecting the plugin to your production store, it is worth verifying in a test environment:

• That invoice numbering is applied correctly and does not conflict with any other tool.
• That taxes (including intra-community reverse charge) are calculated as expected.
• That the VAT number field is collected at checkout and propagated to the invoice.
• That webhooks correctly update the order status in WooCommerce.
• That PDFs are generated and can be downloaded from “My Account”.
• That emails to the customer work with the correct text and attachments.

All of this can be validated end-to-end in the sandbox without consuming quota, without sending anything via PEPPOL, and without generating real accounting entries.

Step 1: Create a staging environment for your WordPress

You have two options:

Option A — Hosting staging (recommended if available)

Most managed WordPress providers include a one-click staging system from their control panel:

• SiteGround — Site Tools → Dev → WordPress Staging
• Kinsta — Sites → Create Staging Environment
• WP Engine — Add Staging Environment
• Cloudways — Application → Clone App / Create Staging
• Hostinger — Hosting → Manage → Create staging

Check your hosting panel before installing anything — it is the cleanest way to have a staging environment.

Option B — WP STAGING plugin

If your hosting does not offer staging or you do not have access to it, the free WP STAGING plugin (wordpress.org/plugins/wp-staging) creates a clone of your store in a subdirectory (e.g. yourstore.com/staging) with a single click. The clone has its own login, its own database, and does not touch any data from the real store.

💡 Never mix a B2BRouter sandbox with a production store: always confirm that the URL where you configure the plugin ends in /staging or a test domain before entering any key.

Step 2: Get a sandbox API key

1. Log in to B2BRouter with your usual account.
2. Go to Developers → Sandboxes and open (or create) a sandbox.
3. Inside the sandbox, go to API Keys and generate a new key. It will start with the prefix test_.
4. Copy the key — you will need it in the next step.

For more details about what the sandbox includes and does not include, consult the sandbox technical documentation.

Step 3: Configure the plugin on staging

On your staging WordPress (not on production):

1. Install and activate the B2BRouter plugin as described in the “Requirements and Installation” section.
2. In the plugin settings, enter the test_… key you generated.
3. Configure the rest of the parameters (numbering pattern, taxes, PDFs, etc.) as you would in production — you can return to the “Initial Configuration” section for details.

Step 4: Configure sandbox webhooks

🚧 Webhook support in the sandbox environment is coming soon.

Step 5: Pre-production checklist

Place a test order on staging and confirm:

• An invoice is generated in the B2BRouter sandbox when the order is completed.
• The invoice number follows the pattern you configured.
• Taxes are correct, including reverse charge if you make intra-community B2B sales.
• If the customer enters a VAT number, it is recorded in the invoice.
• The webhook reaches staging and the order status is updated in WooCommerce.
• The PDF downloads correctly from “My Account” (it will carry the “Not valid” mark — this is normal in sandbox).
• Emails fire with the correct attachments.

Step 6: Go to production

When everything works on staging:

1. On your production WordPress, install the plugin (if you have not done so yet) and configure it from scratch with the prod_… key from your real account.
2. Configure the webhooks on the production account of B2BRouter pointing to the production WP URL.
3. Do not migrate data from staging to production — test invoices (those marked as “Not valid”) must stay in the sandbox only.
4. Place a small real test order to confirm that the entire flow also works in production.

---

Initial Configuration

Step 1: Obtain B2Brouter Credentials

1. Register at app.b2brouter.net
2. Purchase an eDocExchange subscription.
3. Go to Developers → API Keys in the B2Brouter dashboard.
4. Copy the API key and store it securely.

💡 You are configuring the production environment. If you have not tested the plugin yet, we recommend doing so first in a staging environment with a sandbox key. See the “Testing the plugin in a staging environment” section.

Step 2: Configure the Plugin

1. Access the settings:

   • In WordPress, go to Invoices → Settings

2. Enter the API key:

   • Paste your B2Brouter API key.
   • Click Validate Key.
   • If the API key is correct, the plugin will display your account information.

3. Configure the generation mode:

   • Automatic: The plugin automatically generates the invoice when an order moves to the Completed status. This is the recommended option if you want to ensure that all orders have an associated invoice.
   • Manual: The plugin does not generate the invoice automatically. The invoice can be generated manually from each order’s detail page and, once the order is in completed status, the customer can also generate it from their account page. This is the recommended option if you prefer the user to decide when to generate the invoice.

Step 3: Configure Invoice Numbering

1. Series Codes:

   • Invoice series code: Prefix for regular invoices (e.g., “INV”, “FAC”)
   • Credit note series code: Prefix for credit notes (e.g., “CN”, “NC”)

2. Numbering pattern (choose one option):

   a) Automatic (Recommended):

   • B2Brouter generates sequential numbers automatically.
   • No need to manage counters.

   b) WooCommerce order number:

   • Uses the native WooCommerce order number.
   • Example: If the order is #1234, the invoice will be INV-1234.

   c) Sequential:

   • The plugin maintains an independent counter
   • Generates numbers like: INV-00001, INV-00002, INV-00003

   d) Custom pattern:

   • Define your own format using placeholders:
   • {order_id}: Order ID
   • {order_number}: WooCommerce order number
   • {year}: Current year (YYYY)
   • {month}: Current month (MM)
   • {day}: Current day (DD)

   Custom pattern examples:

   • INV-{year}-{order_id} → INV-2025-123
   • {year}/{month}/{order_number} → 2025/12/1234
   • INV{year}{month}{day}-{order_id} → INV20251211-123

Step 4: Configure PDFs

1. Automatic PDF cache:

   • Enable this option to download and save PDFs on the server, inside the wp-content/uploads/b2brouter-Invoices/ folder
   • Improves response time for customer downloads.
   • Reduces calls to the B2Brouter API.

2. Automatic cleanup:

   • Enable scheduled cleanup to delete PDFs that exceed the number of days defined in the retention period.
   • Configure the retention period (default: 90 days).
   • Cleanup runs daily via WordPress cron.

3. Attach PDFs to emails:

   • Attach to completed order email: Includes the PDF when the confirmation email is sent.
   • Attach to customer invoice email: Includes the PDF in WooCommerce invoice emails.
   • Attach to refund email: Includes the credit note in refund emails.

---

Invoice Generation Mode

Automatic Generation

If you have enabled Automatic Mode:

1. The customer completes a purchase.
2. Process the order and mark it as Completed.
3. The plugin:
   • Automatically generates the invoice in B2Brouter.
   • Saves the invoice metadata (ID, number, date).
   • Adds a note to the order.
   • Generates and saves the PDF (if enabled).
   • Sends the email with the PDF attached (if configured).

Manual Generation - Individual Order

If you have enabled Manual Mode and need to generate an invoice:

1. Go to WooCommerce → Orders.
2. Open the order you want to invoice.
3. Locate the B2Brouter Invoice meta box.
4. Click the Generate Invoice button.
5. The metabox will display the status and main details of the invoice.
6. You can download the PDF directly from here.

Manual Generation - Bulk Actions

To process multiple orders at once:

1. Go to WooCommerce → Orders
2. Select the completed orders you want to invoice
3. In the bulk actions dropdown menu, choose Generate B2Brouter Invoices
4. Click Apply
5. You will see a message with the result for each order:
   • Successfully generated invoices
   • Invoices that already existed
   • Errors during generation

Generating Credit Notes

Credit notes are generated for WooCommerce refunds:

1. Open the order in WooCommerce → Orders
2. In the ‘Item’ meta box, click Refund (the order must have an invoice).
3. Enter the refund amount, which can be full or partial.
4. Confirm the refund.
5. The credit note is automatically generated in the country-specific format (e.g., Spanish rectifying invoices).

---

Tax Configuration

The plugin reads the WooCommerce tax configuration and automatically converts it into PEPPOL tax categories.

PEPPOL Tax Categories

• S (Standard rate): Standard rate - Applied when taxes exist.
• E (Exempt from tax): Exempt from tax - Taxable products with a 0% rate.
• Z (Zero-rated goods): Zero-rated goods - Products with an explicit zero tax class.
• NS (Not subject to tax): Not subject to tax - Non-taxable products.
• AE (VAT Reverse Charge): Reverse charge - Automatically detected for intra-EU B2B transactions.

Tax Configuration in WooCommerce

1. Enable tax calculation:

   • Go to WooCommerce → Settings → General.
   • In the Tax and coupon section, enable “Enable tax rates and calculations”.

2. Configure taxes

   • Once taxes are enabled, go to WooCommerce → Settings → Tax. From this section you can configure the different tax rates:

   • Configure standard rates:

     • Click the Standard Rates tab.
     • Add your rates by country:
       • Country code
       • Tax percentage
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

   • Configure zero rate:

     • Click the Zero Rate tab.
     • Add your rates by country:
       • Country code
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

   • Configure reduced rate:

     • Click the Reduced Rate tab.
     • Add your rates by country:
       • Country code
       • Tax percentage
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

Intra-EU Reverse Charge

The plugin automatically detects when reverse charge applies:

Conditions:

• The customer provides a valid VAT number
• The customer’s country is different from the merchant’s country
• Both countries are EU member states (27 states)

What the plugin does:

• Marks the transaction as reverse charge (AE category)
• Generates the invoice without taxes applied to the customer
• Indicates that the customer must declare the taxes in their own country

---

NIF/VAT Collection

NIF Field Configuration

The plugin automatically adds a VAT number field to the WooCommerce checkout. Compatible with:

• Block-based checkout (WooCommerce 8.6+)
• Classic shortcode-based checkout

How It Works

1. At Checkout:

   • The “NIF / VAT Number” field appears in the contact information section.
   • It is optional by default.
   • The customer can enter their VAT number for B2B/B2C invoices.

2. Storage:

   • The VAT number is saved as _billing_tin in the order metadata box.
   • It is also saved to the customer’s profile for reuse.

3. Invoicing:

   • If the customer provides a VAT number, a standard invoice (IssuedInvoice) is generated
   • If there is no VAT number, a simplified invoice (IssuedSimplifiedInvoice) is generated
   • For intra-EU transactions with a VAT number, reverse charge is applied

VAT Number Validation

Currently the plugin does not validate the VAT number format. Validation can be added via:

• Third-party validation plugins
• Custom validation with WooCommerce hooks
• Validation through the B2Brouter API

---

Webhook Configuration

Production and sandbox webhooks are completely independent: each has its own configuration and events do not communicate between environments. If you are testing the plugin on staging with a sandbox key, configure the webhooks inside the sandbox pointing to the staging URL. When you move to production, you will need to configure them again on the production account.

Webhooks allow real-time invoice status updates (< 1 second) instead of waiting for the hourly check.

Why Use Webhooks?

• Instant updates: Invoice status appears immediately in the WordPress admin.
• Less load: Reduces API calls
• More reliable: With hourly fallback check

Step-by-Step Configuration

Step 1: Get the URL from the WordPress Admin Panel

1. Go to Invoices → Settings
2. Scroll down to “Webhook Configuration”
3. Enable “Enable Webhooks”.
4. Copy the Webhook URL from the read-only field
   • It looks like: https://yoursite.com/wp-json/b2brouter/v1/webhook
5. Save the settings.

Step 2: Create the Endpoint in the B2Brouter Dashboard

1. Log in to app.b2brouter.net
2. Go to the Developers tab
3. Click on Webhooks in the main menu.
4. Click “Add webhook”
5. Enter a description, e.g. “WooCommerce Store”.
6. Paste the Webhook URL copied from WordPress.
7. Select the events to send. Recommended: select all.
8. Save the endpoint and copy the signing key of the generated Webhook.

Step 3: Complete the Configuration in the WordPress Admin Panel

1. Return to Invoices → Settings → Webhook Configuration.
2. Paste the signing key from B2Brouter.
3. Leave the “Enable Security Check” option enabled.
4. Click “Save Settings”.

Verification

To verify that webhooks are working correctly:

1. Generate a test invoice.
2. The status should appear in less than 1 second
3. If there are issues:
   • Verify that the Webhook URL matches exactly.
   • Make sure the Secret is pasted correctly (no extra spaces).
   • Check that your WordPress site is accessible from the Internet.

Webhook Security

• All requests are cryptographically signed with HMAC-SHA256.
• Requests with invalid signatures are rejected.
• 5-minute timestamp validation to prevent replay attacks.
• The secret is stored securely in WordPress options.

---

PDF Management

Server Storage

When you enable “Automatic PDF Cache”:

1. Location: wp-content/uploads/b2brouter-Invoices/
2. Structure:

   b2brouter-Invoices/
   ├── 2025/
   │   ├── 01/
   │   │   ├── invoice-123.pdf
   │   │   └── credit-note-124.pdf
   │   └── 02/
   │       └── invoice-125.pdf

Automatic Cleanup

The plugin includes a scheduled task to clean up old PDFs:

1. Configuration:

   • Enable the “Automatic cleanup” checkbox.
   • Set the retention period (default: 90 days)

2. How it works:

   • Runs daily via WordPress cron.
   • Deletes files older than the retention period.
   • Maintains the folder structure.
   • Logs cleanups to the WordPress log.

3. Disabling cleanup:

   • If you disable cleanup, PDFs are kept indefinitely.
   • You will need to manage disk space manually.

Manual Invoice Download from the WordPress Admin

1. Go to WooCommerce → Orders and select the order whose invoice you want to download.
2. From the order’s “B2Brouter Invoice” metabox, click Download PDF.
3. If the PDF is cached, it downloads immediately
4. If not, the plugin:
   • Requests the PDF from B2Brouter.
   • Caches it (if enabled).
   • Downloads it to your browser.

---

Customer Experience

Invoice Downloads

Customers can access their invoices in several ways:

1. From their account → Orders:

• The order list is displayed.
  • If the invoice has already been generated, the Download Invoice button will appear in the Actions column of the order list. Click to download the invoice.
  • If the invoice has not been generated, the Generate Invoice button will appear in the Actions column of the order list. Click to generate the invoice. Once generated, the button will change to Download Invoice. Click to download the invoice.

2. From their account → Orders → Order:

• From the order list, in the Actions column of an order, click View on the order.
• On the order details page, you will find:
  • Download Invoice button.
  • Download Credit Note button (if applicable).

2. From email:

   • If you have enabled “Attach to emails”
   • The PDF is included as an attachment in the confirmation email

3. Customer-generated invoices (Manual Mode):

   • If the mode is Manual, customers can generate invoices themselves
   • On the order details page, they will see a Generate Invoice button
   • After clicking, the page refreshes and the PDF is available

Security

The plugin implements several security measures:

1. Ownership verification: Customers can only access their own invoices.
2. Status validation: Invoices can only be generated for completed orders.
3. CSRF protection: All actions use WordPress nonces.
4. Mode validation: Customer-side generation only works in Manual mode.

---

Troubleshooting

Common Issues

1. API Key Validation Error

Symptoms: Message “Error validating the API key”

Solutions:

• Verify that the API key is correct.
• Make sure your eDocExchange subscription is active.
• Check that your server can connect to B2Brouter (not blocked by a firewall).

2. Invoices Are Not Generated Automatically

Symptoms: Orders are completed but no invoices are generated.

Solutions:

• Verify that the mode is set to Automatic in the settings.
• Check that the order status is Completed.
• Review the order notes for any errors.
• Check the WordPress logs for detailed errors.

3. PDFs Are Not Attached to Emails

Symptoms: Emails are sent but without the PDF attachment

Solutions:

• Verify that “Auto-save PDFs” is enabled.
• Check that “Attach to emails” is enabled.
• Make sure the invoice has been generated before the email is sent.
• Review the SMTP server logs for any sending errors.

4. Webhooks Are Not Working

Symptoms: Invoice status is not updated immediately

Solutions:

• Verify that the Webhook URL matches exactly.
• Check that the Webhook Secret is correct.
• Make sure your site is accessible from the Internet (webhooks do not work on localhost without tunneling).
• Review the WordPress logs to see if requests are arriving.
• Check that there are no SSL errors on your site’s certificate.

5. Error “Could not generate the PDF”

Symptoms: The invoice is created but the PDF cannot be downloaded

Solutions:

• Check that the wp-content/uploads/ directory has write permissions.
• Review the invoice status in B2Brouter (it may not have been processed yet).
• Try regenerating the PDF forcefully (Shift + click).
• Verify that the B2Brouter API is operational.

6. PDFs carry the “Not valid” watermark or webhooks are not arriving

Symptom: generated invoices download with a watermark that reads “Not valid”, and/or the order status in WooCommerce is not updated after payment is processed.

Most likely cause: you are using a sandbox API key (starts with test_) instead of a production key (starts with prod_), or your webhooks are configured in the sandbox instead of the real account.

Solution:

1. Check the API key prefix in the plugin settings:
   • test_… → you are in sandbox. Documents have no legal validity and production webhooks will not arrive.
   • prod_… → you are in production. This is what you want on the real store.
2. If you have confirmed the key is prod_… but webhooks are still not arriving, go to the production account of B2BRouter (not the sandbox) and review the webhook configuration.
3. If you are intentionally using the test_… key for testing, make sure you are doing so in a staging environment and not on the real store. See the “Testing the plugin in a staging environment” section.

---

7. Incorrect Tax Errors

Symptoms: Tax categories are not correct on the invoices

Solutions:

• Review the tax configuration in WooCommerce → Settings → Tax
• Make sure the tax classes are configured correctly.
• Verify that products have the correct tax class assigned.
• For non-taxable products, set “Tax status” to “None”.

Enabling Debug Mode

To get more information about errors:

1. Add these lines to your wp-config.php:

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );

2. Errors will be logged to wp-content/debug.log

3. Search for entries containing “B2Brouter” to see plugin errors

Getting Help

If you cannot resolve the issue:

1. B2Brouter Support: eDocExchange customers have access to premium support with:
   • Priority ticket resolution.
   • Support seven days a week.
2. GitHub Issues: github.com/B2Brouter/b2brouter-woocommerce/issues

---

Best Practices

Test Environment

• Start with the sandbox — it is the recommended environment for most tests and initial development work. Use the full staging environment only for large-scale or broad integration tests.
• Test the entire invoicing flow before going to production.
• Generate test orders with different configurations (with/without VAT number, various countries, etc.).

Backups

• Perform regular backups of your WordPress database
• Include the wp-content/uploads/b2brouter-Invoices/ directory in your backups
• Test backup restoration periodically

Monitoring

• Regularly review the B2Brouter → Invoices page to check the status.
• Set up notifications for invoice generation errors.
• Check the WordPress logs periodically.

Updates

• Keep the plugin updated to the latest version.
• Review the changelog before updating.
• Test updates in the staging environment first.

Performance

• Enable “Auto-save PDFs” to improve response time.
• Configure automatic cleanup to manage disk space.
• Use webhooks for real-time status updates.

---

Legal Requirements

Tax Compliance

The plugin helps with tax compliance, but:

• Responsibility: The merchant is responsible for tax compliance.
• Configuration: Make sure the tax configuration is correct for your country.
• Advice: Consult with a tax advisor for the specific requirements of your country.

Data Protection (GDPR)

The plugin processes personal data:

• Legal basis: Necessary for compliance with legal obligations.
• Data processed: Name, address, VAT number, order information.
• Storage: Data is saved in WordPress and sent to B2Brouter.
• Retention: Configure the retention period according to your legal requirements.

Update your privacy policy to include:

• The use of B2Brouter for invoice generation.
• The data that is sent to B2Brouter.
• How customers can exercise their rights.

---

Conclusion

This plugin provides a complete integration between WooCommerce and B2Brouter for automated electronic invoice management. By following this guide, you will be able to configure and use all the plugin’s features effectively.

For any questions or issues, do not hesitate to contact B2Brouter support or open an issue in the GitHub repository.

Enjoy automated electronic invoicing with B2Brouter! 🎉