draft: [16.0][ADD] connector_amazon_spapi 2

connector/tests/test_mapper.py

@@ -679,7 +679,11 @@ class MyMapper(Component):
 
         self._build_components(MyMapper)
 
-        partner = self.env.ref("base.res_partner_address_4")
+        # Create records instead of relying on demo data
+        parent = self.env["res.partner"].create({"name": "Deco Addict"})
+        partner = self.env["res.partner"].create(
+            {"name": "Test Child", "parent_id": parent.id}
+        )
         mapper = self.comp_registry["my.mapper"](self.work)
         map_record = mapper.map_record(partner)
         expected = {"parent_name": "Deco Addict"}

connector_amazon_spapi/README.rst

@@ -0,0 +1,99 @@
+=======================
+Amazon SP-API Connector
+=======================
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:PLACEHOLDER_DIGEST
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
+   :target: https://www.gnu.org/licenses/lgpl-3.0-standalone.html
+   :alt: License: LGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fconnector-lightgray.png?logo=github
+    :target: https://github.com/OCA/connector/tree/16.0/connector_amazon_spapi
+    :alt: OCA/connector
+
+|badge1| |badge2| |badge3|
+
+Amazon Seller Central (SP-API) integration for Odoo 16.0, providing automated order import,
+inventory synchronization, and pricing management following OCA Connector patterns.
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Configuration
+=============
+
+To configure this module, you need to:
+
+#. Go to Connectors > Amazon > Backends
+#. Create a new backend with your SP-API credentials:
+
+   - LWA Client ID
+   - LWA Client Secret
+   - LWA Refresh Token
+   - AWS Role ARN (optional for certain API operations)
+
+#. Create Marketplace records for each Amazon marketplace you sell in
+#. Create Shop records linking marketplaces to your backend
+
+Usage
+=====
+
+Order Import
+------------
+
+#. Navigate to Connectors > Amazon > Shops
+#. Click "Sync Orders" on a shop record
+#. Orders are fetched asynchronously via queue jobs
+#. Check Connectors > Queue > Jobs to monitor progress
+
+Stock & Price Sync
+------------------
+
+Stock and price synchronization features are planned for future releases.
+See the TESTING_GUIDE.md for technical details on the implementation roadmap.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/connector/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/connector/issues/new?body=module:%20connector_amazon_spapi%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* Odoo Community Association (OCA)
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+This module is part of the `OCA/connector <https://github.com/OCA/connector/tree/16.0/connector_amazon_spapi>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

connector_amazon_spapi/README_IMPLEMENTATION.md

@@ -0,0 +1,232 @@
+# Amazon SP-API Connector - Implementation Guide
+
+## Overview
+
+The Amazon SP-API connector has been successfully scaffolded and installed with core
+SP-API integration functionality.
+
+## What's Been Implemented
+
+### 1. Backend Model (`amazon.backend`)
+
+**SP-API Authentication:**
+
+- `_refresh_access_token()`: Refreshes LWA access token using refresh token
+- `_get_access_token()`: Returns valid access token, auto-refreshing if expired
+- `_call_sp_api()`: Makes authenticated HTTP requests to Amazon SP-API endpoints
+- `action_test_connection()`: Tests API connection by fetching marketplace
+  participations
+
+**Credential Fields:**
+
+- `seller_id`: Amazon Seller ID
+- `region`: NA/EU/FE region selection
+- `lwa_client_id`, `lwa_client_secret`, `lwa_refresh_token`: LWA credentials
+- `aws_role_arn`, `aws_external_id`: AWS IAM role credentials (optional)
+- `endpoint`: Custom API endpoint (auto-set based on region)
+- `access_token`, `token_expires_at`: Cached access token
+
+### 2. Shop Model (`amazon.shop`)
+
+**Order Synchronization:**
+
+- `action_sync_orders()`: Queues background job for order sync
+- `sync_orders()`: Fetches orders from SP-API Orders endpoint
+  - Uses `last_order_sync` timestamp or lookback days
+  - Filters by marketplace and date range
+  - Creates/updates order bindings via `amazon.sale.order`
+
+**Stock Management:**
+
+- `action_push_stock()`: Queues background job for stock push
+- `push_stock()`: Placeholder for Feeds API integration (TODO)
+
+**Configuration Fields:**
+
+- `marketplace_id`: Target Amazon marketplace
+- `import_orders`, `sync_stock`, `sync_price`: Feature toggles
+- `include_afn`: Import Amazon-fulfilled orders
+- `stock_policy`: Free vs forecast quantity
+- `last_order_sync`: Last successful order sync timestamp
+- `order_sync_lookback_days`: Default lookback period
+
+### 3. Order Models (`amazon.sale.order`, `amazon.sale.order.line`)
+
+**Order Binding:**
+
+- Uses `external.binding` pattern with `_inherits` for `sale.order`
+- `_create_or_update_from_amazon()`: Creates/updates Odoo orders from Amazon API data
+- `_sync_order_lines()`: Fetches and imports order items
+- `_get_or_create_partner()`: Partner matching logic (placeholder)
+
+**Order Line Binding:**
+
+- `_create_or_update_from_amazon()`: Creates/updates order lines from Amazon items
+- `_get_product_by_sku()`: Maps Amazon SKU to Odoo products (placeholder)
+
+**Amazon-Specific Fields:**
+
+- `external_id` (AmazonOrderId), `purchase_date`, `last_update_date`
+- `fulfillment_channel` (AFN/MFN), `status` (OrderStatus)
+- `seller_sku`, `product_binding_id`
+
+## Usage Guide
+
+### Step 1: Configure Backend
+
+1. Navigate to **Connectors > Amazon SP-API > Backends**
+2. Create a new backend record:
+
+   - **Name**: Your backend name (e.g., "Amazon US")
+   - **Seller ID**: Your Amazon Seller ID
+   - **Region**: Select NA, EU, or FE
+   - **LWA Client ID**: From Amazon Developer Console
+   - **LWA Client Secret**: From Amazon Developer Console
+   - **LWA Refresh Token**: Generated via authorization flow
+   - **Company**: Select your company
+   - **Warehouse**: Default warehouse for orders
+   - **Test Mode**: Enable for testing (shows additional options)
+   - **Read-Only Mode**: Enable to test without writing to Amazon (see below)
+
+3. Save and click **Test Connection** button
+   - Should display success message with marketplace count
+   - If error, check credentials and endpoint configuration
+
+**Testing Mode**: For safe testing and verification, enable both **Test Mode** and
+**Read-Only Mode**. This allows you to verify product mappings, order imports, and
+competitive pricing without actually pushing stock updates or shipment tracking to
+Amazon. See [READ_ONLY_MODE.md](README_READ_ONLY_MODE.md) for details.
+
+### Step 2: Configure Shops
+
+1. Navigate to **Connectors > Amazon SP-API > Shops**
+2. Create shop records (one per marketplace):
+   - **Name**: Shop name (e.g., "Amazon.com Shop")
+   - **Backend**: Select your backend
+   - **Marketplace**: Select target marketplace (e.g., ATVPDKIKX0DER for amazon.com)
+   - **Import Orders**: Enable to sync orders
+   - **Sync Stock**: Enable to push inventory
+   - **Warehouse**: Override default warehouse if needed
+   - **Pricelist**: Select pricelist for Amazon prices
+
+### Step 3: Sync Orders
+
+1. Open a shop record
+2. Click **Sync Orders** button
+
+   - Queues background job via `queue_job`
+   - Job runs `sync_orders()` method asynchronously
+   - Progress tracked via **Queue > Jobs** menu
+
+3. Monitor sync:
+   - Check **Last Order Sync** timestamp on shop
+   - View created orders in **Sales > Orders**
+   - Each order linked to `amazon.sale.order` binding
+
+### Step 4: Review Imported Orders
+
+1. Navigate to **Sales > Orders**
+2. Filter by date or customer
+3. Each Amazon order:
+   - Linked to `amazon.sale.order` binding record
+   - Contains Amazon Order ID in binding
+   - Order lines mapped to products via SKU
+
+## Architecture Notes
+
+### Background Jobs
+
+The connector uses `queue_job` with the `.with_delay()` pattern:
+
+```python
+# Queue a job
+shop.with_delay().sync_orders()
+
+# Job executes asynchronously
+# Monitor in: Queue > Jobs menu
+```
+
+### External Binding Pattern
+
+Orders use the `external.binding` pattern:
+
+```python
+class AmazonSaleOrder(models.Model):
+    _name = "amazon.sale.order"
+    _inherit = "external.binding"
+    _inherits = {"sale.order": "odoo_id"}
+
+    odoo_id = fields.Many2one("sale.order", required=True, ondelete="cascade")
+    external_id = fields.Char()  # AmazonOrderId
+```
+
+This creates:
+
+- 1 `sale.order` record (standard Odoo order)
+- 1 `amazon.sale.order` binding (Amazon-specific data)
+- Linked via `odoo_id` field
+
+### API Rate Limits
+
+Amazon SP-API has rate limits per endpoint:
+
+- Orders API: 0.0167 requests/second (1 per minute)
+- Use background jobs to respect limits
+- Implement retry logic for throttling errors
+
+## TODO / Future Enhancements
+
+### Product Synchronization
+
+- Implement product catalog import via Catalog Items API
+- Map Amazon ASINs to Odoo products
+- Sync product attributes, images, descriptions
+
+### Stock Push (Feeds API)
+
+- Build inventory feed XML
+- Submit via `/feeds/2021-06-30/feeds`
+- Poll feed processing status
+- Handle feed result reports
+
+### Price Push
+
+- Implement pricing feed submission
+- Support competitive pricing rules
+- Handle bulk price updates
+
+### Partner Matching
+
+- Enhance `_get_or_create_partner()` logic
+- Match by email, phone, or address
+- Create new partners for unknown buyers
+
+### Error Handling
+
+- Implement retry mechanism for API errors
+- Log failed syncs for debugging
+- Email notifications for critical failures
+
+### Advanced Features
+
+- Fulfillment (FBA) order handling
+- Returns and refunds via RMA API
+- Multi-currency support
+- Tax calculation
+
+## API Documentation
+
+- **SP-API Developer Guide**: https://developer-docs.amazon.com/sp-api/
+- **Orders API**: https://developer-docs.amazon.com/sp-api/docs/orders-api-v0-reference
+- **Feeds API**: https://developer-docs.amazon.com/sp-api/docs/feeds-api-reference
+- **Catalog Items API**:
+  https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v2020-12-01-reference
+
+## Support
+
+For issues or questions:
+
+1. Check Odoo logs: `invoke logs`
+2. Review background jobs: **Queue > Jobs**
+3. Verify API credentials and permissions
+4. Check Amazon Seller Central for account status