The gateway supports both synchronous and asynchronous responses to incoming requests. A synchronous response returns to the client in the same HTTP connection as the request. With asynchronous responses, a client can send multiple requests and receive the responses in subsequent connections.

By default, responses from the gateway are synchronous. If you want asynchronous responses, some additional steps are required.

The use of synchronous responses is similar to using the Process offline option for CSV imports and reports in the Sage Intacct UI.


Synchronous responses

Synchronous responses are typically used when the client must wait to receive the response before processing continues on the client side. A request is processed in real time, and the gateway returns the response via the HTTP connection created by the client. If a validation error occurs, the error is returned synchronously.

processing of synchronous response

Note: Sending a large request can cause the sender process to time out (after 15 minutes) even though the request is still being processed by the Sage Intacct system. You can avoid timeouts using by limiting your calls to a given set of recommendations.


Asynchronous responses

You can work with Sage Intacct to configure asynchronous processing if you do not want your client to wait for responses in the same HTTP connection. Asynchronous responses can be very useful when posting large requests that require significant processing time or when a response is not needed in the same HTTP connection.

processing of asynchronous response

Setting up asynchronous processing

You must open a support case for help establishing an asynchronous transport policy. Be prepared to provide the following information:

Attribute Required Type Description
Policy ID Required string(40) Unique policy ID you want to use
Response URL Required string(256) Callback URL for posting XML responses. HTTPS is the only supported protocol.
HTTP User ID Optional string(40) User ID for basic server authentication
HTTP Password Optional string(40) Password for basic server authentication
Serialize Optional boolean Serialize async requests one at a time. Default: false

An example transport policy setup is as follows:

Using asynchronous processing

Once you have a transport policy in place, you provide the transport policy ID in the <control> block of your requests, as shown:

<request>
    <control>
        <senderid>test_sender</senderid>
        <password>test_password</password>
        <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
        <policyid>hello-world</policyid> <!-- this your unique transport policy ID -->
        <includewhitespace>false</includewhitespace>
    </control>
    <operation>
        <!-- ... -->
    </operation>
</request>

The above request will result in the following acknowledgement response, and the connection is closed:

<response>
      <acknowledgement>
            <status>success</status>
      </acknowledgement>
      <control>
            <status>success</status>
            <senderid>test_sender</senderid>
            <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid>
            <uniqueid>false</uniqueid>
            <dtdversion>3.0</dtdversion>
      </control>
</response>

When the request is processed out of the queue, a response is posted back in a new connection using the callback URL and any other parameters set up in the transport policy:

POST /test/intacct-async.php HTTP/1.1
Host: www.example.com
Content-Type: application/xml
Authorization: Basic abc123

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <control>
        <status>success</status>
        <senderid>test_sender</senderid>
        <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <operation>
        <!-- ... -->
    </operation>
</response>

Best practices and tips

Asynchronous requests require more infrastructure on your end, compared to simply sending a request and waiting for a response. Consider the following best practices and tips when preparing to use asynchronous processing:

Provide feedback