Certainly! Here is a Markdown document summarizing the entire discussion, from the basic concepts of Odoo-ABS Subscription integration to the API endpoints and the asynchronous messaging approach using MQTT and RabbitMQ:

Odoo-ABS Subscription Integration¶

Overview¶

In this integration, we explore how Odoo and ABS (Asset-Based Service) can work together to manage service plans, customer relationships, subscriptions, and payments. The Odoo Subscription model will handle time-driven payments (e.g., monthly or annual service fees), while ABS will manage the service fulfillment and trigger service-based payments upon specific milestones (e.g., service completions).

Key Objectives:¶

Odoo handles CRM, subscriptions, and invoicing for customers.
ABS handles service management, including service fulfillment, milestones, and triggering payments.
Hybrid Payment Model: Combine Odoo's built-in period-triggered payments with ABS-triggered service-based payments for comprehensive subscription management.
Use DIRAC framework messaging (via FED/BRO) to synchronize ABS-triggered events with Odoo's invoicing system.

Hybrid Payment Architecture - The Key Innovation:¶

The ABS-Odoo integration's primary value lies in its hybrid payment model that combines two complementary payment triggers:

Odoo Period-Triggered Payments (Built-in)¶

Monthly/Annual Subscription Fees - Automated recurring billing
Deposit Collection - Initial security deposits
Renewal Payments - Subscription period renewals
Final Settlement - End-of-contract payments

ABS Service-Triggered Payments (Event-driven)¶

Per-Service Usage - Payment for each battery swap, equipment rental, etc.
Milestone Payments - Payments triggered by service completion events
Overage Charges - Additional fees for exceeding quotas
Incident-Based Charges - Damage, loss, or special service fees

Unified Customer Experience¶

Single Invoice combining both period-based and service-based charges
Unified Payment Portal in Odoo showing all charges
Consistent Billing with ABS providing service event data to Odoo
Complete Audit Trail of all payment types in one system

B2C Payment-First Business Model:¶

A fundamental principle of B2C asset-based services is "Pay First, Then Serve" - payments always precede service delivery:

Payment-First Requirements:¶

Deposit Required - Customer must pay deposit before receiving any service
Pre-Paid Service Credits - Service usage must be pre-paid (e.g., monthly quota)
No Post-Service Invoicing - Never "we served, here's the invoice, please pay"
Service Blocking - ABS blocks service access when payment is overdue

Hybrid Payment Model with Payment-First:¶

Period-Triggered Payments (Odoo):
Monthly subscription fee - Pre-paid for the month
Deposit collection - Required before service activation
Renewal payments - Pre-paid for next period
Service-Triggered Payments (ABS):
Pre-paid service credits - Customer buys credits before usage
Overage charges - Additional credits required when quota exceeded
Incident charges - Pre-paid deposits for damage/loss coverage

Payment-First Flow Example:¶

1. Customer pays monthly subscription (KES 2,000) → Odoo
2. Customer pays service credits (KES 500) → Odoo  
3. ABS receives payment confirmation → Service activated
4. Customer uses service (battery swaps) → Credits deducted
5. When credits low → ABS requests additional payment → Odoo
6. Customer pays additional credits → Service continues

Entity Mapping:¶

