Bridge WooCommerce orders with Dolibarr

In this tutorial we will explain how to bridge your WooCommerce orders to Dolibarr. The resulting bridge will convert placed orders in WooCommerce to sale orders on the sales module linked to new third parties.

This tutorial assumes you have a Dolibarr instance with access to the REST API and, at least, the Sales module enabled.

Enable the addon

The first step is to enable the Dolibarr addon on the general tab of the settings page.

Once the addon is enabled, we can create bridges to work with the REST API. In addition Forms Bridge offers some templates to start creating our bridges, and workflow jobs.

The template wizard

To streamline the creation process, we will use the Sale Orders template from the addon. To use it, simply go to Add bridge tab on the addon’s page and click on Use a template. After that, the template wizard will be displayed. On the templates dropdown, select the option Sale Orders.

The Sale Orders template is a WooCommerce bridge template and its only available if you have WooCommerce installed and selected as the target integration.

The backend step

The next step on the wizard will ask us for the backend connection. The backend connection will ask us for a name, the URL and an API key. Leave the default backend name and set the URL and your api key and Forms Bridge will perform a ping to the backend to check the health of the connection. If all goes well, the template wizard will allow us to continue.

This step is only required if you already don’t have any backend connection. If you’ve created a backend before, you can simply reuse it and click next.

The bridge step

To finish, the wizard will ask us for the bridge name (remember, it should be unique as it is the identifier). That’s all! Now click on submit and let the magic happen. Behind the curtain, Forms Bridge will create the backend connection and a new bridge that will connect the Woo Checkout form with the backend.

The bridge workflow

After using the template you will have a bridge with the following workflow:

Lets see what happen on each job of the pipeline and how you can add custom configurations to the bridge:

Form submission: This is the first step of the pipeline and allow us to apply mutation layers to the form submission. In this case, the form submission is the order data. This step is configured with a bunch of mutation layers to prune the order data and get only the required fields.
Third party: This workflow job is the responsible to create a new third party on Dolibarr based on the checkout billing data. The job will search for an existing third party by name and email and, if it does not exists, create a new one. Once done, all the billing fields are removed from the payload and replaced with the socid field.
Contact: The next step on the pipeline is the creation of the shipping address. This job gets shipping fields from the payload and creates a new contact linked to the third party. Once done, all shipping fields are removed from the payload.
Products by reference: This job will get the product_refs field of the payload and search for products on Dolibarr. The product_refs array is populated with the product sku values of the order, one for each line, and this values are used to search products by internal reference on Dolibarr. If the amount of found products does not match the amount of lines, the job will through a search error.

Remember! To get this bridge working properly, you have to get your WooCommerce product SKU values synchronized with the Dolibarr products Reference values. This fields are used as the relation between the two inventories.

To avoid search errors on the Products by reference job its important to treat sku values on WC and References on Dolibarr as unique values.

The output of the pipeline should be a payload like this:

{
  "date": "$timestamp",
  "socid": 1,
  "contact_ids": [1],
  "note_private": "Lorem ipsum dolor sit amer",
  "lines": [
    {"fk_product": 1, "subprice": 24.99, "qty": 2, "tva_tx": 21}
  ]
}

Additional configuration

At this point, the bridge is ready for use, you can stop here or continue editing the bridge with custom configurations to fit your specific use case.

A good example is the validation state of your order. By default, the bridge assumes that the order has to be validated and delegates on you to do this validation manually. Depending on your sale workflow, you would prefer to register new orders as already validated. If that’s the case, you can achieve it by adding to the end of the pipeline the job Validate order. This job will add a callback to the form submission to validate the order after it has been created.

If you need to go further with payload mutations you always can use the forms_bridge_payload filter to mangle your bridge submissions with PHP and all of its power and flexibility. Checkout the API documentation.

To conclude, its worth to mention that you can get the same bridge setup doing it manually, but with templates you can save a lot of time! We strongly recommend you to check for templates before start creating new bridges.