Overview

Get going quickly using Sage Intacct Web Services with the Sage Intacct SDK for PHP. The SDK allows you to work with pre-built PHP objects instead of directly with the underlying XML API.

The Sage Intacct SDK for PHP is licensed under Apache v2.0. Please read and accept this before using the SDK.

This topic provides a high-level overview of the SDK. When you are ready to start coding, try the getting started example and keep the reference documentation handy for delving deeper.


System Requirements


Quick Install

  1. Install Composer
  2. In your project, specify the Sage Intacct SDK for PHP as a dependency in your project’s composer.json file:

     {
         "require": {
             "intacct/intacct-sdk-php": "v2.*"
         }
     }
    
  3. In a terminal window, run composer install from the root folder.

  4. Require Composer’s autoloader in your project file(s):

     require __DIR__ . '/vendor/autoload.php';
    

Client model

The SDK uses a client model for sending requests to the gateway. You construct a client, optionally configure it, then use it to execute your requests.

There are two kinds of clients:

Both clients provide an execute call that sends a single API function, and an executeBatch function for sending multiple functions. For usage information, see the getting started example.


Client configuration

When you construct a client, you can optionally provide configuration information in a client configuration object. This object can provide Web Services credentials, company credentials, a session ID, logger choices, the gateway endpoint, and so forth.

$config = new ClientConfig();                // Create the config and set a session ID
$config->setSessionId('SomeSessionFromTheInternet..'); 
$client = new OnlineClient($clientConfig);   // Construct the client with the config

