Pub/Sub API Accounting Integration

The Pub/Sub Accounting Integration allows any system capable of accessing the Salesforce Pub/Sub API to seamlessly integrate accounting with the TMS. The TMS sends outbound accounting events (Customer, Vendor, Load, Customer Invoice, and Vendor Invoice) to the Pub/Sub API event bus for processing by the accounting system. The TMS is also able to process inbound accounting events (Customer Payment and Vendor Payment) sent to the Event Bus by the accounting system.  

The main Salesforce components used by this integration include a Connected App for authentication purposes, Platform Events, and the Pub/Sub API.

Setup Connected App/API user

The Pub/Sub accounting integration requires a Connected App and an API User to function. See the Connected App Setup information for creating a Connected App and an API User.

See Salesforce documentation for additional information on creating API Users.

Accounting System Access to the Pub/Sub API

Salesforce documentation should be consulted for details on accessing the Pub/Sub API with the accounting system. The accounting system requires the URL created above with the Consumer Key and Consumer Secret.

Salesforce Pub/Sub API Documentation

Publishing and Subscribing to the Event Bus

Each time a payload is published or a subscribed payload is received is called an "Event." Each event has a unique field, the EventUUID. If there is an Event failure, a Queued Transaction is created with the EventUUID and the system administrator is notified.

Inbound Events

The TMS "listens" for subscribed events from the Event Bus. When subscribed events occur, the records are added to the TMS. The two events the TMS listens for are published Customer Payments and Vendor Payments.

Subscribing events call the streamFetchRequest API and receive a streamFetchResponse in return.

Customer Payment

When a cash application is posted to a Customer Invoice in the accounting system, a payload is published to the Event Bus. The TMS is subscribed to these events and accepts the payload.

The following fields for a Customer Payment record are created and populated from the Event Bus.

