Order and Sales Flow

• Order import by create date, update date, or specific marketplace order.
• Customer, invoice, and shipping partner creation from Mirakl payloads.
• Marketplace status, provision, channel, and delivery metadata on the Odoo sales order.
• Credit-note import and duplicate shipping-line cleanup helpers.

Catalog and Listings

• Listing and offer import with SKU filters, stock-only mode, and only-new-product mode.
• Optional update of existing Odoo products and prices during listing import.
• Attribute, category, and value-list synchronization for Mirakl catalog compliance.
• Product merge workflows and mapping support for imported marketplace items.

Shipping and Invoicing

• Inventory export from Odoo to Mirakl.
• Tracking export with central Mirakl carrier configuration and tracking URLs.
• Shipping watchdog automation for completed pickings that still need confirmation.
• Optional invoice PDF upload when shipments are sent to Mirakl.

Refunds and Support

• Refund payload generation from Odoo credit notes and transmission to Mirakl.
• Remote refund IDs, timestamps, states, and error handling stored in Odoo.
• Mirakl inbox synchronization into Odoo Helpdesk with attachments and replies.
• Ticket-side order cancellation and delivery visibility for support teams.

Order Acceptance (OR21)

• Mirakl: Annehmen and Mirakl: Ablehnen buttons on the sales order header.
• Visible automatically while the Mirakl order is in WAITING_ACCEPTANCE.
• Sends per-line decisions to PUT /api/orders/{order_id}/accept.
• Local mirakl_acceptance_state mirror with timestamp.

Incident Management

• Incident öffnen and Incident schließen buttons on shipped Mirakl orders.
• Calls POST and DELETE /api/orders/{order_id}/incident.
• Protects the seller from auto-refund timeouts while a claim is open.
• Stores open/closed state and timestamps on the sales order.

Customer Debit (PA01) and Payouts

• Mirakl-Payment-Modus toggle on the marketplace instance.
• PA01: Customer Debit button on customer invoices linked to a Mirakl sales order.
• Optional cron Mirakl: Customer Debit Confirmation (PA01) for paid invoices.
• Payouts ziehen pulls Mirakl payment history and self-billing PDFs as ir.attachment.

Live Webhooks

• Per-instance endpoint /mirakl/webhook/<int:instance_id>.
• HMAC-SHA256 signature verification with per-instance secret.
• Dispatches ORDER_CREATED, ORDER_STATE_CHANGED, ORDER_REFUSED, MESSAGE_RECEIVED, REFUND_CREATED.
• Auto-computed webhook URL on the instance form for one-click copy.

Drift & Offer-Diff

• Configurable stock-drift threshold and on-demand Drift jetzt prüfen button.
• Reverse-reads GET /api/offers in pages of 100 entries.
• Reports stock drift, orphan offers (Mirakl-only), and missing offers (Odoo-only).
• Optional cron Mirakl: Stock & Offer Drift Check every six hours.

Discount Handling & Tests

• Translates per-line promotions arrays into Odoo discount percentages.
• Falls back to top-level order_discount aggregate spread across non-shipping lines.
• Ships a tests/ package with a Mirakl-aware mock for _send_mirakl_request.
• Tagged tests for selective runs: mirakl_request, mirakl_webhook, mirakl_offer_diff, mirakl_stock_drift, mirakl_order_accept, mirakl_sale_order.

Master Data & Catalog

• GET /api/account
• GET /api/channels, /api/hierarchies, /api/reasons
• GET /api/shipping/carriers, /api/shipping/zones, /api/shipping/logistic_classes
• GET /api/offers/states, /api/products/attributes
• POST/GET /api/products/imports, /api/offers, /api/offers/imports, /api/offers/stock/imports

Orders & Fulfillment

• GET /api/orders, /api/orders/documents
• PUT /api/orders/{id}/cancel, /api/orders/{id}/tracking
• POST /api/orders/refund
• PUT /api/orders/{id}/accept (new)
• POST/DELETE /api/orders/{id}/incident (new)

Payments & Self-Billing

• GET /api/sellerpayment/transactions_logs
• POST /api/payment/debit (new)
• GET /api/payment/payments_history (new)
• GET /api/payment/payment_documents/{id}/download (new)

Helpdesk Inbox

• GET /api/inbox/threads
• GET /api/inbox/threads/{id}
• POST /api/inbox/threads/{id}/message
• GET /api/inbox/threads/{id}/download

Instance Configuration

Import Operations

