Sage

Sage Integration Guide

Sync your invoice and customer data directly from Salesforce to Sage.
This integration ensures accounting accuracy by seamlessly pushing relevant invoice data, customer records, and revenue recognition dates from your TMS to Sage.

Overview

The Sage Integration connects FTM.cloud’s Transportation Management System (TMS) directly to Sage Intacct for seamless synchronization of invoices, customers, and item data.
This integration ensures financial accuracy by automatically pushing invoice data, customer records, and revenue details from Salesforce to Sage.

1️⃣ User Information – What This Integration Does

Purpose

This integration automates the invoicing and customer sync process between FTM and Sage Intacct, enabling accounting teams to:

Push invoices from FTM to Sage Intacct
Automatically create or update customer records
Sync item-level billing lines with accurate Sage Item Codes
Track Sage invoice keys and statuses directly in Salesforce
Eliminate double data entry between systems

Key Features

✅ One-click invoice push from Salesforce to Sage
✅ Automatic customer and item creation
✅ XML-based secure API communication
✅ Updates FTM records with Sage keys (Customer RecordNo, Invoice Key, etc.)
✅ Visualforce page to view invoice details and trigger Sage actions

Workflow Summary

Load or Storage record is completed and ready for invoicing
User opens the “Send Invoice to Sage” Visualforce page
Click “Create Customer” (if not already synced)
Click “Create Invoice/Transaction” to push the invoice to Sage
Success or error messages appear instantly on-screen
Sage IDs are automatically stored back in FTM fields

Scope & Limitations

⚠️ Important Notes

The integration supports only Sage Intacct XML Web Services
Each FTM record must have valid billing addresses and contact details
Special characters (like & or ‘) in customer names may cause Sage API rejections
The process requires valid Sage credentials configured in the backend Apex logic

Authentication

The connection uses Sage’s XML Gateway endpoint:
https://api.intacct.com/ia/xml/xmlgw.phtml

Credential Fields (hardcoded in sandbox, customizable via Custom Settings):

senderid
senderpassword
userid
companyid
passwordid

Production credentials should be securely stored in Salesforce Custom Settings → Sage.
This prevents hardcoding and allows admin updates without code deployment.

To create custom setting:
Go to setup => Custom setting => Create New => Save

=> In the Custom Field section, create the fields.

=> Add the value to the fields, and save.

2️⃣ Developer Information – How It Works in Salesforce

Repository

🔗 GitHub: https://github.com/ashkanshamili/FTM

Apex Class

SageInvoice.cls
Handles customer, item, and invoice creation through Sage Intacct’s XML API.

Method	Purpose
CustomerCreate(Id invoiceId)	Creates or updates a customer in Sage using billing data from FreightTM__Storage__c and related Account.
InvoiceCreate(Id invoiceId)	Builds and sends invoice XML with line items to Sage, updates record with returned Sage Key.
ItemCreate(Id invoiceId)	Pushes related line items as Sage Items, updates Sage Item Record Numbers.
CreateCustomer()	Visualforce action method → runs CustomerCreate().
CreateInvoice()	Visualforce action method → runs InvoiceCreate().
CreateItem()	Visualforce action method → runs ItemCreate().

Visualforce Page

SageInvoice.page
Provides UI to review invoice data and trigger actions to send data to Sage.

Button	Action
Create Customer	Calls SageInvoice.CustomerCreate()
Create Invoice/Transaction	Calls SageInvoice.InvoiceCreate()
(Optional) Create Item	Calls SageInvoice.ItemCreate()

Page Layout Highlights

Displays invoice number, date, terms, total, and storage details
Lists all related line items with description, price, quantity, and Sage item type
Provides success/error messages inline
Includes a “Back” button to return to previous record

API Endpoint

Purpose	Method	URL
Sage XML Gateway	POST	https://api.intacct.com/ia/xml/xmlgw.phtml

Core Salesforce Objects

Object	Usage
FreightTM__Storage__c	Invoice record pushed to Sage.
FreightTM__Storage_Billing__c	Line items mapped to Sage invoice items.
Account	Customer record; updated with Sage Record Numbers.

XML Request Samples

Create customer

<request>
  <control>
    <senderid>vinovault</senderid>
    <password>VinoVault2023%!</password>
    <controlid>test</controlid>
    <uniqueid>false</uniqueid>
    <dtdversion>3.0</dtdversion>
  </control>
  <operation>
    <authentication>
      <login>
        <userid>sbaker</userid>
        <companyid>vinovault-sandbox</companyid>
        <password>V$S@apa!Vino123!!!</password>
      </login>
    </authentication>
    <content>
      <function controlid="createCustomer">
        <create>
          <CUSTOMER>
            <CUSTOMERID>12345</CUSTOMERID>
            <NAME>ACME Logistics</NAME>
            <DISPLAYCONTACT>
              <PHONE1>555-1010</PHONE1>
              <MAILADDRESS>
                <ADDRESS2>123 Main St</ADDRESS2>
                <CITY>Dallas</CITY>
                <STATE>TX</STATE>
                <ZIP>75201</ZIP>
              </MAILADDRESS>
            </DISPLAYCONTACT>
          </CUSTOMER>
        </create>
      </function>
    </content>
  </operation>
</request>

Create invoice

<create_sotransaction>
  <transactiontype>Sales Invoice</transactiontype>
  <datecreated>
    <year>2025</year><month>10</month><day>27</day>
  </datecreated>
  <customerid>12345</customerid>
  <referenceno>FTM-INV-5678</referenceno>
  <termname>Net 30</termname>
  <state>TX</state>
  <sotransitems>
    <sotransitem>
      <itemid>1022</itemid>
      <itemdesc>Temperature Controlled Transport</itemdesc>
      <taxable>true</taxable>
      <quantity>5</quantity>
      <unit>Each</unit>
      <price>300</price>
      <locationid>NYW</locationid>
    </sotransitem>
  </sotransitems>
</create_sotransaction>

Response Handling

XML response parsed via Dom.Document
Extracts <RECORDNO> and <CUSTOMERID> or <key> for invoices
Updates Salesforce fields automatically:
- Sage_Customer_ID__c
- Sage_Customer_RecordNo__c
- Sage_Invoice_Key__c
- Status__c → “Sent” or “Invoice Sent”

Error Management

Scenario	Behavior
API failure (non-200)	Displays generic error message in Visualforce page
Sage XML “failure” node	Extracts <description> and <description2> text and shows detailed message
Missing required field	Customer or invoice creation halted, message displayed
Item sync failure	Continues remaining items, logs failed item details

Testing

Run in Anonymous Apex:

SageInvoice.CustomerCreate('a0KXXXXXXXXXXXXXXX');
SageInvoice.InvoiceCreate('a0KXXXXXXXXXXXXXXX');

Or directly via the Visualforce page:

/apex/SageInvoice?id=a0KXXXXXXXXXXXXXXX

Deployment Notes

Sandbox uses vinovault-sandbox company ID
Production will use your live Sage company credentials
Move credentials to Custom Setting: Sage before deployment
Ensure Remote Site Settings include https://api.intacct.com
Include test coverage for all three flows (Customer, Item, Invoice)

UI Summary

Buttons

🧾 Create Customer → Creates or updates Sage customer
💰 Create Invoice/Transaction → Pushes invoice and line items
📦 (Optional) Create Item → Syncs Sage Item records

Visual Output

Invoice header details
Line item breakdown table
Inline success or failure messages

Support Contacts

📧 Integration Support: [email protected]