barsa d943d04754 Refactor environment configuration and enhance order processing logic

- Updated SF_PUBSUB_NUM_REQUESTED in environment configuration to improve flow control.
- Enhanced CatalogCdcSubscriber and OrderCdcSubscriber to utilize a dynamic numRequested value for subscriptions, improving event handling.
- Removed deprecated WHMCS API access key configurations from WhmcsConfigService to streamline integration.
- Improved error handling and logging in various services for better operational insights.
- Refactored currency service to centralize fallback currency logic, ensuring consistent currency handling across the application.

2025-11-17 10:31:33 +09:00

11 KiB

Raw Blame History

Salesforce ↔ WHMCS Mapping Reference

Complete field mapping and data transformation reference for order fulfillment workflow.

🗺️ Overview

This document provides the authoritative mapping between Salesforce Order/OrderItem data and WHMCS API parameters for the order fulfillment process.

Data Flow

Salesforce Order/OrderItems → BFF Transformation → WHMCS AddOrder API → WHMCS Services

📊 Complete Field Mapping

Order Header Mapping

Salesforce Field	WHMCS Parameter	Example Value	Type	Notes
`Order.AccountId`	`clientid`	`1`	int	Resolved via portal mapping table
N/A (System)	`paymentmethod`	`"mailin"`	string	Required by WHMCS API
N/A (System)	`noinvoice`	`true`	bool	Don't create invoice during provisioning
N/A (System)	`noemail`	`true`	bool	Don't send emails during provisioning
`Order.Id`	Added to notes	`"sfOrderId=8014x000000ABCDXYZ"`	string	For tracking purposes

OrderItem Array Mapping

Salesforce Source	WHMCS Parameter	Example	Type	Transformation
`Product2.WH_Product_ID__c`	`pid[]`	`["185", "242", "246"]`	string[]	Convert number to string
`Product2.Billing_Cycle__c`	`billingcycle[]`	`["monthly", "onetime", "monthly"]`	string[]	Lowercase transformation
`OrderItem.Quantity`	`qty[]`	`[1, 1, 1]`	int[]	Direct mapping

Optional Parameters

Salesforce Source	WHMCS Parameter	Default Value	Notes
N/A	`promocode`	`""`	Not used in provisioning
N/A	`configoptions[]`	`["", "", ""]`	Base64 encoded if needed
N/A	`customfields[]`	`["", "", ""]`	Base64 encoded if needed

🏷️ Product Mapping Examples

Internet Products

Product Name	Salesforce SKU	WH_Product_ID__c	WHMCS pid	Billing_Cycle__c	WHMCS billingcycle
Internet Silver (Home 1G)	`INTERNET-SILVER-HOME-1G`	181	"181"	"Monthly"	"monthly"
Internet Gold (Home 1G)	`INTERNET-GOLD-HOME-1G`	182	"182"	"Monthly"	"monthly"
Internet Platinum (Home 1G)	`INTERNET-PLATINUM-HOME-1G`	183	"183"	"Monthly"	"monthly"
Internet Silver (Apartment 1G)	`INTERNET-SILVER-APT-1G`	184	"184"	"Monthly"	"monthly"
Internet Gold (Apartment 1G)	`INTERNET-GOLD-APT-1G`	185	"185"	"Monthly"	"monthly"
Internet Platinum (Apartment 1G)	`INTERNET-PLATINUM-APT-1G`	186	"186"	"Monthly"	"monthly"

Installation Products

Product Name	Salesforce SKU	WH_Product_ID__c	WHMCS pid	Billing_Cycle__c	WHMCS billingcycle
Single Installation	`INTERNET-INSTALL-SINGLE`	242	"242"	"One-time"	"onetime"
12-Month Installation	`INTERNET-INSTALL-12M`	243	"243"	"One-time"	"onetime"
24-Month Installation	`INTERNET-INSTALL-24M`	244	"244"	"One-time"	"onetime"
Weekend Installation Fee	`INTERNET-INSTALL-WEEKEND`	245	"245"	"One-time"	"onetime"

Add-on Products

Product Name	Salesforce SKU	WH_Product_ID__c	WHMCS pid	Billing_Cycle__c	WHMCS billingcycle
Hikari Denwa Service	`INTERNET-ADDON-HOME-PHONE`	246	"246"	"Monthly"	"monthly"
Hikari Denwa Installation	`INTERNET-ADDON-DENWA-INSTALL`	247	"247"	"One-time"	"onetime"

VPN Products

Product Name	Salesforce SKU	WH_Product_ID__c	WHMCS pid	Billing_Cycle__c	WHMCS billingcycle
VPN USA (San Francisco)	`VPN-USA-SF`	33	"33"	"Monthly"	"monthly"
VPN UK (London)	`VPN-UK-LONDON`	54	"54"	"Monthly"	"monthly"
VPN Activation Fee	`VPN-ACTIVATION`	37	"37"	"One-time"	"onetime"

📋 Complete Order Example

Salesforce Order Structure