{
	"paymentId": "22s8dje8dje9dke9ew",
	"paymentType": "Check",
	"checkReferenceNumber": "12345",
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": “L-1919293”,
	"paymentDate": “2023-01-23”,
	"paymentAmount": 1000.00,
	"discount": 100.00,
	"paymentCurrency": "USD",
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Additional fields may be added to the Customer Payment TMS1 Field Set and set by inbound Customer Payment events.

Vendor Payment

Payloads are published when a cash application is posted to a Vendor Invoice in the accounting system. The TMS is subscribed to these events and accepts the payload.

The following fields for a Vendor Payment record are created and populated from the Event Bus.

{
	"paymentId": "33s8dje8dje9dke9ew",
	"paymentType": "Check",
	"checkReferenceNumber": "12345",
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"paymentDate": "2023-01-23"
	"paymentAmount": 1000.00,
	"discount": 100.00,
	"paymentCurrency": "USD",
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Additional fields may be added to the Vendor Payment TMS1 Field Set and set by inbound Vendor Payment events.

Outbound Events

The TMS publishes events to the Event Bus. When publish events occur, the records are sent to the Event Bus and are then received by the accounting integration. There are five events the TMS publishes for the accounting system. They include Customer, Customer Invoice, Vendor, Vendor Invoice, and Load event payloads.

The TMS uses Platform Events when publishing to the Event Bus for lightweight and near real time sending of data.

Most outbound payloads include the Salesforce Record ID of the record that is sent as a payload field. See Salesforce for more information on locating the record ID.

Prepare to send accounting information from the TMS by setting the Accounting Status picklist field to Ready for Accounting. The Accounting Status field is a managed Global Picklist Value Set and should not be changed. After a successful publish event, the Accounting Status changes to Sent to Accounting. A status of Publish Error displays if there is an issue and an email is sent to the system administrator.

Several field sets trigger publishing events when values are changed. Add fields to these field sets to send updated information to the accounting integration.

Publishing events call the PublishRequest API and receive a PublishResponse in return.

Customer Payload

The following fields for an Account (Customer) record are published to the Event Bus for the accounting integration.

{
	"customerId": "1js8dje8dje9dke9eq",
	"customerName": "ABC Company",
	"dbaName": "ABC Company",
	"tmsType": "Customer",
	"defaultCustomerBillToId": "aus8dje8dje9dke9ew",
	"defaultCustomerBillToName": "ABC Company",
	"billingStreet": "2333 Waukegan Road",
	"billingCity": "Bannockburn",
	"billingState": "IL",
	"billingPostalCode": "60015",
	"billingCountry": "US",
	"shippingStreet": "2333 Waukegan Road",
	"shippingCity": "Bannockburn",
	"shippingState": "IL",
	"shippingPostalCode": "60015",
	"shippingCountry": "US",
	"customerCurrency": "USD",
	"contacts":
	[
		{
			"contactId": "1d8dkj38djk39dk39d",
			"firstName": "George",
			"lastName": "Smiley",
			"email": "gsmiley@revenova.com",
			"phone": "312-333-9999",
			"role": "Billing"
		}
	]
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Vendor Payload

The following fields for an Account (Vendor) record are published to the Event Bus for the accounting integration.

Contacts Payload

The following fields for a Contact record are published to the Event Bus as part of Customer and Vendor payloads. Multiple Contact records may be added to a single Customer or Vendor payload.

Load Payload

The following fields for a Load record are published to the Event Bus for the accounting integration.

{
	"loadId": "1js8dje8dje9dke9et",
	"loadName": "Load-12345",
	"customerId": "1js8dje8dje9dke9eq",
	"customerName": "ABC Company",
	"customerBillToId": "1js8dje8dje9dke9eq",
	"customerBillToName": "ABC Company",
	"customerSalesRepId": "1je8dje8e6ehe9eie8",
	"customerSalesRepName": "George Smiley",
	"carrierSalesRepId": "1je8dje8e6ehe9eie8",
	"carrierSalesRepName": "Roy Bland",
	"mode": "Truckload",
	"weight": 20000,
	"weightUnits": "lbs",
	"stops": 
	[
		{
    "stopId": "2j8fj3d9dkj3d9dk303",
			"stopName": "Stop 1",
			"stopNumber": 1,
			"isPickup": true,
			"isDelivery": false,
			"expectedDate": "2023-01-22",
			"appointmentTime": "10:00",
			"locationName": "ABC Warehouse",
			"street": "123 North Ave.",
			"city": "Chicago",
			"state": "IL",
			"postalCode": "60603",
			"country": "US"
		},
		{
     "stopId": "2j8fj3d9dkj3d9dk223",
			"stopName": "Stop 2",
			"stopNumber": 2,
			"isPickup": false,
			"isDelivery": true,
			"expectedDate": "2023-01-22",
			"appointmentTime": "10:00"
			"locationName": "DEF Warehouse",
			"street": "333 North Ave.",
			"city": "Chicago",
			"state": "IL",
			"postalCode": "60603",
			"country": "US"
		}
	],
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Stops Payload

The following fields for a Stop record are published to the Event Bus as part of a single Load Payload. Multiple Stop records may be added to a Load payload.

Customer Invoice Payload

The following fields for a Customer Invoice record are published to the Event Bus for the accounting integration.

{
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"invoiceType": "Invoice",
	"customerId": "aus8dje8dje9dke9ew",
	"customerBillToId": "aus8dje8dje9dke9ew",
	"loadId": "s823js8ew888fk39dk",
	"loadNumber": "Load-123",
	"invoiceDate": "2023-01-23",
	"invoiceDueDate": "2023-02-23"
	"invoiceTotal": 2222.50,
	"paymentDiscount": 0.00,
	"taxAmount": 0.00,
	"invoiceCurrency": "USD",
	"charges":
	[
		{
			"chargeType": "Freight",
			"description": "Freight",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Fuel",
			"description": "Fuel",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Accessorial",
			"description": "Lift Gate Pickup",
			"accessorialId": "q2d4s8ewh37su28sj3",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 0.10,
			"chargeAmount": 100.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		}
	]
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Vendor Invoice Payload

The following fields for a Vendor Invoice record are published to the Event Bus for the accounting integration.

{
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"invoiceType": "Invoice",
	"vendorId": "aus8dje8dje9dke9ew",
	"vendorRemitToId": "1kmd8dk30d3ll30dd",
	"loadId": "s823js8ew888fk39dk",
	"loadNumber": "Load-123",
	"nvoiceDate": "2023-01-23",
	"invoiceDueDate": "2023-02-23"
	"invoiceTotal": 100.50,
	"paymentDiscount": 0.00,
	"invoiceCurrency": "USD",
	"charges":
	[
		{
			"chargeType": "Freight",
			"description": "Freight",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Fuel",
			"description": "Fuel",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Accessorial",
			"description": "Lift Gate Pickup",
			"accessorialId": "q2d4s8ewh37su28sj3",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 0.10,
			"chargeAmount": 100.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		}
	]
    "customFields":
	[
		{
            "fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Charge Payloads

The following fields for a Charge record are published to the Event Bus as part of Customer and Vendor Invoice payloads. Multiple Charge records may be added to a single Customer or Vendor invoice from the respective objects.

Freight & Fuel Accessorial Charge Fields