OpenCart Connector

Overview

The connector keeps Odoo in sync with your OpenCart store. Because OpenCart has no native admin REST API, the data comes from the bundled bf_api.php companion (a single self-contained PHP file you install on the OpenCart server). It covers:

• Products — import OpenCart products into Odoo product templates, including their categories and images, and (optionally) stock and tax group.

• Customers — import OpenCart customers (name, email, telephone) into Odoo contacts.

• Orders — import OpenCart orders into Odoo sale orders, mapping each order's numeric OpenCart order_status_id to a sale-order action (keep draft, confirm, cancel, or ignore).

• Refunds — optionally discover OpenCart order credit slips (order_slip) and create matching draft customer credit notes in Odoo.

Direction of sync: Odoo ← OpenCart (import is the primary flow; product export and webhook-driven updates are supported).

Every remote call goes through a queue: nothing is written to Odoo until a job runs, jobs retry with back-off on transient failures, and a circuit breaker pauses an instance that keeps failing.

Requirements

• Odoo: 18.0, Community or Enterprise.

• OpenCart: a running OpenCart store you can add one PHP file to, with access to its config.php database credentials. The companion talks to OpenCart's database directly, so it works across OpenCart versions that keep the standard product, customer and order tables. The store must be reachable from the Odoo server.

• PHP / MySQL: the OpenCart host must run PHP with the mysqli extension (standard on any OpenCart server).

• Python: no extra libraries beyond a standard Odoo 18 install.

• Odoo access: any internal user can use the connector screens. The companion token, webhook secret and other credentials are stored in system-only fields, so only the Settings / Administration user can read or change them.

• Network: outbound HTTPS from Odoo to your store. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see Safety features).

Installation

The connector has two parts: the Odoo module, and the bf_api.php companion on the OpenCart server.

Odoo side

1. Copy bambooforge_opencart_connector into your Odoo addons path.

2. Restart the Odoo service.

3. Open Apps, click Update Apps List, search for OpenCart, and press Activate / Install. Dependencies (Sales, Contacts, Invoicing) install automatically.

No OpenCart store is required to evaluate the connector: a mock companion ships inside the module, so you can install, explore and run the full import flow against sample data before pointing it at a real store. To use it, set the instance Base URL to https://<your-odoo-domain>/opencart/mock_api (the mock accepts any non-empty token).

OpenCart side — install the companion

The companion file ships inside the module at bambooforge_opencart_connector/phase2/opencart_api/bf_api.php.

1. Copy bf_api.php to your OpenCart web root — the same directory that holds OpenCart's index.php and config.php (the companion reads config.php from its own directory for the database credentials, so it must sit next to it).

2. The file is then reachable at https://store.example.com/bf_api.php.

3. Set its token (next section), and always serve it over HTTPS in production — the token travels in the request.

Step 1 — Configure the companion token & URL

The companion is protected by a single shared token. It is read from the BF_API_TOKEN environment variable if set, otherwise from the constant at the top of the file (which ships as the placeholder CHANGE-ME-LONG-SECRET). You must change it.

1. Open bf_api.php and either:

   • set the BF_API_TOKEN environment variable on the OpenCart host to a long random secret, or

   • edit the line define('BF_API_TOKEN', getenv('BF_API_TOKEN') ?: 'CHANGE-ME-LONG-SECRET'); and replace CHANGE-ME-LONG-SECRET with your own long secret.

2. Keep that exact secret — you will paste the same value into the Odoo instance API Token field in Step 2. They must match exactly.

3. Verify the companion responds. In a browser or with curl (replace the token):

   https://store.example.com/bf_api.php?token=YOUR-SECRET&resource=ping

   A healthy companion returns JSON like {"ok": true, "platform": "opencart", ...}. A 401 Unauthorized means the token does not match; a 500 with "OpenCart config.php not found" means bf_api.php is not next to config.php.

The companion exposes only read endpoints — ping, products, customers and orders — and authenticates every request, either by the token query parameter or an X-BF-Token header.

Step 2 — Create the connection in Odoo

Open OpenCart Connector ▸ Configuration ▸ Instances and create a record.

Key fields:

Then click Test Connection. The connector calls the companion's ping endpoint; a green Connected state means the URL and token are correct, and the default order-status mappings are seeded on the first successful connect. If it fails, the exact error is shown on the form and recorded in Logs (see Troubleshooting).

Tip: use Quick Setup (button on the instance) to pick a use case (catalog only, B2C full sync, …), seed default field mappings and order-status rules, and apply a recommended schedule in one step.

Step 3 — First sync (dry-run, then live)

New instances start with Dry-run ON. In dry-run, import and delete jobs simulate writes: instead of changing data they produce Validation Results you can review under OpenCart Connector ▸ Operations ▸ Validation Results. This lets you confirm what would happen before anything is written.

To run a first import:

1. On the instance, click Import Products (and/or Import Customers, Import Orders). This enqueues jobs; it does not block the UI.

2. Jobs are processed by the OpenCart Queue Processor scheduled action (every minute), or immediately if you run it manually from Operations ▸ Queue Jobs.

3. Review Validation Results while still in dry-run.

4. When satisfied, open the instance, turn Dry-run OFF, and run the imports again to write the records for real.

Imported records land in the standard Odoo apps: Sales ▸ Products, Contacts, and Sales ▸ Orders. Each carries its OpenCart reference so re-imports update the same record instead of duplicating it.

Order status mapping

OpenCart stores each order's status as a numeric order_status_id, which the connector normalizes onto the order. Under Configuration ▸ Order State Mappings each instance gets a default table (seeded on first successful connect) that decides what happens to the Odoo sale order when an order arrives in a given status:

