Transaction IDs and asynchronous processing

Use transaction IDs to identify API calls and handle asynchronous processing when TrustWeaver can't complete an operation synchronously.

Transaction IDs

Every compliant e-invoicing operation accepts an optional TransactionId element. This parameter identifies a single business transaction and is recorded in TrustWeaver logs. TrustWeaver doesn't enforce the uniqueness of this value.

In some cases, such as when you submit a Latin American invoice for clearance, TrustWeaver passes the transaction ID to external systems that treat it as a unique identifier. When that happens, you must use the same transaction ID to retrythe operation after a failure.

To obtain your transaction ID:

Business transaction with an identifier: Use the business transaction identifier as the transaction ID.
Business transaction without an identifier: Generate a random 128-bit value and use its hexadecimal representation. Most platforms provide this through UUID or GUID implementations.

Asynchronous processing

Some operations support or require asynchronous processing. For example, when a clearance operation must wait for a tax authority response. TrustWeaver decides whether to process a request asynchronously and the client indicates whether it is prepared to handle a request using the AsyncBehaviorMode parameter.

Possible AsyncBehaviorMode values:

NotExpected: The client can't handle asynchronous processing. If TrustWeaver determines that asynchronous processing is required, it returns an AsyncBehaviorRequired client fault. Omitting AsyncBehaviorMode is equivalent to using this value.
Expected: The client can handle asynchronous processing. TrustWeaver might still process the request synchronously if asynchronous processing is not needed.

Polling pattern

When TrustWeaver processes a request asynchronously, the response includes an AsyncState element and might omit some or all expected result elements. The client must poll until processing is complete:

Send the initial request with AsyncBehaviorMode set to Expected.
If the response contains an AsyncState element, processing is not yet complete. Wait a suitable polling interval.
Resend the same operation, including only the AsyncState from the previous response. Omit all other request elements (Document, SenderInfo, CorroborationSpec, and so on).
Each poll response includes a new AsyncState and possibly some result elements. Repeat until the response indicates completion.
Processing is complete when OperationState inside AsyncState contains a single zero byte. At that point, all expected result elements have been returned across the sequence of responses.

CAUTION: Never construct an AsyncState value. Always take it from the previous response unchanged.

OperationUniquenessViolation

TrustWeaver might detect that a submitted operation appears to duplicate a previously initiated one. For example, a Latin American invoice with the same identifiers as a previous submission. In this case, TrustWeaver returns a client fault with the code OperationUniquenessViolation.

This can occur in two situations:

Duplicate submission error: A problem in the client's identifier assignment caused the same document to be submitted twice as distinct operations. Investigate and correct the identifier generation logic before retrying.
Lost response on retry: The response to the original submission was lost, for example, due to a network failure, and the client re-submitted the same document as a retry. In this case, the fault may include an AsyncState that you can use to resume polling for the result of the original operation. Use the AsyncState in a poll request to retrieve the original result.

Note: When an OperationUniquenessViolation fault contains an AsyncState, the client application must determine whether the collision is a normal retry (use AsyncState to continue) or an indication of a data problem (investigate before proceeding).