Bagisto Connector

Overview

The connector keeps Odoo and Bagisto in sync over the Bagisto Admin REST API (the bagisto/rest-api package). It covers:

• Products — import Bagisto products into Odoo product templates (optionally with stock, images, categories and tax group), and export Odoo product changes back to the store.

• Customers — import Bagisto customers (and their billing/shipping addresses) into Odoo contacts.

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

• Refunds — optionally discover Bagisto order slips (credit notes) attached to an order and create matching draft customer credit notes in Odoo.

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

Bagisto returns flat, already-resolved rows and prices in decimal major units, so no currency conversion is needed. 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.

• Bagisto: a Bagisto store with the official bagisto/rest-api package installed and the Admin REST API enabled. Bagisto must be reachable from the Odoo server.

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

• Odoo access: any internal user can use the connector screens. Bagisto credentials are stored in system-only fields, so only the Settings / Administration user can read or change the admin password or bearer token.

• 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

1. Copy bambooforge_bagisto_connector into your Odoo addons path.

2. Restart the Odoo service.

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

No Bagisto store is required to evaluate the connector: a mock Bagisto Admin REST API 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. Point an instance's Base URL at <your-odoo>/bagisto/mock_api with auth type Admin Email + Password (any email/password) to try it.

Step 1 — Obtain a Bagisto Admin API token (Sanctum)

The connector talks to the Bagisto Admin REST API, which authenticates with a Laravel Sanctum bearer token. You have two ways to provide it.

Option A — let Odoo log in for you (recommended). Give the connector a Bagisto admin email and password. On connect it calls POST /api/v1/admin/login with {email, password, device_name}; Bagisto returns a Sanctum token at the top-level token key, and the connector sends it as Authorization: Bearer <token> on every request. The token is cached and automatically refreshed if the store returns 401.

To prepare this in Bagisto:

1. Make sure the bagisto/rest-api package is installed and the Admin REST API is enabled.

2. Use an existing admin account (or create one under Settings ▸ Users) that has permission to read products, customers and orders.

3. Note its email and password — you will enter them in Odoo in Step 2.

Option B — paste a pre-issued token. If you already have a Sanctum token (for example one minted by an automation account), you can paste it directly. To mint one manually, call the login endpoint once, e.g.:

curl -X POST https://store.example.com/api/v1/admin/login \
     -H "Accept: application/json" \
     -d "email=admin@example.com" \
     -d "password=YOUR_PASSWORD" \
     -d "device_name=odoo"

Copy the token value from the JSON response. In Odoo, choose auth type Bearer Token and paste it.

Step 2 — Create the connection in Odoo

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

Key fields:

Then click Test Connection. A green Connected state means the credentials and URL are correct. The first successful connection also seeds the default order-state mapping rows. 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 solution pack (Catalog Only, B2C Full Sync, B2B Order-First, Retail Starter), seed default field mappings and starter flows, and apply a recommended safety profile 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 Bagisto 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, Import Refunds). This enqueues jobs; it does not block the UI.

2. Jobs are processed by the Bagisto 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 Bagisto reference so re-imports update the same record instead of duplicating it.

Order status mapping

Bagisto exposes a string order status on every order (pending, pending_payment, processing, completed, canceled, closed, fraud, plus any shop-specific custom ones). Under Configuration ▸ Order State Mappings each instance gets a default table 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 shop introduces (use the exact Bagisto status string).

Field mapping & customization

• Field Mappings (Configuration) map Bagisto 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 Bagisto fields per resource. Run Schema Introspection on the instance to refresh it from your live store (it falls back to the bundled sample if the store is unreachable).

• Stock / images / taxes / refunds 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 — name-based, never auto-creates a tax), Sync refunds (and Auto-post refund). They are off by default; turn on only what you need.

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): point your Bagisto store's webhook/event delivery at:

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

• Secret: the instance Webhook Secret (admin-only field on the instance).

The webhook is enabled per instance via the Webhook Enabled toggle (on by default). Each delivery must carry an HMAC-SHA256 signature over the raw body in the X-Bagisto-Signature header; Odoo verifies it and rejects anything without a valid signature. The signed body must include a fresh emitted_at timestamp (within 15 minutes past / 5 minutes future), and each signature is accepted only once, so captured requests cannot be replayed. Verified deliveries enqueue a safe import (or a delete, for delete events). Without webhooks the scheduled reconciliation still keeps data current.

Safety features

• Dry-run mode — simulate writes and review Validation Results before going live (Dry-run field, ON by default).

• Business validation profiles — Minimal / Standard / Strict gate risky writes (Business validation profile field).

• Safety profiles — Conservative / Balanced / Aggressive apply a coherent set of dry-run, delete-strategy and batch-size defaults in one click.

• 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 and no blocking validation issues remain.

• Rollback snapshots — when enabled (Rollback 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.

• Admin-only credentials — admin password, bearer token and webhook secret live in base.group_system fields, hidden from ordinary internal users.

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 connector targets the Bagisto Admin REST API (the bagisto/rest-api package). Validate your exact build with the bundled mock first.

Do I need Bagisto installed to evaluate it? No. A mock Bagisto Admin REST API ships inside, so you can install, explore and demo the full import flow before connecting a real store — point the Base URL at <your-odoo>/bagisto/mock_api.

How does authentication work? Bagisto uses a Laravel Sanctum bearer token. Either let the connector log in for you (it calls POST /api/v1/admin/login with your admin email/password and caches the returned token), or paste a pre-issued token and choose Bearer Token auth. The token is refreshed automatically on 401.

How does real-time sync work? Point your store's webhook delivery at /bagisto/webhook with the shared secret; Odoo verifies the HMAC-SHA256 signature, rejects stale or replayed deliveries, and enqueues a safe import. Without it, scheduled reconciliation keeps things in sync.

Are prices and currency converted? No conversion is needed: Bagisto returns prices in decimal major units and the connector reads them as-is.

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.

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, customers, orders and order slips (refunds) from your store and writes the corresponding Odoo records. It can also export product changes back to Bagisto. Credentials and the webhook secret are stored in admin-only fields.

• In scope today: product/customer/order import, product export, order-status mapping, refund discovery, 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. Updates track the supported Odoo 18 / Bagisto Admin REST API 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