Change any row to Ignore (do nothing), Keep draft, Confirm sale order or Cancel sale order. Unknown/custom statuses default to Ignore, so a status you have not mapped never triggers a destructive transition. Add a row for any custom status your store introduces (use the exact numeric order_status_id).

Field mapping & customization

• Field Mappings (Configuration) map OpenCart fields to Odoo fields per model. Use Generate suggested mappings on the instance to seed the business-critical ones, then adjust. The mapping board flags fields that need attention.

• Schema Fields lists the discovered OpenCart fields per resource. Run Schema Introspection on the instance to refresh it from your live store (it falls back to sample data if the store is not reachable).

• Stock / images / tax are opt-in toggles on the instance: Sync stock, Sync images (and max images), Upload images on export, Sync taxes and Auto-match taxes on import. They are off by default; turn on only what you need. Tax matching is name-based and never auto-creates taxes.

• Refunds are opt-in: turn on Sync refunds to create draft credit notes from OpenCart order slips, and Auto-post refunds if you want them validated automatically (off by default so accountants can review first).

Automation (scheduled actions & webhooks)

The module ships these scheduled actions (Settings ▸ Technical ▸ Scheduled Actions):

Turn on Auto import / Auto reconcile per model on the instance to let the scheduled actions keep things in sync hands-free.

Real-time webhooks (optional): if your store (or a custom OpenCart extension) can POST events, point them at:

• Delivery URL: https://<your-odoo-domain>/opencart/webhook

• Signature header: X-Opencart-Signature — an HMAC-SHA256 of the raw body using the instance Webhook Secret (admin-only field on the instance).

Odoo verifies the signature on each delivery, rejects stale or replayed requests (the signed emitted_at must be recent), and enqueues a safe import. Without webhooks the scheduled reconciliation still keeps data current.

Safety features

• Dry-run mode — simulate writes and review Validation Results before going live.

• Business validation profiles — Minimal / Standard / Strict gate risky writes.

• Resilient queue — every remote action is a job with retry and exponential back-off, plus a dead-letter state for jobs that exhaust their retries.

• Circuit breaker — after repeated failures an instance auto-pauses (Tripped); the Auto Recover action reopens it once the store responds again.

• Rollback snapshots — when enabled, imports capture a snapshot so you can undo a batch from Operations ▸ Rollback Snapshots.

• SSRF guard — the connector refuses internal/loopback/private hosts unless Allow internal host is explicitly enabled.

• Token-only companion — bf_api.php rejects every request without the matching token and exposes read-only endpoints; serve it over HTTPS so the token is not exposed.

Troubleshooting

For anything else, Operations ▸ Logs records every API call, payload and error with a timestamp.

Frequently asked questions

Which versions are supported? Odoo 18.0 on the Odoo side. On the store side the companion reads OpenCart's database directly, so it works with OpenCart builds that keep the standard product, customer and order tables. Validate your exact build with the bundled mock first.

Why does it need a PHP file? Can't it use OpenCart's API? OpenCart ships no rich admin REST API. The connector therefore includes bf_api.php, a small self-contained, token-secured companion you drop at the OpenCart web root; it reuses OpenCart's config.php for database access and returns products/customers/orders as JSON.

Where exactly do I put bf_api.php? In the OpenCart web root, the directory that already contains index.php and config.php. It must sit next to config.php because it reads the database credentials from there. It is then reachable at https://store.example.com/bf_api.php.

Do I need OpenCart installed to evaluate it? No. A mock companion ships inside the module. Point the instance Base URL at https://<your-odoo-domain>/opencart/mock_api (any non-empty token) and run the full import flow before connecting a real store.

How does authentication work? A single shared token. Set BF_API_TOKEN in bf_api.php (constant or environment variable) and paste the same value into the Odoo instance API Token field. The companion rejects every request whose token does not match.

How does real-time sync work? If your store can POST events, point them at /opencart/webhook with an X-Opencart-Signature HMAC-SHA256 of the body using the instance Webhook Secret; Odoo verifies the signature and enqueues a safe import. Without it, scheduled reconciliation keeps things in sync.

Is it safe to run against production data? Dry-run is ON by default, validation blocks risky writes, and rollback snapshots let you undo. You decide when to go live. The companion is read-only.

What support and refund policy do I get? Every request is answered within 24 hours, setup help included. If you report a bug within 2 months of purchase and it is not resolved within 15 days, you are entitled to a full money-back refund.

Data, privacy & limits

• The connector reads products (with categories and images), customers, orders and order slips from your store via bf_api.php and writes the corresponding Odoo records. The companion token, webhook secret and other credentials are stored in admin-only fields.

• The companion is read-only: it exposes only the ping, products, customers and orders endpoints and never writes to the OpenCart database.

• In scope today: product/customer/order import (with categories and images), order-status mapping, refund discovery from order slips, product export, scheduled sync, signed webhooks.

• Out of scope / best-effort: tax auto-matching (off by default, name-based, never auto-creates taxes); multi-warehouse stock routing; subscription/booking order types.

Support & updates

• Support: support@bambooforge.dev — answered within 24 hours, setup help included.

• Refund: report a bug within 2 months of purchase; if unresolved within 15 days, full refund.

• Full source is included, companion file bundled. Updates track the supported Odoo 18 line.

Upgrading & version compatibility

This build targets Odoo 18.0. Each Odoo major series (17.0, 18.0, 19.0) has its own dedicated build of this module — always install the build that matches your Odoo version. Mixing a build with a different Odoo series is not supported.

Uninstallation

You can remove this module at any time from Apps → (this module) → Uninstall, or from the command line. Uninstalling is clean and reversible by reinstalling — but note what is and is not deleted.

Changelog