The Elbuz API Sync module on an OpenCart 3 store sends orders to Elbuz itself: new ones right after checkout, existing ones after each status change. They become “Customer order” documents.
When you need this:
- Managers need orders in Elbuz at once — they arrive within seconds, no schedule.
- A customer paid on the site — the payment module sets a status, and the order becomes “Paid”.
- Elbuz is down — checkout works; the order waits in the module queue.
- Elbuz Tunnel still picks up orders — the module continues the same documents, no duplicates.
Where to start: download and install the module, then issue it a key in Elbuz.
What the module does
- Sends orders at once and after every status change — whether it comes from checkout, a payment module or a manager in the OpenCart admin.
- Translates site statuses into Elbuz statuses — document status and payment status, by your mapping table.
- Uploads older orders — all orders changed since the date you pick.
- Doesn't lose orders when Elbuz is unavailable — keeps them in a queue and retries.
- Shows a log of sends — what went out, into which document, and why something failed.
- Continues the Elbuz Tunnel history — orders go into the same documents.
How to install the module on your site
- Download the elbuz_api_sync.ocmod.zip archive.
- In the OpenCart admin, open “Extensions → Installer” and upload the archive with the “Upload” button. If you can't use the installer, copy the contents of the
uploadfolder from the archive to the site root. - Open “Extensions → Extensions” and choose “Modules” in the extension type list.
- In the “Elbuz: order sync” row, click “Install” (green plus), then “Edit” (pencil).
After installation the module is off and sends nothing until you fill in the connection and save it with “Status” set to “Enabled”. Removing the module with “Uninstall” deletes its queue and log.
How to issue a key for the module in Elbuz
The module needs its own API v2 key. The key name becomes the order source in the list, and Elbuz uses the key to recognize orders it already has.
- In Elbuz, open “API and access tokens” and click “+”.
- In the “User” field, enter the store name, for example
site_opencart. - In “On behalf of”, choose an employee who has the orders window open and the “Add” button allowed.
- Clear “Read only”.
- Switch “Data changes” to “Act on its own”. Only the “Management” group can switch it.
- In “Safety limit: changes per hour”, set a number with headroom: each module send counts as one change, even if it carries 100 orders.
- Save and copy the key — it starts with
elbz_.
1
User = key name2
Data changes: Act on its own3
Safety limit: changes per hour4
Read only (off)- User — the key name, which also becomes the source of the orders it brings in.
- Data changes — set to “Act on its own”, so the key writes changes itself.
- Safety limit — at most 1000 changes per hour are allowed for this key.
- Read only — switched off, so the key may create and update orders.
If you leave “Data changes” in “Ask” mode, or the key exceeds the safety limit, every send waits until someone accepts it in “Pulse”. In the module log these orders show the result “waiting for confirmation in Elbuz”, and they are not in the Elbuz order list.
One key per site. Under a shared key, identical order numbers from two sites merge into one document. General key rules are in API v2.
How to connect the module to Elbuz
Where: the “Elbuz: order sync” module → “Connection” tab.
- “Status” — “Enabled”.
- “Elbuz API address” — your account address ending with
/api/v2:https://your-domain.elbuz.com/api/v2. An address withouthttps://orhttp://won't save: “The API address must start with https:// or http://”. - “API key” — the key you copied in Elbuz.
- Leave “Elbuz template ID” empty. You only need it when moving from Elbuz Tunnel.
- Click “Check connection”. The reply “Connected. Document statuses received: N, payment statuses: M.” means the address and key are correct, and Elbuz statuses now appear on the “Statuses” tab.
- Save the module with the blue floppy-disk button at the top right.
“Check connection” takes the address and key straight from the form, without saving. The module starts sending orders only after you save. A failed check reads “No connection to Elbuz: …” with the reason — see the table below.
How to map site statuses to Elbuz statuses
Where: the “Statuses” tab. For each OpenCart status, choose “Elbuz document status” and “Elbuz payment status”. The list of Elbuz statuses appears after “Check connection”.
| Status on the site | Elbuz document status | Elbuz payment status |
|---|---|---|
| Pending | New | Pending |
| Processing, paid | Paid | Paid |
| Canceled | Canceled | — do not change — |
OpenCart has no separate payment status: payment is shown by the same order status. So for the statuses your site gives paid orders, choose “Paid” in the payment column.
“— do not change —” means this site status doesn't change the matching status in Elbuz. A new order with no mapping gets the default status, “New”. If “Elbuz template ID” is filled in, the template's status mapping applies to empty rows.
The module sends an order every time its status changes. Whether a new site status overwrites the one a manager set in Elbuz is decided by the general rules: which status wins. Line items are written only when the document is created.
How to send orders that are already on the site
The module sends new orders by itself. Send the ones that existed before installation manually.
Where: the “Send” tab.
- In “Orders changed since”, pick a date. The default is 30 days ago.
- Click “Send”. The module takes all orders changed since that date, except abandoned carts with no status, and sends them in batches of 100.
- Keep the page open until “left in queue: 0” appears next to the button. The line reads “Sent: N, errors: M, left in queue: K”.
Sending the same orders again creates no duplicates: they are updated in the documents already created. Use the same button to catch up after a failure — pick the date from which orders didn't arrive.
Cron URL
Under the button there is a “Cron URL”. Add it to your hosting scheduler to run every 5–15 minutes, for example:
*/10 * * * * curl -s "https://your-site/index.php?route=extension/module/elbuz_api_sync/cron&key=…" >/dev/null
Cron sends whatever didn't go through at once — up to 1000 orders per run. Without it, the queue goes out with the next site order: if there are no orders at night, one held up yesterday arrives only in the morning. A URL without the correct key returns 403 and sends nothing.
How to check that orders arrive
- Place a test order on the site.
- In the module, open the “Journal” tab. The order should have the state “sent” and the result “created”. The “Elbuz document” column shows the document ID in Elbuz, not its number in the order list.
- In Elbuz, open the “Orders” window. The order is at the top with the source “API: key name”; its site number is stored in the document as a separate field.
- Change the order status in the OpenCart admin. The log shows “updated”, and Elbuz shows the status from your mapping table.
The log shows the last 30 orders. Yellow rows are still in the queue, red ones were not sent; the reason is in the “Message” column. The number in the “Order” column opens the order in OpenCart.
1
Order paid on the site2
Delivery status On the way3
New order, not paid yet- An order paid on the site arrives in Elbuz with the payment status Paid and the order status Paid.
- The delivery status from the site, On the way, is carried over to the order.
- A new order that is not paid yet stays New with the payment status Pending.
What happens if Elbuz doesn't respond
The module doesn't slow down or break checkout on the site. It waits up to 5 seconds for Elbuz to reply, then writes the error to the log and keeps the order in the queue.
- Start or end
- Action or result
- Decision: the path depends on the answer
| What happened | What the module does | State in the log |
|---|---|---|
| Elbuz accepted the order | Records the document number | “sent”, “created” or “updated” |
| The key is in “Ask” mode | Stops retrying: the request is already in “Pulse” | “sent”, “waiting for confirmation in Elbuz” |
Elbuz rejected one order's data (422 with an orders[…] field) | Stops only that order; the rest of the batch goes on | “not sent”, “error” |
| No connection, key or permission error, rate limit, another 422 reply (for example, template not found) | Retries after 1, 4, 9 … minutes; the longest pause is 12 hours | “queued”, “error” |
| 30 failed attempts in a row | Stops retrying | “not sent”, “error” |
An order marked “not sent” goes out again when its status changes on the site, or when you click “Send” with a date that covers it. Every retry takes the order's current data.
How to move from Elbuz Tunnel without duplicates
Orders already picked up by the tunnel are stored with its template as the source. To make the module update those documents instead of creating new ones, enter that template's number.
- In Elbuz, open Directories → Operations → Data import. The tunnel template number is in the last column of the template list, “ID”.
- In the module, on the “Connection” tab, enter it in “Elbuz template ID” and save.
- Change the status of one old order on the site. The module log should show “updated”, not “created”.
- In the tunnel template, clear the “Orders” checkbox so orders don't arrive two ways. The tunnel keeps picking up the catalog.
With “Elbuz template ID” set, the template's status mapping applies: its “Order statuses” and “Payment statuses” buttons. A row filled in on the module's “Statuses” tab takes priority over the template. The template must be visible to the key's employee, otherwise a send returns 422 with "template_id": "not found".
Scenarios
New store: orders must appear in Elbuz at once
Task: the manager works in Elbuz and shouldn't wait for a schedule to see site orders.
What to do: a separate key in “Act on its own” mode; in the module — “Status” “Enabled”, the address, the key, “Check connection”, status mapping, save; “Send” with the date the site went live; the cron URL in the scheduler every 10 minutes.
Result: each new order becomes a “Customer order” document with the source “API: key name” within seconds, and a status change on the site updates the same document.
Card payment on the site must show up in Elbuz
Task: the manager shouldn't reconcile payments with the payment provider by hand.
What to do: on the “Statuses” tab, for the status the payment module sets after payment, choose “Paid” in both columns.
Result: as soon as the payment module changes the status, the order in Elbuz gets the payment status “Paid”. Stock and reservations don't change until the document is posted.
Catalog via the tunnel, orders via the module
Task: for years the tunnel picked up both the catalog and orders; orders now need to arrive at once, not with the next run.
What to do: move from the tunnel: the tunnel template in “Elbuz template ID”, a check on an old order, then clear the “Orders” checkbox in the template.
Result: old orders are updated in the same documents, and new ones go there too. The tunnel keeps updating the catalog on its own schedule.
What to do when orders don't arrive
| What you see | Why | What to do |
|---|---|---|
| “No connection to Elbuz: HTTP 401 invalid, disabled or expired key” | the key was copied partially, turned off or replaced with a new one | copy the key again from “API and access tokens” and check the key's “Active” flag |
| “No connection to Elbuz: HTTP 404” or a connection error | the address lacks /api/v2 or the domain is wrong | the address must be https://your-domain.elbuz.com/api/v2 |
| “HTTP 403 read-only key” in the log | the key has “Read only” checked | clear the checkbox in the key; the module retries on its own |
| “HTTP 403 no right for sync” in the log | the key's employee isn't allowed the “Add” button in the orders window | grant the right or choose another employee in the key |
| “HTTP 403 IP … is not allowed for this key” in the log | the key has a list of allowed IPs, and the site server isn't on it | add the site server's IP to the key |
| Result “waiting for confirmation in Elbuz”, and the order isn't in Elbuz | the key is in “Ask” mode or exceeded the safety limit | accept the requests in “Pulse”, switch the key to “Act on its own”, raise the safety limit (key) |
“not sent”, with HTTP 422 and an orders[…] field in “Message” | Elbuz didn't accept the order data, for example a mapped status was deleted in Elbuz | click “Check connection”, choose the statuses again, save and send the order with “Send” |
| An order stays “queued” for a long time | Elbuz didn't respond, and cron isn't set up | add the cron URL or click “Send” |
| The same order appears twice in Elbuz | the tunnel loaded it, and the module runs without “Elbuz template ID”; or the key was replaced with a different one | move from the tunnel; don't switch the module to a different key, only reissue the same one |
| The log is empty after a new order | the module is disabled or the settings weren't saved | set “Status” to “Enabled” and save; until then “Send” replies “Enable the module and save the settings.” |
FAQ
Does the module send products and prices to Elbuz?
No, only orders. Elbuz Tunnel brings the catalog from the site, and tunnel export sends it from Elbuz to the site.
What currency do amounts arrive in?
In the order currency, that is, the way the customer paid. Line prices include tax; shipping comes as a separate amount.
A customer added a product to an order on the site — will the document change?
No. Line items are written only when the document is created; copy a changed order composition into the document by hand. Until the document is posted, repeat sends update the status, payment and shipping method; the address, amounts and customer stay from the first send.
Does the module work on OpenCart 2 or 4?
No, the module is for OpenCart 3.0.x. On an OpenCart 2 site, the tunnel picks up orders.
Will an order from the module reduce stock?
No. The document is created unposted, and Elbuz counts stock and reservations only from posted documents.
What happens if I delete an order on the site?
The document in Elbuz stays: the module doesn't delete documents. Before deleting, move the order on the site to a status mapped to “Canceled”, or delete the document in Elbuz.
Where it is and who has access
- Download
- elbuz_api_sync.ocmod.zip — OpenCart 3.0.x, PHP 7.1+ with curl
- Module on the site
- Extensions → Extensions → Modules → “Elbuz: order sync”
- Key in Elbuz
- Account → System settings → “Other settings” → “API and access tokens”
- Access rights
- the key's employee needs the orders window and its “Add” button
- Where orders show up
- the “Orders” window, source “API: key name”
The module sends orders only. It doesn't send the catalog: Elbuz Tunnel brings products from the site into Elbuz.
Related topics
- To understand whose status remains after a send — which status wins.
- If your site isn't on OpenCart 3 and you write the module yourself — orders via API v2.
- If you also need to bring the catalog from the site — moving the catalog with Elbuz Tunnel.
- If another system needs to learn about order changes — API v2 webhooks.
