OneBox Sync — CRM for OpenCart 2.3, 3.x and 4.x

OneBox Sync for OpenCart is a module that links a store on OpenCart 2.3, 3.x or 4.x to OneBox OS: every new order automatically becomes a process/order in the CRM, together with the customer, phone number, shipping address and items. Instead of transferring data by hand, the manager sees the request in OneBox straight away and works it through your own business process.

The module is completely free, the code is open. Repository on GitHub: github.com/catcodestudio/opencart-onebox-sync. No keys, no subscriptions, no order limits.

How it works, step by step

1. The customer places an order — the module reacts to the order-history-add event, without touching checkout.
2. The module authenticates with your OneBox: gets a token via POST /api/v2/token/get/ and sends the order via POST /api/v2/order/set/.
3. Items are matched to the OneBox catalogue: name, SKU (article/model), quantity and price — catalogue products are found or created automatically, with no duplicates in the catalogue. Shipping is passed as a separate line, so the process total matches the order total.
4. OneBox returns a process ID — it’s recorded in the sync log; an externalid is also passed, so a repeat trigger won’t create a second process.
5. Failed sends are retried by a cron job — orders that didn’t go through on the first attempt reach the CRM automatically.

Under the hood

• OpenCart events — the module subscribes to the order-history-add event (addHistory in OpenCart 4, addOrderHistory in 3.x and 2.3); core and theme files are not modified.
• Idempotency: an upsert by externalid on the OneBox side plus a unique sync log in the store’s database — no duplicate processes and no duplicate catalogue items.
• Mapping of items, payment and shipping into the OneBox process fields; optional workflowid/statusid/sourceid routing (empty = the first business process automatically).
• Cron retry queue for orders that failed to send the first time: it picks up both failed sends and ones stuck “in progress” for over an hour (for example if PHP was interrupted mid-request).
• Cron token — the public retry URL can be locked down with a shared secret: ...&token=<value>. OpenCart 4’s built-in scheduler also works without a token; an empty field leaves the endpoint open.
• The API password is stored encrypted in the database, and the sync log holds the API request and response for diagnostics.

How to install

1. In OneBox, install the “API v2” component (1b.app → Apps → API Services) and set an employee’s login and password (Users and Employees → Login, password, access rights).
2. Upload cc_onebox.ocmod.zip via Extensions → Installer in the OpenCart admin. For OpenCart 3.0.2–3.0.5 use the separate build — cc_onebox-oc3.ocmod.zip (after installing, refresh modifications: Extensions → Modifications → “Refresh” button).
3. For OpenCart 2.3.0.0–2.3.0.2 use the build cc_onebox-oc2.ocmod.zip. ⚠️ The built-in 2.3 installer copies files via FTP only: if FTP isn’t configured, unpack the archive and upload the contents of the upload/ folder to the store root, then go to Extensions → Modules → OneBox Sync → “Install”.
4. In Extensions → Modules, find OneBox Sync, click “Install” and open the settings.
5. Enter your OneBox domain, API login and API password, then click “Test connection”.
6. If needed, fill in the business process, stage and source IDs (you can leave them blank — the module will take the first business process) and save.
7. Place a test order and check the process in OneBox and the entry in the log.
8. OpenCart 3.x and 2.3 have no scheduler — the retry line is added to the hosting’s crontab manually (typically every 15 minutes):
   curl -s "https://SHOP/index.php?route=extension/module/cc_onebox_cron/retry&token=TOKEN" (on 3.x the route is extension/module/cc_onebox/cronRetry; the ready-made URL is shown in the module settings)