ServicePlanTemplate = Odoo Subscription Product (the "product" definition)
ServicePlan = Odoo Subscription Account (the customer's active subscription)

ABS FSM State Management¶

Payment Cycle FSM States (Payment-First Model)¶

ABS uses a MealyFSM for payment state management with the following states: - INITIAL - Service plan created, awaiting contract signing - DEPOSIT_DUE - Contract signed, payment required before service activation - CURRENT - Deposit paid, service active and current (payment-first satisfied) - RENEWAL_DUE - Subscription period expired, renewal payment required before service continues - FINAL_DUE - Final payment due, payment required before contract completion - COMPLETE - Final payment completed, contract fulfilled

Key Principle: Service is only available when payment state is CURRENT - all other states block service access.

Service Cycle FSM States (Payment-First Model)¶

ABS uses a MealyFSM for service state management with the following states: - INITIAL - Service plan created, awaiting deposit confirmation - WAIT_BATTERY_ISSUE - Payment confirmed, customer ready to receive first battery - BATTERY_ISSUED - Battery issued to customer, service active (payment-first satisfied) - BATTERY_RETURNED - Battery returned by customer (swap or final return) - BATTERY_LOST - Battery lost or damaged while in customer possession - COMPLETE - Service completed after final battery return or settlement

Key Principle: Service delivery only occurs after payment confirmation - no service without payment.

FSM Signal Flow¶

ABS FSM outputs trigger state transitions and external notifications: - Payment Signals: DEPOSIT_REQUIRED, RENEWAL_REQUIRED, SERVICE_ACTIVATED, FINAL_PAYMENT_REQUIRED, PAYMENT_COMPLETE - Service Signals: SERVICE_READY, BATTERY_ALLOCATED, SWAP_READY, RETURN_PROCESSED, ASSET_LOST_REPORTED, SERVICE_COMPLETE

Key Concepts¶

1. Odoo Subscription Model¶

Purpose: Designed for time-triggered, recurring payments, commonly used for subscriptions where a customer is billed at fixed intervals (e.g., monthly, yearly).
Functionality:
Invoice generation for recurring payments based on fixed periods.
Subscription lifecycle management (e.g., start date, end date, renewal).
Customer portal to track subscriptions, payments, and invoices.
Use in Integration:
The Odoo Subscription model will handle basic recurring payments (e.g., monthly fee for a service like battery swap).
ABS-triggered payments (e.g., service completion) will be handled outside of Odoo's regular subscription invoicing cycle, but will be linked to the Odoo subscription record.

2. ABS (Asset-Based Service)¶

Purpose: Manages service fulfillment and service contracts using FSM-driven state management.
Functionality:
ServicePlanTemplate - Defines service offerings with billing currency and legal jurisdiction
ServicePlan - Customer's active subscription with FSM-driven state management
ServiceBundle - Collection of services (e.g., battery swap service)
ServiceState - Per-service usage tracking and quota management
PaymentAccount - Payment state and history tracking
MealyFSM - Finite state machines for payment and service cycles
AgentConfig - Delegation agent pattern for business logic execution
Use in Integration:
ABS triggers payments based on FSM state transitions (e.g., DEPOSIT_DUE → DEPOSIT_PAID)
ABS uses DIRAC messaging to notify Odoo via FED/BRO coordination
ABS maintains template-based architecture with version pinning for contract stability

Implementation Path¶

1. Odoo Subscription Setup for Period-Driven Payments¶

Create a Subscription Record in Odoo for each customer subscribing to a service plan (e.g., battery swap, maintenance).
Odoo will handle recurring payments (e.g., monthly fees) and create the associated invoices automatically.

Example Subscription Record:

{
  "partner_id": "customer_789",  // Link to the customer
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "amount_total": 200.00,  // Periodic payment amount
  "state": "active"
}

2. Hybrid Payment Integration - ABS Service-Triggered Payments¶

ABS triggers service-based payments whenever a milestone is reached (e.g., battery swap completed).
ABS sends a payment request to Odoo via DIRAC messaging, which combines with Odoo's period-triggered payments.
Odoo generates unified invoices that include both subscription fees and service-based charges.

Example Payment Request Message (ABS → Odoo):

{
  "message_type": "payment_request",
  "plan_id": "plan-nairobi-customer001-001",
  "template_id": "template-nairobi-monthly-flatfee-v1",
  "amount": 50.00,
  "currency": "KES",
  "service_id": "service-battery-swap-001",
  "customer_id": "customer-001",
  "fsm_state": "DEPOSIT_DUE",
  "timestamp": "2025-09-10T15:00:00Z"
}

Odoo generates an invoice for the service-based payment once the request is received.
After payment, ABS will be notified via an API call or message that the payment has been completed.

Example Payment Completed Message (Odoo → ABS):

{
  "message_type": "payment_completed",
  "plan_id": "plan-nairobi-customer001-001",
  "template_id": "template-nairobi-monthly-flatfee-v1",
  "payment_status": "success",
  "amount_paid": 50.00,
  "currency": "KES",
  "fsm_input": "DEPOSIT_PAID",
  "timestamp": "2025-09-10T15:30:00Z",
  "transaction_id": "T12345ABC",
  "invoice_reference": "INV-2025-001"
}

3. API Endpoints in Odoo¶

You’ll need to expose custom API endpoints in Odoo to handle the messages from ABS (for payment requests, service completion notifications, etc.). These will allow Odoo to handle the relevant business logic, such as creating invoices, updating subscription states, and responding with the appropriate status messages.

Example Odoo API Route for Payment Request:

from odoo import http
from odoo.http import request
import json

class ABSIntegrationController(http.Controller):

    @http.route('/api/abs/payment_request', type='json', auth='none', methods=['POST'])
    def handle_payment_request(self, **post):
        data = post.get('data', {})
        plan_id = data.get('plan_id')
        template_id = data.get('template_id')
        amount = data.get('amount')
        customer_id = data.get('customer_id')
        fsm_state = data.get('fsm_state')

        # Create an invoice in Odoo
        customer = request.env['res.partner'].browse(customer_id)
        subscription = request.env['sale.subscription'].search([('abs_plan_id', '=', plan_id)])
        if subscription:
            invoice = request.env['account.move'].create({
                'partner_id': customer.id,
                'move_type': 'out_invoice',
                'invoice_line_ids': [(0, 0, {
                    'product_id': subscription.product_id.id,
                    'quantity': 1,
                    'price_unit': amount,
                })],
            })
            invoice.action_post()

            return {'status': 'success', 'invoice_id': invoice.id}
        return {'status': 'failed', 'message': 'Subscription not found'}

4. DIRAC Framework Messaging Integration¶

For asynchronous communication between ABS and Odoo, the DIRAC framework provides standardized messaging through FED (Federated API) and BRO (Messaging Broker).

FED (Federated API Layer)¶

Standardized Interface: Provides unified access to ABS services through consistent API patterns
Cross-Referenced Data: Ensures data consistency between ABS and Odoo systems
Single Access Point: All ABS-Odoo interactions flow through FED for consistency and control

BRO (Messaging Broker Exchange)¶

Emit/Echo Pattern: ABS publishes events using emit/abs/service/{resource}/{id}/{event} topics
Response Tracking: Odoo responds with echo/abs/service/{resource}/{id}/{event} confirmations
MQTT-Based: Lightweight, efficient messaging optimized for real-time operations via EMQX
Message Persistence: Reliable message delivery with guaranteed processing and replay capabilities

Example DIRAC Topic Patterns:¶

# Payment request from ABS
emit/abs/service/battery_swap/plan-nairobi-customer001-001/payment_request
  → Odoo processes payment
  → echo/abs/service/battery_swap/plan-nairobi-customer001-001/payment_confirmed

# Service completion notification
emit/abs/service/battery_swap/plan-nairobi-customer001-001/service_completed
  → Odoo updates subscription
  → echo/abs/service/battery_swap/plan-nairobi-customer001-001/subscription_updated

5. Implementation Path¶

Phase 1: Basic Integration with Odoo Subscription¶

Set up Odoo Subscription for period-driven payments (e.g., monthly or yearly fees).
Create custom API endpoints in Odoo for receiving ABS-triggered events (payment requests, service completions).
ABS sends payment request messages via DIRAC FED/BRO messaging.
Odoo generates invoices based on these payment requests, and responds to ABS with payment statuses.

Phase 2: Hybrid Payment Model Implementation¶

ABS triggers service-based payments when milestones are reached (e.g., battery swap completed).
Odoo processes these payments by combining them with period-triggered payments in unified invoices.
Example Hybrid Invoice (Payment-First Model):
Period-Triggered: Monthly subscription fee (KES 2,000) - Pre-paid for next month
Service-Triggered: Additional service credits (KES 500) - Pre-paid for future usage
Total Invoice: KES 2,500 with itemized breakdown
Note: All charges are pre-paid - no post-service invoicing
Odoo subscription tracks both period-driven payments and service-based payments, providing a unified customer experience.

Scale up the DIRAC messaging system (e.g., optimize BRO broker performance and FED API throughput).
Improve reliability and error handling in the integration.
Add more complex business logic (e.g., payment retries, service milestones).
Enhance customer portal in Odoo to provide real-time visibility into both subscription status and service-based payments.

6. Conclusion¶

This approach allows you to integrate ABS-managed services with Odoo's subscription and invoicing system while keeping things flexible and scalable. The hybrid payment model combines Odoo's built-in period-triggered payments with ABS-triggered service-based payments, creating a comprehensive solution that handles both subscription fees and usage-based charges in a unified billing system.

Critical B2C Principle: The integration enforces "Pay First, Then Serve" - all payments are pre-paid and service delivery only occurs after payment confirmation, ensuring no post-service invoicing or payment collection issues.

Phase 1 involves setting up the basic subscription logic and integrating it with ABS for service-triggered payments.
Phase 2 focuses on extending the integration to track both time-based and service-based payments in Odoo.
Phase 3 involves making the solution scalable using the DIRAC framework with FED/BRO coordination.

ABS Architecture Recommendations¶

ServicePlanTemplate Integration¶

Recommendation: Map Odoo Subscription Products to ABS ServicePlanTemplates
Implementation: Store template_id in Odoo subscription records to link to ABS templates
Benefits: Enables template-based versioning and contract stability

FSM State Synchronization¶

Recommendation: Synchronize Odoo subscription states with ABS FSM states
Implementation: Map Odoo subscription status to ABS payment_state and service_state
Benefits: Ensures consistent state management across both systems

Currency and Legal Compliance¶

Recommendation: Use ABS template-level billing_currency and legal_jurisdiction
Implementation: Inherit currency from ServicePlanTemplate in ABS, pass to Odoo
Benefits: Ensures country-specific compliance and currency consistency

Delegation Agent Pattern¶

Recommendation: Use ABS delegation agent pattern for business logic execution
Implementation: Route Odoo requests through ABS AgentConfig delegation functions
Benefits: Maintains encapsulation and enables complex business rule processing

DIRAC Framework Benefits¶

Recommendation: Leverage DIRAC FED/BRO for standardized integration
Implementation: Use emit/echo patterns for reliable message delivery
Benefits: Provides audit trails, correlation tracking, and scalable messaging

If you'd like to dive into any part of the integration, such as custom API code, DIRAC messaging configuration, or scaling strategies, feel free to reach out.