7c929eb4dc
- Streamlined the README.md for clarity and conciseness. - Deleted outdated documentation files related to Freebit SIM management, SIM management API data flow, and various architectural guides to reduce clutter and improve maintainability. - Updated the last modified date in the README to reflect the latest changes.
46 lines
2.8 KiB
Markdown
46 lines
2.8 KiB
Markdown
# Orders & Provisioning
|
||
|
||
How customer orders are created, where they live, and how fulfillment reaches WHMCS.
|
||
|
||
## Order Creation (Customer Checkout)
|
||
|
||
- Orders are created in Salesforce using the portal pricebook. The record includes:
|
||
- AccountId (from the user’s mapping)
|
||
- Order type (Internet, SIM, VPN)
|
||
- Activation preferences (type, scheduled date, SIM/MNP details when provided)
|
||
- Address snapshot copied from the customer profile/checkout form
|
||
- Status starts at “Pending Review”
|
||
- Before creation we verify a WHMCS payment method exists and (for Internet) that WHMCS does not already have an active Internet service.
|
||
- Order items are built from the Salesforce pricebook entries for the selected SKUs.
|
||
|
||
## Fulfillment to WHMCS (Triggered by Salesforce)
|
||
|
||
- Salesforce Change Data Capture (CDC) watches for order status changes (e.g., Approved/Reactivate). When triggered, we enqueue a provisioning job.
|
||
- Fulfillment steps:
|
||
1. Set Salesforce order activation status to “Activating.”
|
||
2. Map Salesforce order items to WHMCS products and call WHMCS AddOrder to create the billing order (so invoices/subscriptions exist in WHMCS).
|
||
3. For SIM orders, call Freebit to activate SIMs when required.
|
||
4. Update Salesforce with WHMCS Order ID, activation status/results, and any error codes/messages.
|
||
5. Publish live events so the UI can update order status in real time (SSE).
|
||
- If Salesforce shows the last error code “PAYMENT_METHOD_MISSING,” provisioning is paused until the customer adds a payment method in WHMCS.
|
||
|
||
## Where Data Lives
|
||
|
||
- Salesforce: master order record, status, address snapshot, product lines.
|
||
- WHMCS: billing copy created during fulfillment (used for invoices/subscriptions).
|
||
- Freebit: only for SIM provisioning tasks.
|
||
|
||
## Freshness & Caching
|
||
|
||
- Orders and order items use CDC-driven caching (no TTL). Salesforce order/order-item change events invalidate caches immediately.
|
||
- Cache is also invalidated when we create or provision an order.
|
||
- Customers can subscribe to order event streams; UI updates without manual refresh.
|
||
|
||
## What happens on errors
|
||
|
||
- Payment method missing: fulfillment is paused; Salesforce `Activation_Error_Code__c` is set to `PAYMENT_METHOD_MISSING` and the UI shows a prompt to add a payment method.
|
||
- Validation/mapping issues (e.g., bad SKU, missing mapping): we stop and return a clear error; Salesforce gets an error code/message for traceability.
|
||
- WHMCS errors while creating the billing order: we mark fulfillment as failed, write the error back to Salesforce, and keep the Salesforce order intact (no partial WHMCS order is kept if creation fails).
|
||
- Freebit/SIM errors: logged and surfaced in the activation status; order remains in Salesforce for retry.
|
||
- Connectivity issues (Salesforce/WHMCS): we return “try again later,” do not commit partial work, and leave caches unchanged.
|