146 lines
7.1 KiB
Markdown
146 lines
7.1 KiB
Markdown
# Dine360 Social Commerce Integration for Odoo 17
|
|
|
|
[](https://www.odoo.com/)
|
|
[](https://www.gnu.org/licenses/lgpl-3.0.html)
|
|
[](https://developers.facebook.com/)
|
|
[](https://developers.facebook.com/docs/whatsapp/cloud-api)
|
|
|
|
A production-ready social commerce integration suite for **Odoo 17 eCommerce**, connecting your store with:
|
|
1. **Meta / Facebook Commerce Catalog** (Graph API v19.0 Batch Sync & RSS 2.0 XML / JSON Scheduled Data Feed)
|
|
2. **Instagram Shopping** (Product tagging linking directly to canonical Odoo eCommerce product pages and checkout)
|
|
3. **WhatsApp Business Platform / Cloud API** (Customer inquiries, dynamic product inquiry pre-fills, automated order notifications with deduplication, and inbound chat history)
|
|
|
|
---
|
|
|
|
## Authoritative Architecture Rule
|
|
|
|
Odoo remains the **sole single source of truth** for:
|
|
* **Products & Variants**: Attributes, images, descriptions, barcodes.
|
|
* **Pricing**: Currency, list price, taxes, and promotional pricelists.
|
|
* **Inventory**: Stock availability, warehouse quant movements.
|
|
* **Customers**: Contact details, delivery addresses, communication logs.
|
|
* **Orders**: Order states (`draft` → `sent` → `sale` → `done` / `cancel`), delivery tracking, invoices.
|
|
|
|
All external API calls to Meta and WhatsApp are **asynchronous and non-blocking**. Network latency or third-party API downtime will never disrupt Odoo eCommerce checkout, POS, or inventory operations.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### 1. Meta Commerce Catalog Sync
|
|
* **Real-Time Queue**: Auto-enqueues sync events whenever a product's price, stock, variant, or publication status changes.
|
|
* **Batch Graph API v19.0 Client**: Sends up to 5,000 items per batch request to Meta's `/items_batch` endpoint.
|
|
* **Scheduled Data Feed**:
|
|
* RSS 2.0 XML Product Feed: `/social/meta/catalog_feed.xml`
|
|
* JSON Product Feed: `/social/meta/catalog_feed.json`
|
|
* **Product Type Awareness**: Automatically exports consumables (`consu`) and services (`service`) as `in stock`, while accurately reflecting warehouse inventory for storable products (`product`).
|
|
|
|
### 2. Instagram Shopping
|
|
* Canonical URLs generated from Odoo's website configuration for seamless shopping tags.
|
|
* Google Product Category (`g:google_product_category`), condition, and availability standard attributes supported.
|
|
|
|
### 3. WhatsApp Business Cloud API Integration
|
|
* **Automated Order Lifecycle Notifications**:
|
|
* **Order Confirmed**: Triggered upon sale order confirmation / online checkout payment.
|
|
* **Order In Preparation**: Triggered during kitchen/warehouse order processing.
|
|
* **Order Shipped**: Triggered upon validation of stock delivery picking.
|
|
* **Order Delivered**: Triggered upon completion of customer delivery.
|
|
* **Deduplication Safeguard**: Automatically suppresses duplicate messages if orders or shipments are re-saved.
|
|
* **Bi-Directional Webhook (`/social/whatsapp/webhook`)**:
|
|
* `GET`: Meta challenge verification with token authentication.
|
|
* `POST`: Inbound message listener with HMAC-SHA256 signature verification (`X-Hub-Signature-256`).
|
|
* **Customer Chat & Inquiries**:
|
|
* Incoming customer WhatsApp messages are logged in Odoo.
|
|
* Smart sender phone matching against `phone_sanitized` and normalized regex numbers.
|
|
* Automatic regex extraction of order references (e.g., `SO00123`).
|
|
|
|
### 4. Storefront UI Widgets
|
|
* **Floating WhatsApp Button**: Circular pulsating button fixed to the bottom-right corner of public storefront pages with responsive hover tooltip.
|
|
* **Product Page Inquiry Button**: Positioned beside *Add to Cart* on `/shop` product pages. Pre-fills message with product title and canonical store link.
|
|
* **Dynamic Variant Tracking**: Variant attribute selections and quantity changes dynamically update the WhatsApp chat URL in real time.
|
|
|
|
### 5. Executive Command Center Dashboard
|
|
* Real-time metrics: Catalog Sync Count, WhatsApp Notification Stats, Customer Inquiry Counter.
|
|
* Live Action Buttons:
|
|
* **Test Meta Connection**
|
|
* **Sync Products to Meta**
|
|
* **Test WhatsApp API**
|
|
* **Retry Failed Operations**
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
dine360-social-commerce/
|
|
├── addons/
|
|
│ └── dine360_meta_social/ # Core Odoo 17 Custom Module
|
|
│ ├── __manifest__.py # Dependencies: base, web, website, website_sale, sale, stock, phone_validation, stock_delivery
|
|
│ ├── controllers/
|
|
│ │ ├── meta_feed.py # XML & JSON Catalog Feeds
|
|
│ │ └── whatsapp_webhook.py# Webhook challenge & event receiver
|
|
│ ├── models/ # Business logic & API clients
|
|
│ │ ├── product_product.py
|
|
│ │ ├── product_template.py
|
|
│ │ ├── res_company.py
|
|
│ │ ├── res_config_settings.py
|
|
│ │ ├── sale_order.py
|
|
│ │ ├── social_commerce_dashboard.py
|
|
│ │ ├── social_meta_catalog.py
|
|
│ │ ├── social_meta_sync_queue.py
|
|
│ │ ├── social_whatsapp_api.py
|
|
│ │ ├── social_whatsapp_message.py
|
|
│ │ ├── social_whatsapp_notification.py
|
|
│ │ ├── social_whatsapp_template.py
|
|
│ │ ├── stock_picking.py
|
|
│ │ └── website.py
|
|
│ ├── views/ # Backend views, menus & dashboards
|
|
│ ├── static/ # CSS animations & frontend JS
|
|
│ ├── data/ # Crons & default template data
|
|
│ ├── security/ # Access control lists & user groups
|
|
│ └── tests/ # Unit & integration test suite (12/12 passing)
|
|
├── docker-compose.yml # Local deployment setup (Odoo 17 + PostgreSQL 15)
|
|
├── HANDOVER.md # Detailed architectural handover & bug fix notes
|
|
├── SOCIAL_COMMERCE_SETUP.md # Step-by-step credentials & configuration runbook
|
|
└── SOCIAL_COMMERCE_TEST_REPORT.md # Test matrix & verification logs
|
|
```
|
|
|
|
---
|
|
|
|
## Quickstart (Docker)
|
|
|
|
1. **Start Environment**:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
2. **Access Odoo**:
|
|
* URL: `http://localhost:10050`
|
|
* Storefront: `http://localhost:10050/shop`
|
|
3. **Install / Upgrade Module**:
|
|
```bash
|
|
docker exec -it odoo_client50 odoo -d Antalya -u dine360_meta_social --stop-after-init
|
|
```
|
|
|
|
---
|
|
|
|
## Running Automated Tests
|
|
|
|
Run the built-in unit and integration test suite:
|
|
```bash
|
|
docker exec -it odoo_client50 odoo -d Antalya --test-enable --test-tags /dine360_meta_social --stop-after-init
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
* [Project Handover & Architecture](HANDOVER.md)
|
|
* [Production Setup & Credentials Guide](SOCIAL_COMMERCE_SETUP.md)
|
|
* [Quality Assurance & Test Report](SOCIAL_COMMERCE_TEST_REPORT.md)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This software is licensed under the [LGPL-3.0 License](https://www.gnu.org/licenses/lgpl-3.0.html).
|