Order {
  Id: "8014x000000ABCDXYZ",
  AccountId: "001xx000004TmiQAAS",
  Status: "Pending Review",
  Order_Type__c: "Internet"
}

OrderItems [
  {
    Id: "8024x000000DEFGABC",
    Product2: {
      WH_Product_ID__c: 185,
      Billing_Cycle__c: "Monthly",
      SKU: "INTERNET-GOLD-APT-1G"
    },
    Quantity: 1
  },
  {
    Id: "8024x000000HIJKLMN",
    Product2: {
      WH_Product_ID__c: 242,
      Billing_Cycle__c: "One-time",
      SKU: "INTERNET-INSTALL-SINGLE"
    },
    Quantity: 1
  },
  {
    Id: "8024x000000OPQRSTU",
    Product2: {
      WH_Product_ID__c: 246,
      Billing_Cycle__c: "Monthly",
      SKU: "INTERNET-ADDON-HOME-PHONE"
    },
    Quantity: 1
  }
]

Transformed WHMCS AddOrder Request

{
  "action": "AddOrder",
  "clientid": 1,
  "paymentmethod": "mailin",
  "pid": ["185", "242", "246"],
  "billingcycle": ["monthly", "onetime", "monthly"],
  "qty": [1, 1, 1],
  "noinvoice": true,
  "noemail": true,
  "promocode": "",
  "configoptions": ["", "", ""],
  "customfields": ["", "", ""]
}

WHMCS AddOrder Response

{
  "result": "success",
  "orderid": 12345,
  "serviceids": "67890,67891,67892",
  "addonids": "",
  "domainids": "",
  "invoiceid": 0
}

🔄 Status Update Mapping

Salesforce Order Status Updates

During Fulfillment

Step	Order.Status	Provisioning_Status__c	WHMCS_Order_ID__c	Notes
Initial	"Pending Review"	null	null	Customer placed order
CS Approval	"Activating"	"In Progress"	null	CS clicked provision
WHMCS Created	"Activating"	"In Progress"	"12345"	AddOrder completed
Services Active	"Activated"	"Fulfilled"	"12345"	AcceptOrder completed

On Failure

Step	Order.Status	Provisioning_Status__c	Error Fields	Notes
Validation Failure	"Draft"	"Failed"	Error_Codec, Error_Messagec	Revert to draft
WHMCS API Failure	"Draft"	"Failed"	Error_Codec, Error_Messagec	Rollback status

OrderItem Status Updates

Field	Source	Example	Notes
`WHMCS_Service_ID__c`	AddOrder response (`serviceids`)	"67890"	Individual service ID
`Billing_Cycle__c`	Already set	"Monthly"	No change during fulfillment

🔧 Data Transformation Rules

Billing Cycle Transformation

// Salesforce → WHMCS transformation
const billingCycleMap = {
  Monthly: "monthly",
  Quarterly: "quarterly",
  Semiannually: "semiannually",
  Annually: "annually",
  "One-time": "onetime",
  Onetime: "onetime",
};

// Implementation
billingCycle: product.billingCycle.toLowerCase();

Product ID Transformation

// Salesforce WH_Product_ID__c (number) → WHMCS pid (string)
productId: product.whmcsProductId.toString();

Client ID Resolution

// Order.AccountId → WHMCS clientid via mapping table
const mapping = await mappingsService.findBySfAccountId(order.AccountId);
clientId: mapping.whmcsClientId;

🛡️ Validation Rules

Required Field Validation

// Before WHMCS API call
✅ clientid must be valid WHMCS client
✅ paymentmethod must be valid WHMCS payment method
✅ pid[] must contain valid WHMCS product IDs
✅ billingcycle[] must match WHMCS billing cycles
✅ qty[] must be positive integers

Business Rule Validation

// Before provisioning
✅ Order.Status must be "Pending Review" or "Activating"
✅ Order must not already have WHMCS_Order_ID__c
✅ Client must have valid payment method in WHMCS
✅ All products must have WH_Product_ID__c mapping

📝 Implementation Notes

Array Handling

WHMCS expects arrays: Use pid[], billingcycle[], qty[] format
Order matters: Arrays must be in same order (pid[0] matches billingcycle[0])
Empty values: Use empty strings "" for optional array elements

Serialization (Advanced)

// For configoptions[] and customfields[] if needed
function serializeForWhmcs(data: Record<string, string>): string {
  const serialized = phpSerialize(data);
  return Buffer.from(serialized).toString("base64");
}

// PHP serialize format: a:2:{s:3:"key";s:5:"value";}

Error Handling

// WHMCS API error responses
{
  "result": "error",
  "message": "Client ID Not Found"
}

// Map to structured error codes
WHMCS_CLIENT_NOT_FOUND → ORDER_NOT_FOUND
WHMCS_PRODUCT_INVALID → MAPPING_ERROR
WHMCS_API_ERROR → WHMCS_ERROR

This mapping reference ensures consistent data transformation and provides the complete picture for troubleshooting and maintenance.

11 KiB Raw Blame History