Dashboard

Orders

Queue

Configuration and Mapping

Listings

Credit Notes

Helpdesk

Endpoint

• URL: <your-odoo-base-url>/mirakl/webhook/<int:instance_id>
• Method: POST
• Content type: application/json
• Public route, no Odoo session required.

Signature

• Header: X-Mirakl-Signature or X-Hub-Signature-256.
• Scheme: HMAC-SHA256 of the raw request body using the per-instance secret.
• Accepted formats: <hex> or sha256=<hex>.
• Failures return 401; transient processing errors return 202 to avoid retry storms.

mk.instance

• mirakl_webhook_enabled (Boolean) - master switch for the inbound webhook endpoint.
• mirakl_webhook_secret (Char, password) - HMAC-SHA256 secret shared with Mirakl.
• mirakl_webhook_url_display (Char, computed) - public webhook URL for one-click copy.
• mirakl_drift_threshold (Integer, default 1) - drift below this delta is ignored.
• mirakl_drift_last_run / mirakl_drift_last_summary - last sweep timestamp and result.
• mirakl_payment_self_managed (Boolean) - PA01 mode toggle.
• mirakl_last_payout_pull (Datetime, readonly) - last successful payout-history fetch.

sale.order

• mirakl_acceptance_state (Selection) - pending / accepted / refused.
• mirakl_acceptance_sent_at - when OR21 was transmitted.
• mirakl_acceptance_can_decide (computed) - drives the OR21 button visibility.
• mirakl_incident_open / mirakl_incident_opened_at - incident state and timestamp.
• mirakl_can_open_incident (computed) - true when order is shipped and no incident is open.

account.move

• mirakl_customer_debit_sent (Boolean, readonly) - true after successful PA01 call.
• mirakl_customer_debit_sent_at - PA01 timestamp.

Webhook Event Routing

• ORDER_CREATED / ORDER_STATE_CHANGED / ORDER_REFUSED re-import the order via sale.order.mirakl_import_single_order.
• MESSAGE_RECEIVED calls the helpdesk thread sync.
• REFUND_CREATED aliases to the order handler.
• Response codes: 200 ok, 401 bad signature, 403 webhook off, 404 instance unknown, 400 bad JSON, 202 on internal error (no retry storm).

Drift Detector Internals

• Pages GET /api/offers with max=100; loop ends when a page returns less than 100.
• Multi-pack offers translate free_qty through mirakl_offer_product_qty before comparison.
• Pure helper _mirakl_filter_stock_drift is exposed for unit-testing without network calls.
• Cron catches exceptions per instance; one misconfigured shop cannot break the sweep.

Refuse Reason Fallback

• Resolves in order: mirakl_default_refuse_reason_code, mirakl_default_cancel_reason_code, mirakl_default_refund_reason_code.
• If none is set, the refuse button raises UserError.
• Per-line decisions with mixed accept/refuse - call _mirakl_send_order_acceptance directly.

Incident Payload

• Open: POST /api/orders/<id>/incident with {"order_lines":[{"order_line_id":"...","reason_code":"INCIDENT_OPEN"}]}.
• Close: DELETE /api/orders/<id>/incident?order_line_ids=L1,L2,....
• While open, Mirakl pauses auto-refund timeouts on the order.

PA01 Cron Criteria

• move_type = out_invoice AND state = posted AND mirakl_sale_order_id set.
• mirakl_customer_debit_sent is False.
• payment_state in (paid, in_payment, partial).
• Linked instance has mirakl_payment_self_managed = True.

Payout PDF Storage

• Incremental: each pull uses start_date = mirakl_last_payout_pull.
• Download via response_mode='raw' to bypass JSON parsing.
• Stored as ir.attachment with res_model = "mk.instance", name mirakl_payment_<id>.pdf.
• Surfaces in the chatter of the marketplace instance.

Discount Maths

• Per-line: (sum(promotions[].amount) / base_total) * 100, clamped to [0, 100].
• Only discount is touched; price_unit stays at the Mirakl original.
• Global fallback only when no per-line promotions exist; spread over non-shipping lines.
• Writes use _marketplace_silent_sync_context() to avoid echoing changes back to Mirakl.

Test Mock Patterns

• Route table: mock_mirakl({(method, path_substring): response}).
• Single response: mock_mirakl_response(env, payload).
• Base class MiraklTestCase provides self.instance with realistic credentials.
• Tags allow selective runs: --test-tags mirakl_request etc.