Casas Bahia Store Management
This is the installation and configuration guide for Casas Bahia Store Management, the module you downloaded from your ECOSIRE dashboard or the Odoo App Store. Everything on this page describes the casasbahia_store_management module exactly as it ships today — the facts below were read out of the released build, not from a roadmap.
| Technical name | casasbahia_store_management |
| Odoo versions | 17.0, 18.0, 19.0 (Community or Enterprise) |
| Current shipped version | 17.0 → 17.0.1.1.0, 18.0 → 18.0.1.1.0, 19.0 → 19.0.1.2.1 |
| Price | $499 USD — one-time, per Odoo version |
| Odoo module licence | OPL-1 |
| Category | Connector |
This module installs and runs standalone. There is no licence client to install, no activation key, and nothing to switch on — buy it, install it, connect it to your Casas Bahia seller account, and it works. The OPL-1 licence is contractual: one purchased copy per installation, as with any Odoo App Store module.
Requirements
| Requirement | Detail |
|---|---|
| Odoo | 17.0, 18.0 or 19.0, Community or Enterprise. Self-hosted or Odoo.sh — Odoo Online (SaaS) cannot install third-party modules |
| Odoo apps | base, sale_management, stock, account, delivery, mail, web, portal, product, contacts, digest — Odoo installs any that are missing automatically |
| Python packages | requests |
| Platform account | A Casas Bahia seller account with API access |
Install the Python packages into the same interpreter that runs Odoo:
sudo -u odoo pip install requests
Installation
1. Download the ZIP for your Odoo version
Sign in at ecosire.com and open your dashboard downloads, or download the ZIP from your Odoo App Store purchase. Take the build that matches your Odoo major version — a 19.0 ZIP will not install on an 18.0 database.
2. Extract into your addons path
unzip casasbahia_store_management_v19_*.zip -d /opt/odoo/addons/
ls /opt/odoo/addons/casasbahia_store_management/__manifest__.py # sanity check
The module must end up as a single top-level casasbahia_store_management/ directory with __manifest__.py directly inside it. If your ls check fails, the folder landed one level too deep or too shallow — move it so the path above resolves.
3. Restart Odoo and install
sudo systemctl restart odoo
- Go to Apps and click Update Apps List (developer mode must be on).
- Search for Casas Bahia Store Management and click Install.
- Odoo pulls in the Odoo apps listed above automatically.
When the install finishes, a Casasbahia menu appears in the main Odoo app switcher.
Configuration
Get your Casas Bahia API key
Casas Bahia (Grupo Casas Bahia / Via) uses API-key authentication — there is no OAuth flow and no OAuth screen. Generate your key in the seller portal:
- Sign in to the Casas Bahia seller portal.
- Open Minha Conta → API → Gerar Chave.
- Copy the key. Keys are tied to your CNPJ and rotate every 90 days — put a reminder in your calendar, because a silently expired key is the most common cause of a connector that used to work and now does not.
Connect to Casas Bahia
Go to Casasbahia → Configuration → Instances and create a connection record. The fields the module defines for the connection are:
| Field | Technical name | Type | Required |
|---|---|---|---|
| Instance Name | name | Char | Yes |
| Casasbahia Shop URL / Store ID | shop_url | Char | Yes |
| Company | company_id | Many2one | Yes |
| API Key | api_key | Char | No |
| Webhook Secret | shared_secret | Char | No |
The fields marked Yes are enforced by the model — Odoo will not let you save the record without them. The API key and webhook secret are only visible to system administrators (base.group_system). Use Test Connection on the record to verify the key against the marketplace before importing anything.
The same record carries the settings that drive what happens automatically after an import — all three default to off, and each one gates the next, so switch them on one at a time as you gain confidence:
| Setting | What it does when on |
|---|---|
auto_confirm_order | Confirms each imported sale order instead of leaving it in draft |
auto_create_invoice | Creates the customer invoice for a confirmed order |
auto_validate_invoice | Posts the invoice that was created |
Beyond those, the instance record also lets you set a Default Warehouse applied to imported orders, a Payout Journal used when payouts create bank statements, a pricelist and a default salesperson, risk thresholds for order risk scoring, and your monthly marketing/operating cost figures used by the profit analytics.
The module contacts the marketplace API at developers.casasbahia.com.br. Your firewall must allow outbound HTTPS to it.
Webhooks
The module listens on four public endpoints so the marketplace can push events to your Odoo instead of waiting for the next scheduled sync:
| Endpoint | Payload |
|---|---|
POST /casasbahia/webhook/order | Order notification |
POST /casasbahia/webhook/product | Product notification |
POST /casasbahia/webhook/customer | Customer notification |
POST /casasbahia/webhook/refund | Refund notification |
Every incoming call is authenticated: the request must carry an X-Casasbahia-Hmac-SHA256 header with the HMAC-SHA256 signature of the raw body (computed with the Webhook Secret of the instance), and an X-Casasbahia-Shop-Domain header identifying which instance the event belongs to. A call with a missing or wrong signature is rejected without touching any data. Accepted payloads are recorded as a queue job (Casasbahia → Operations → Queue Jobs) and applied from there, so a busy marketplace can never block the HTTP request.
Each webhook subscription (Casasbahia → Configuration → Webhooks) then decides what actually happens to the payload:
| Setting | Behaviour |
|---|---|
| Auto Process | With it off, the notification is recorded on the subscription (statistics and a message) but nothing is applied to Odoo — useful for a trial period. With it on, the payload is applied as described below. |
| Create Odoo Record | An event referencing a record Odoo does not know yet fetches and imports that single record |
| Update Odoo Record | An event for an existing record updates it |
| Delete Odoo Record | A cancellation (for example a cancelled order) archives the corresponding Odoo record |
There is also a user-authenticated helper route, /casasbahia/verify, used internally by the Test Connection button on the instance form. It is not an integration surface — you do not need to configure anything for it.
Scheduled actions
The module installs 13 scheduled actions (Settings → Technical → Scheduled Actions):
| Scheduled action | Runs every | Enabled on install |
|---|---|---|
| Casasbahia: Sync Products | 30 minutes | Yes |
| Casasbahia: Sync Orders | 15 minutes | Yes |
| Casasbahia: Sync Customers | 60 minutes | Yes |
| Casasbahia: Sync Inventory | 10 minutes | Yes |
| Casasbahia: Process Queue Jobs | 5 minutes | Yes |
| Casasbahia: Import Payout Reports | 6 hours | Yes |
| Casasbahia: Import Refunds | 30 minutes | Yes |
| Casasbahia: Auto Risk Detection | 30 minutes | Yes |
| Casasbahia: Generate Analytics | 4 hours | Yes |
| Casasbahia: Webhook Health Check | 60 minutes | Yes |
| Casasbahia: Cleanup Old Logs | 24 hours | Yes |
| Casasbahia: Process Workflows | 10 minutes | Yes |
| Casasbahia: Daily Summary Report | 1 day | Yes |
Intervals above are the shipped defaults. Adjust them to your volume — but be aware that the platform, not Odoo, sets the API rate limits, and shortening a sync interval is the usual cause of throttling errors in the logs.
Using the module
The module's menu is laid out as:
- Casasbahia → Dashboard
- Casasbahia → Orders
- Casasbahia → Refunds
- Casasbahia → Products
- Casasbahia → Customers
- Casasbahia → Payouts
- Casasbahia → Analytics
- Casasbahia → Operations — Run Operations, Queue Jobs, Logs
- Casasbahia → Configuration — Instances, Locations, Payment Gateways, Scheduled Actions, Webhooks
A normal first run is:
- Save the connection record and use Test Connection to confirm the module reaches the marketplace before importing anything.
- Run a small import first — Run Operations with a narrow From/To Date or a handful of Specific IDs — and check the results before letting the scheduled actions take over.
- Watch the log records during the first full sync. Failures are recorded there rather than raised at the user.
Run Operations (the import wizard)
Casasbahia → Operations → Run Operations runs any of the module's import/export operations on demand. The options that shape the run:
| Option | What it does |
|---|---|
| From Date / To Date | Restricts the run to that date window |
| Specific IDs | Imports only the records with those marketplace ids — the fastest way to re-pull one problem order or product |
| Skip Existing Records | Leaves records Odoo already has untouched instead of updating them |
| Import Product Images | Also downloads and attaches the marketplace product images to the Odoo product during catalog import |
The operation list includes Import Unshipped Orders (only orders that have not shipped yet, not a repeat of the general order import), Import Locations (reads your seller shops as warehouse locations), Import Stock Levels (applies each offer's sellable quantity to the mapped warehouse) and Export Stock Levels (pushes the Odoo on-hand quantity back onto the offer).
Payouts and reconciliation
The Payouts menu shows each marketplace payout the connector imported: total, fees, net, status, and the full transaction ledger behind it as payout lines. On each payout, Create Bank Statement produces the bank statement on the payout journal, and the two settings on the payout record — create_bank_statement and skip_import — decide whether an import does this automatically and whether a given payout should be skipped entirely. Reconciled and unreconciled amounts are tracked on the payout so you can see at a glance which payouts still need attention.
Dashboard, analytics and orders
The dashboard's period selector is per-visit: two users looking at different date windows get their own figures — one user's view never overwrites the shared numbers. Amounts are shown in the currency of the records, not a hardcoded dollar sign. Both dashboard charts are clickable and drill down into the underlying orders, and the Orders list itself offers kanban, pivot and graph views alongside the list and form.
Roles
Workflow actions are guarded by role, matching what the module's access rights allow — payouts and statement actions need the Casas Bahia Finance role, analytics generation needs Casas Bahia Analytics, carrier activation needs Casas Bahia Operations, webhook registration needs Casas Bahia Developer, and risk, instance, workflow and refund actions need Casas Bahia Manager. A user who cannot see the button's action through their role never gets past the guard. Data is isolated per company: every model that belongs to an instance is scoped by record rules, so a second company's users see nothing of yours.
Troubleshooting
Connecting and syncing
| Symptom | Cause and fix |
|---|---|
| The connection will not validate | Re-check every required field in the table above. Most failures are a mistyped API key, or a key created for a sandbox while the module points at production (or vice-versa). |
| It worked, then stopped authenticating | Casas Bahia API keys rotate every 90 days. Generate a fresh key in the seller portal and update the instance. |
| Nothing syncs even though the connection is fine | The scheduled actions are disabled at the Odoo level, or Odoo's cron worker is not running. Check Settings → Technical → Scheduled Actions and that --max-cron-threads is greater than zero. |
| Sync starts then stops part-way | Read the module's log records for that run. Rate limiting and rejected field values are the two common causes; both are logged with the platform's own error text. A single bad record no longer aborts the run — it is skipped and logged while the rest complete. |
| Orders all landed on 1 January | You are on a build older than 19.0.1.2.0, which misparsed Brazilian UTC offsets in order dates. Update the module. |
| Records import but map to the wrong Odoo values | Fix the mapping records under the module's configuration, then re-run the import. |
| Duplicated products or customers | Run the initial import once. If a first attempt half-finished, check the existing records before re-running rather than importing on top. |
Webhooks
| Symptom | Cause and fix |
|---|---|
Invalid signature response | The X-Casasbahia-Hmac-SHA256 header does not match the instance's Webhook Secret. Re-copy the secret into the instance record — both ends must be byte-identical. |
Instance not found response | The X-Casasbahia-Shop-Domain header does not match any instance's Shop URL. Check the spelling of the shop domain on the instance. |
| Notifications arrive but nothing changes in Odoo | The subscription's Auto Process switch is off — the notification is recorded on the subscription, and applying it is waiting for you to switch it on. |
Version history
| Odoo version | Version you download today |
|---|---|
| 17.0 | 17.0.1.1.0 |
| 18.0 | 18.0.1.1.0 |
| 19.0 | 19.0.1.2.1 |
Recent 19.0 changes worth knowing about: 19.0.1.2.1 fixed order risk assessment (creating a risk record no longer crashes) and made workflow buttons check the user's role before acting. 19.0.1.2.0 was a large correctness release — Brazilian order dates parse correctly, payouts actually import with their transaction ledger and optional bank-statement creation, stock levels import and export for real, the operations wizard's date/ID/skip/image options all work, product images download during catalog import, imported orders can auto-confirm/invoice/post from the instance settings, webhook subscriptions honour Auto Process and their create/update/archive switches, and the dashboard no longer lets one user's date filter overwrite another's. 19.0.1.1.0 removed the licence-client dependency entirely — the module runs standalone with no activation.
Your installed version is shown in Apps.