--- title: "ERP Accounting Bridge & Cryptographic Webhooks Module Documentation" description: "Documentation for Account Bridge" --- ## Table of Contents 1. [Module Overview (Technical)](#1-module-overview-technical) 2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value) 3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities) 4. [Visual Interface & Form Structure](#4-visual-interface--form-structure) 5. [Architectural Flow & Double-Entry Accounting Engine](#5-architectural-flow--double-entry-accounting-engine) 6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks) 7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands) 8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration) 9. [Glossary](#9-glossary) --- ## 1. Module Overview (Technical) The **ERP Accounting Bridge & Cryptographic Webhooks** module (`public.accounting_mappings`, `public.webhook_endpoints`, and `public.webhook_logs`) bridges the operational telecom revenue engine of **Ring2All Billing** with institutional Enterprise Resource Planning (ERP) accounting platforms (such as QuickBooks Online, Xero, Odoo, SAP, and NetSuite). ### Core Components & Subsystems 1. **Chart of Accounts Mapping (`public.accounting_mappings`):** Maps internal billing transaction categories directly to standard general ledger account codes (Assets, Liabilities, Equity, Revenue, COGS, and Expenses). 2. **Double-Entry General Journal Export:** Generates balanced debit and credit journal entry exports adhering to standard GAAP and IFRS accrual accounting principles. 3. **Cryptographic Webhooks Engine (`public.webhook_endpoints`):** Dispatches real-time HTTPS webhooks signed with HMAC-SHA256 cryptographic signatures to external ERP listeners upon key financial events. ```sql -- Chart of Accounts Mapping Schema CREATE TABLE public.accounting_mappings ( id BIGSERIAL PRIMARY KEY, category VARCHAR(50) NOT NULL UNIQUE, account_code VARCHAR(50) NOT NULL, account_name VARCHAR(100) NOT NULL, description TEXT, updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); -- Cryptographic Webhooks Schema CREATE TABLE public.webhook_endpoints ( id BIGSERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT gen_random_uuid(), url VARCHAR(255) NOT NULL, secret VARCHAR(100) NOT NULL, events TEXT[] NOT NULL, is_active BOOLEAN NOT NULL DEFAULT true, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); ``` ### Cryptographic Webhook Security Specification All outbound HTTP POST payloads include an HMAC-SHA256 signature in the HTTP header: ```http POST /api/billing/webhook HTTP/1.1 Host: erp.acmetelecom.com Content-Type: application/json X-Ring2All-Signature: sha256=4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a X-Ring2All-Event: invoice.paid X-Ring2All-Timestamp: 1788806400 ``` External ERP receivers verify message integrity and authenticity by computing `hmac_sha256(payload, webhook_secret)`. --- ## 2. Module Overview (Commercial & Business Value) * **Elimination of Double-Entry Bookkeeping:** Automatically translates thousands of metered telecom micro-transactions into summarized, balanced General Journal entries, eliminating human bookkeeping errors. * **Instant Financial Closing:** Enables financial controllers to close monthly books in minutes rather than weeks through one-click CSV journal export and live webhook reconciliation. * **Zero-Trust Enterprise Security:** Cryptographic HMAC-SHA256 request signing ensures that external accounting systems only process legitimate, unaltered financial transactions originating from the authenticated billing platform. * **Real-Time Event Notification:** Financial webhooks allow downstream CRM, ERP, and payment management software to respond immediately when payments clear or accounts fall into delinquency. --- ## 3. 🎯 User Roles & Key Capabilities | User Role | Key Permissions | Core Responsibilities & Workflows | | :--- | :--- | :--- | | **Super Administrator** | Full Control & Webhook Secret Management | Configures ERP endpoints, manages HMAC signing secrets, and configures automated retry policies. | | **Chief Financial Officer / Lead Accountant** | Chart of Accounts & Journal Export | Configures general ledger account codes, audits balanced debit/credit reconciliations, and downloads monthly ERP journal exports. | | **Integration Engineer** | Webhook Debugging & Payload Inspection | Inspects HTTP response statuses in the delivery log, diagnoses endpoint timeouts, and verifies payload schema structures. | | **Financial Auditor** | Read-Only Ledger Verification | Inspects audit trails, verified delivery timestamps, and general ledger journal accuracy. | --- ## 4. Visual Interface & Form Structure ### 4.1 Chart of Accounts Configuration (Tab 1) The **Chart of Accounts** tab allows accountants to map platform revenue streams, carrier costs, and sales tax liabilities to their corporate ERP ledger codes. ![Chart of Accounts Tab](/screenshots/billing/reports/financial/accounting/accounting-chart.png) ### 4.2 Cryptographic Webhooks & Delivery Logs (Tab 2) The **Webhooks** tab manages active HTTPS webhook endpoints, secret keys, subscribed events, and an interactive real-time inspection log tracking HTTP response codes and retry counts. ![Cryptographic Webhooks Tab](/screenshots/billing/reports/financial/accounting/accounting-webhooks.png) ### 4.3 General Journal CSV Export Modal Operators can export balanced general ledger journal entries for any historical date range, configured specifically for import into QuickBooks, Xero, Odoo, or SAP. ![General Journal Export Modal](/screenshots/billing/reports/financial/accounting/accounting-export-modal.png) ### 4.4 Default Chart of Accounts Categories | Financial Category | Default Account Code | Default Account Name | Normal Balance | Description | | :--- | :--- | :--- | :---: | :--- | | `voice_revenue` | `4000` | Voice Usage Revenue | Credit | Metered outbound and inbound voice call usage revenue from rated CDRs. | | `subscription_revenue` | `4100` | Plan Subscription Revenue | Credit | Recurring monthly subscription fees billed for hosted PBX and trunk plans. | | `did_revenue` | `4200` | DID & Number Revenue | Credit | Recurring and setup fees collected for wholesale and retail DID numbers. | | `sales_tax_payable` | `2100` | Sales & Telecom Tax Payable | Credit | Collected municipal, state, and federal telecom taxes and regulatory fees. | | `carrier_cogs` | `5000` | Carrier Termination COGS | Debit | Direct wholesale costs incurred from terminating carrier providers. | | `customer_wallet_liability` | `2200` | Customer Prepaid Liability | Credit | Unearned customer prepaid deposits held in wallets prior to usage. | --- ## 5. Architectural Flow & Double-Entry Accounting Engine ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Billing Event (e.g. Invoice Finalized) │ └───────────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────┴────────────────────────┐ │ │ ▼ (Batch General Journal) ▼ (Real-Time Webhook) ┌───────────────────────────────────────┐ ┌───────────────────────────────────────┐ │ Double-Entry Ledger Balancing │ │ Cryptographic Signing Engine │ │ • Debit: Accounts Receivable (1200) │ │ • Generate payload JSON string │ │ • Credit: Voice Revenue (4000) │ │ • Compute HMAC-SHA256 with secret │ │ • Credit: Sales Tax Payable (2100) │ │ • Set `X-Ring2All-Signature` header │ └──────────────────┬────────────────────┘ └──────────────────┬────────────────────┘ │ │ ▼ ▼ ┌───────────────────────────────────────┐ ┌───────────────────────────────────────┐ │ Export Balanced Journal CSV │ │ HTTPS POST to External ERP Listener │ │ • Compatible with QuickBooks / Odoo │ │ • Log HTTP response status in DB │ └───────────────────────────────────────┘ └───────────────────────────────────────┘ ``` --- ## 6. Common Scenarios & Operational Playbooks ### Scenario A: Adding an Odoo ERP Webhook Listener 1. Navigate to **REPORTS / Financial Reports / Account Bridge**. 2. Select the **Cryptographic Webhooks** tab. 3. Click **Add Webhook Endpoint**. 4. Enter your ERP listener URL (e.g. `https://erp.yourcompany.com/api/v1/billing/webhook`). 5. Select target events: `invoice.created`, `invoice.paid`, and `customer.balance_depleted`. 6. Copy the generated HMAC secret key into your ERP webhook signature verifier and click **Save Endpoint**. ### Scenario B: Exporting Monthly Journal Entries for Financial Closing 1. In the **Account Bridge** module, click **Export Journal CSV** in the top action toolbar. 2. Select the **Period Start** and **Period End** dates (e.g., first and last day of the target month). 3. Click **Download Journal CSV**. The system generates a balanced double-entry spreadsheet where Total Debits equal Total Credits. --- ## 7. Troubleshooting & Diagnostic Commands ### Inspect Failed Webhook Delivery Logs ```sql SELECT l.id, e.url, l.event_type, l.response_status, l.attempts, l.created_at FROM webhook_logs l JOIN webhook_endpoints e ON e.id = l.endpoint_id WHERE l.response_status IS NULL OR l.response_status >= 400 ORDER BY l.created_at DESC LIMIT 10; ``` ### Verify Chart of Accounts Completeness ```sql SELECT category, account_code, account_name FROM accounting_mappings ORDER BY account_code ASC; ``` --- ## 8. Model Context Protocol (MCP) AI Integration The **ERP Accounting Bridge & Cryptographic Webhooks** module connects directly to the **Ring2All BSS MCP Server**, enabling financial copilots and accounting auditors to inspect chart of accounts mappings and retrieve summarized double-entry ledger totals. ### Available MCP Tools | Tool Name | Access Role | Description & Primary Function | Example Arguments | | :--- | :--- | :--- | :--- | | `get_accounting_journal_summary` | `Billing Operations` / `Admin` | Retrieves summary of double-entry general ledger journal entries and mapped accounts for finance reconciliation. | `{"startDate": "2026-09-01", "endDate": "2026-09-30"}` | ### Sample MCP Tool Execution: `get_accounting_journal_summary` #### Request Payload ```json { "name": "get_accounting_journal_summary", "arguments": { "startDate": "2026-09-01", "endDate": "2026-09-30" } } ``` #### Response Payload ```json { "period": { "startDate": "2026-09-01", "endDate": "2026-09-30" }, "totalDebits": 14520.80, "totalCredits": 14520.80, "isBalanced": true, "mappedAccountsCount": 8, "mappings": [ { "category": "voice_usage_revenue", "accountCode": "4000", "accountName": "Voice Usage Revenue" }, { "category": "carrier_cogs", "accountCode": "5000", "accountName": "Carrier Termination Expense" } ] } ``` ### Conversational AI Prompts for Copilot * *"Provide the accounting journal summary and trial balance for September 2026."* * *"Are all revenue and expense categories mapped to active General Ledger accounts?"* * *"Verify if total debits match total credits for the current billing cycle."* --- ## 9. Glossary * **Account Bridge:** The integration layer linking telecom rating transactions to institutional accounting general ledgers. * **COGS (Cost of Goods Sold):** Direct variable wholesale carrier fees incurred in delivering telephony minutes. * **Double-Entry Bookkeeping:** Accounting standard requiring every transaction to record equal and offsetting debit and credit entries. * **HMAC-SHA256:** Keyed-hash message authentication code ensuring payload integrity and origin authenticity. * **Webhook:** An automated HTTP callback triggered by an event in Ring2All Billing and dispatched to an external server. * **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.