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.2.1.0, 18.0 → 18.0.2.1.0, 19.0 → 19.0.2.1.0 |
| 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.
The delivery URL is registered at the marketplace, not from Odoo. Casas Bahia publishes no webhook-subscription API, so the connector cannot create the subscription for you. Point the marketplace at the endpoint above (order, product, customer, refund) in the Casas Bahia seller portal, then set the subscription record here to Active. Until you do, the record reads Awaiting Portal Setup, and the module tells you so rather than reporting a live subscription it never created. Order sync keeps running on its schedule meanwhile, so no data is lost while the webhook is being set up.
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.2.1.0 |
| 18.0 | 18.0.2.1.0 |
| 19.0 | 19.0.2.1.0 |
Recent changes worth knowing about: 19.0.2.1.0 (also 18.0.2.1.0 and 17.0.2.1.0) rebuilt the whole API layer against the marketplace's published seller API. The previous layer called 39 routes the platform does not publish and used the wrong HTTP verb on 8 more, so several features could never have worked against the real API - they failed on the first call. Every route is now one the platform documents, and each feature was re-pointed at the route that genuinely carries it: documents attach to their order, refunds are issued per order line against a reason code, withdrawing a product withdraws your offer (the catalogue entry belongs to the marketplace), incidents are read as orders with an open incident and resolved per line, shops come from your shop roles, payouts from the billing cycles, and reports are built from the order list, the shop statistics and per-order evaluations. Two things this release states plainly instead of pretending: the marketplace publishes no webhook-subscription API, so enabling a webhook now records it as Awaiting Portal Setup and shows you the URL to register in the seller portal; and there is no LGPD erasure endpoint, so the erasure action clears the data subject's personal data from your Odoo copy, logs it, and tells you the marketplace-side request goes through Casas Bahia's own channel. Product images are read (the marketplace owns them) rather than uploaded. 19.0.2.0.x added hardening against 36 known real-world failure cases and fixed the marketplace's own status words flowing into a selection field, which could roll back a whole order. 19.0.1.2.1 fixed order risk assessment and made workflow buttons check the user's role before acting. 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.