Dolibarr Integration

Dolibarr Integration by TechMarbles allows your WooCommerce store to connect with your Dolibarr ERP for automated, reliable and seamless data sync between both the platforms.

The Dolibarr Integration establishes a highly reliable, bi-directional connection between your e-commerce storefront and your enterprise resource planning system (ERP). This integration is designed to eliminate manual data entry, reduce fulfillment errors, and provide your business with a single, unified source of truth for inventory, customer, and financial data.

---

---

Security Notice

↑ Back to top

Do not share your actual API Key or Login credentials in public forums or unencrypted emails. The keys generated in the steps below provide access to your ERP data. Treat them like passwords.

---

Part 1: Prerequisites & Dolibarr Configuration

↑ Back to top

Before connecting the WooCommerce plugin, you must ensure your Dolibarr instance is ready to accept API connections.

Step 1: Enable the REST API Module

↑ Back to top

The integration communicates with Dolibarr via the REST API. This must be enabled first.

1. Log in to your Dolibarr Admin Dashboard.
2. Navigate to Home (top menu) > Setup (left menu) > Modules/Applications.
3. In the search bar, type API.
4. Locate the module named REST API.
5. Toggle the switch to ON (Green).
6. Click the “Gear” icon (Settings) on the module to ensure Production usage is allowed if you are connecting a live store.

Step 2: Create a Dedicated Integration User (Recommended)

↑ Back to top

For security and audit trails, it is best practice to create a specific user for this integration rather than using your main Admin account.

1. Navigate to Home > Users & Groups.
2. Click New User.
3. Login: Enter a recognizable name (e.g., Woo_connector).
4. Password: Generate a strong, secure password.
5. Super Admin: Set to No (recommended) or Yes (if you want full unrestricted access).
   • If set to No: You must manually assign permissions. Go to the Permissions tab for this new user and grant Read/Write access to: Third Parties, Orders, Invoices, Products, and Stocks.

Step 3: Generate the API Key

↑ Back to top

This is the “password” the WooCommerce plugin will use to talk to Dolibarr.

1. Navigate to Home > Users & Groups.
2. Click on the user created in Step 2 (or the user you intend to use).
3. Click the Modify button (pencil icon) on the User Card.
4. Scroll down to the API Key field.
5. Click the Regenerate button (circular arrows) to create a new key.
6. Copy this key immediately. You will need it for the connection settings.

---

Part 2: Connection Details

↑ Back to top

When configuring the Dolibarr Integration plugin, you will be asked for the following details. Please use the values found in your specific Dolibarr installation.

1. Dolibarr URL (API Endpoint)

↑ Back to top

This is the web address where your Dolibarr is hosted.

• Where to find it: Look at your browser’s address bar when logged into Dolibarr.
• Format: It typically looks like your main domain.
• Value to Enter:https://<YOUR_DOLIBARR_DOMAIN>/
  • Note: Ensure you include https:// and remove any trailing text like index.php.

2. DoliAPI Key

↑ Back to top

This is the security token generated in Part 1, Step 3.

• Where to find it: Home > Users & Groups > [Select User] > API Key.
• Value to Enter:[PASTE_YOUR_GENERATED_KEY_HERE]
  • Example format: 79a8s7d98a7sd98a7s9d87a9s8d7

3. Login/Username (Optional for some auth methods)

↑ Back to top

If the plugin requests a Login ID alongside the API Key.

• Where to find it: Home > Users & Groups.
• Value to Enter: [YOUR_INTEGRATION_USERNAME]

---

Part 3: Testing the Connection

↑ Back to top

Once you have entered the details above into the Dolibarr Integration plugin’s settings:

1. Click the “Test Connection” button in the plugin.
2. Success: You should see a green checkmark or a “Connected Successfully” message. This confirms the API Key is valid and the URL is reachable.
3. Failure? Check the following:
   • Is the REST API Module enabled in Dolibarr? (Part 1, Step 1).
   • Does the User have Permissions to view Third Parties/Products?
   • Is your server firewall blocking requests from WooCommerce?

---

4. Product Configuration