During client instantiation, the default endpoint (https://api.intacct.com/ia/xml/xmlgw.phtml) is used.


Request configuration

To configure the request that is sent to the gateway by the SDK, create a request configuration instance and pass it in when you call execute or executeBatch.

You can use a request configuration to set a control ID for the request, specify a transport policy ID (for an offline client), set a time-out value, and so forth.

$requestConfig = new RequestConfig();                    // Create the request config and set a control ID
$requestConfig->setControlId("testing123");
$response = $client->execute($query, $requestConfig);    // Execute the request

For a high-level understanding of how you can configure requests, see XML Requests.


API functions

The underlying API functions are made available through classes in the Intacct/Functions namespace. The classes that provide object-specific functionality are under feature namespaces, and the classes that provide generic functionality are in a single namespace. For example, object-specific classes such as CustomerCreate, JournalEntryCreate, and ContactUpdate are under their respective categories, and generic classes such as Read and ReadByQuery are under a single Common namespace.

All these classes implement FunctionInterface and extend AbstractFunction, which gives them access to an XML writer that translates the PHP objects into XML.

The clients can execute any class implementations of the FunctionInterface. If the Intacct/Functions classes do not meet your needs, you are welcome to write your own classes that implement this interface. Check out Custom Object Function for more on this.

The following example constructs a ReadByQuery instance that queries for vendors:

 $query = new ReadByQuery();
 $query->setObjectName('VENDOR');
 $query->setPageSize(1); // Keep the count to just 1 for the example
 $query->setFields([
     'RECORDNO',
     'VENDORID',
     'NAME',
 ]);

Credentials

There are several ways you can supply Web Services and company credentials to the SDK.

You can mix and match how credentials are loaded. For example, you might set Web Services credentials in your environment, then load company login credentials from a credentials file. You can also pass company credentials directly to the ClientConfig from a different source.

Hard-coded credentials

The following shows how to provide hard-coded Web Services and company credentials using ClientConfig:

$config = new ClientConfig();
$config->setSenderId('testsenderid');
$config->setSenderPassword('pass123!');
$config->setCompanyId('testcompany');
$config->setUserId('testuser');
$config->setUserPassword('testpass');

Note: You should make every effort to securely store your credentials and not hard-code them.

Environment variables

You can use environment variables to specify credentials directly or via named profiles in a credentials file. You can also override the default gateway endpoint using an environment variable.

Variable Description
INTACCT_SENDER_ID, INTACCT_SENDER_PASSWORD Hard-coded Web Services credentials.
INTACCT_COMPANY_ID, INTACCT_USER_ID, INTACCT_USER_PASSWORD Hard-coded company login credentials.
INTACCT_SENDER_PROFILE, INTACCT_COMPANY_PROFILE,INTACCT_PROFILE Names of profiles in a credentials file. Using these variables causes the client to load credentials from the given profile in the credentials file in use.
INTACCT_ENDPOINT_URL Overrides the default endpoint URL.

Credentials file and profiles

If not otherwise supplied, the SDK will look for credentials in the default profile in a credentials file in the default location:

home_dir/.intacct/credentials.ini

The following shows the format for the file. Each profile starts with a name in brackets followed by key/value pairs.

[default]
sender_id = "mysenderid"
sender_password = "mysenderpassword"
company_id = "mycompanyid"
user_id = "myuserid"
user_password = "myuserpassword"

[demo987654321]
company_id = "demo987654321"
user_id = "myuserid"
user_password = "myuserpassword"

[dev123]
sender_id = "mysenderid"
sender_password = "mysenderpassword"
endpoint_url = "https://api.intacct.com/ia/xml/xmlgw.phtml"

You can provide values for the following in any profile:

Override the location for the credentials file

You can override the default location of the credentials file with the ClientConfig::setProfileFile function:

$config = new ClientConfig();
$config->setProfileFile(__DIR__ . '/.SomeFileNotInSourceControl.ini');
$config->setProfileName('demo987654321');

$client = new OnlineClient($config);

Use a non-default profile name

As shown above, you can specify a non-default profile to use with ClientConfig::setProfileName. You can also use the INTACCT_SENDER_PROFILE, INTACCT_COMPANY_PROFILE, or INTACCT_PROFILE environment variables for this purpose.

Session credentials

Some integrations are triggered by Smart Event HTTP notifications. Such notifications typically include a session ID and endpoint URL.

Warning: Do not blindly trust session IDs that your server receives over the internet. Always validate these parameters before using them.

You can use the static SessionProvider::factory function to validate that a session ID is valid and that the endpoint URL is a *.intacct.com domain.

try {
    $config = new ClientConfig();
    // Web Services credentials are loaded from the environment
    // Assume the following endpoint and session ID came from the $_POST (after using sanitize filters)
    $config->setEndpointUrl('https://api.intacct.com/ia/xml/xmlgw.phtml');
    $config->setSessionId('SomeSessionFromTheInternet..');
    
    // Validate that the session ID is valid and the endpoint URL is a *.intacct.com domain
    $sessionConfig = SessionProvider::factory($config);
    
    // Create a client with the validated session credentials in a new ClientConfig
    $client = new OnlineClient($sessionConfig);
    
    // Execute some other API functions
    
} catch (\Exception $exception) {
    echo 'Uh oh...';
}

Client/entity slide-in credentials

The following table shows how to specify companies when using client/entity slide in. Note the use of the pipe character (|) to separate the IDs.

Description Company ID
Client linked from your console myConsoleId|clientCompanyId
Entity level of a company companyId|entityId
Entity level of a company for a client linked from your console myConsoleId|clientCompanyId|entityId

Error handling

There are several categories of errors that can occur when sending requests to the gateway. Your code should handle these.

Exception Description
IntacctException An IntacctException extends the \RuntimeException and is likely an issue with Sage Intacct itself.
ResponseException A ResponseException extends the \RuntimeException and is likely a problem with the client or request configuration.
ResultException A ResultException extends the ResponseException and is likely a problem with an API function being executed.

The execute and executeBatch functions have some built-in error handling for the results (Result instances) coming back:


Logging

The SDK lets you use any logger that implements the PSR-3 Logger Interface. One popular implementation is Monolog, which is used throughout the SDK examples.

A logger can be set using the ClientConfig::setLogger function. If set, the SDK will add entries for all HTTP request and responses with the Sage Intacct API endpoint.

By default, the SDK writes log entries using the debug log level. To change the level, use ClientConfig::setLogLevel. If you change the level, consider changing the format to omit the XML request and response as these can get quite large.

To format the entries differently, construct a new Intacct\Logging\MessageFormatter object and add it to the config with ClientConfig::setLogMessageFormatter. Refer to the PHPDoc comments in the MessageFormatter::__construct for the variables used by the formatter.

The logger will attempt to redact sensitive info, like passwords, from the debug entries. Regardless, access to logs should always be restricted.


What’s Next?

Provide feedback