↑ Back to top

This section ensures product data, inventory, and pricing are synchronized accurately.

The integration facilitates a reliable bi-directional data flow for products and inventory.

Setting	Purpose	Configuration Guidance
Sync Direction	Determines the authoritative source for product data (e.g., Name, Description).	Bi-Directional is recommended if products are managed in both systems.
SKU/Reference Field	This is the crucial unique identifier. It maps the WooCommerce SKU field to the Dolibarr Reference field.	Dolibarr Ref must contain the exact same value as the WooCommerce product SKU.
Default Warehouse ID	All orders must be allocated stock from a specific Dolibarr warehouse.	Enter the Dolibarr Internal ID for your primary WooCommerce fulfillment warehouse (e.g., 1).
Inventory Sync	Toggles the synchronization of stock levels.	Check this box. Recommended: Set the stock source as Dolibarr.
Pricing Level	Selects the designated Dolibarr price list (Base, Level 1, etc.) that the plugin should use when updating WooCommerce prices.	Ensure the selected level is maintained and accurate within Dolibarr.

---

5. Customer Configuration

↑ Back to top

Managing customer records (Third Parties) ensures accurate sales reporting and CRM activities within Dolibarr.

Setting	Purpose	Configuration Guidance
Create New Customer	If checked, a new WooCommerce customer automatically creates a new Third Party record in Dolibarr.	Check this box for accurate contact management and sales tracking.
Default Guest Customer ID	Crucial for Guest Checkouts. Orders placed without an account will be assigned to this single Third Party ID in Dolibarr.	Create a generic ‘Web Guest’ Third Party in Dolibarr and enter its Internal ID here.
Customer Type	Assigns a classification to the created Third Party record in Dolibarr.	Select CUSTOMER (Recommended).
Address Mapping	Verifies that Billing and Shipping fields (e.g., Address Line 1, City) are correctly mapped to their corresponding fields in the Dolibarr Third Party and Order records.	Verify fields match (e.g., Woo billing_address maps to Dolibarr address).

---

6. Order Workflow Configuration

↑ Back to top

This is the control center for your fulfillment and financial process. The plugin uses Woo order’s status changes as triggers for specific actions in Dolibarr.

The workflow dictates the life cycle of the order from WooCommerce to Dolibarr and back.

WooCommerce Status Trigger	Dolibarr Transaction Action	Recommended Dolibarr Status
Order Paid	Create Sales Order	Validated (Pending Fulfillment)
Order Fulfilled	Create Delivery Note (Item Fulfillment)	Processed/Delivered
Ready for Billing	Create Customer Invoice	Draft or Validated
Order Refunded	Create Credit Note	Validated (reverses the invoice)
Shipping Lines	Include Shipping Fees	Check this to record shipping as a separate line item (usually a service product).
Tax Handling	Calculate Tax using Dolibarr Engine	Recommended: Ensures tax compliance aligns with your Dolibarr setup.

---

7. Logging & Troubleshooting

↑ Back to top

The Logs tab provides comprehensive feedback on every attempted data synchronization.

7.1. Accessing Logs

↑ Back to top

1. Navigate to the Logs Tab within the Woo plugin interface.
2. Filter the log records by Record Type (Order, Product, Customer) or by Status (Success, Warning, Error).

7.2. Troubleshooting Common Errors

↑ Back to top

Error Message Example	Likely Cause	Resolution
Third Party ID not found	The guest checkout order is missing a mapping in Customer Settings.	Enter the Default Guest Customer ID (Part 5).
Stock is insufficient	Dolibarr stock for the ordered item is zero or too low.	Manually update stock in the Dolibarr Product record or wait for replenishment.
API Key unauthorized	The DoliAPI Key has expired or the user lacks necessary permissions.	Regenerate the API Key in Dolibarr (Part 2) and re-enter it, then verify user permissions.
Invalid sales order	The Sales Order (SO) in Dolibarr is already Billed or Closed.	Verify the SO status in Dolibarr and ensure the plugin is not attempting to double-process.

FAQs

↑ Back to top

Help customers by answering commonly asked questions.