Transaction Status
A TransactionStatusRequest
is used by a vendor to inquire about the status of one or more transactions, for example to determine whether a transaction has been cancelled or is still open. The vendor will include a TransactionItem
for each transaction whose status it requires. Each TransactionItem
element must include the TransactionId
.
The response will be in the form of a TransactionStatusResponse
element and will include an ItemStatus
element for each TransactionItem
in the request. The ItemStatus
element will contain the TransactionId
of the transaction and the ParentTransactionId
of the TransactionOpenRequest
if there is more than one transaction request associated with that transaction.
The ItemStatus
element will also contain the Quantity
, Actualized
, AssetId
, OrderNumber
, TransactionStatus
, UnitPrice
, TransactionDate
, VendorId
, StatusCode
, StatusDescription
, and OrderLineId
elements.
The Quantity
element specifies the total number of sheets that the customer has purchased. The Actualized
element specifies the number of copies of the asset that the customer has already printed. Note that the Actualized element is not used by the Noteflight Viewer and it is only provded in the response for backward compatibility. The TransactionStatus
specifies whether the transaction is OPEN, COMPLETE or CANCELLED. When a vendor creates a new transaction through a TransactionOpenRequest
or TransactionRetryRequest
, the status of the transaction is marked as "OPEN" usually until the customer prints all the copies for that transaction. The only exception to that occurs when the vendor has issued a TransactionCancelRequest
for that transaction. A TransactionCancelRequest
will change the transaction's status from "OPEN" to "CANCELLED", even if there are remaining prints for that transaction. If a transaction has not been cancelled and the customer prints all the copies of the asset, then the DAM system will change the status of the transaction to "COMPLETED".
If an error occurs while retrieving the transaction information, the ItemStatus
element will return the TransactionId
from the request, set the AssetId
, OrderNumber
, and OrderLineId
to 'unknown' and specify the respective status code and status description for the error. The status codes and status descriptions are specified on the DAM Status Codes page.
Request / Response Examples
TransactionStatusRequest Example:
<?xml version="1.0"?>
<!DOCTYPE DAMRequest SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMRequestVersion5.dtd">
<DAMRequest>
<RequestHdr>
<DAMVersion>5.0</DAMVersion>
<VendorId>123</VendorId>
<VendorKey>theKey123</VendorKey>
</RequestHdr>
<TransactionStatusRequest>
<TransactionItem>
<TransactionId>1122444</TransactionId>
</TransactionItem>
<TransactionItem>
<TransactionId>5555777</TransactionId>
</TransactionItem>
</TransactionStatusRequest>
</DAMRequest>
TransactionStatusResponse Example:
<?xml version="1.0"?>
<!DOCTYPE DAMResponse SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMResponseVersion5.dtd">
<DAMResponse>
<ResponseHdr>
<DAMVersion>5.0</DAMVersion>
<VendorId>123</VendorId>
</ResponseHdr>
<TransactionStatusResponse>
<ItemStatus>
<StatusCode>1</StatusCode>
<StatusDescription>OK.</StatusDescription>
<TransactionId>1122444</TransactionId>
<ParentTransactionId>1122333</TransactionId>
<Quantity>1</Quantity>
<Actualized>1</Actualized>
<AssetId>4000</AssetId>
<OrderNumber>12345</OrderNumber>
<TransactionStatus>CANCELLED</TransactionStatus>
<UnitPrice>3.95</UnitPrice>
<TransactionDate>2015-09-25</TransactionDate>
</ItemStatus>
<ItemStatus>
<StatusCode>1</StatusCode>
<StatusDescription>OK.</StatusDescription>
<TransactionId>5555777</TransactionId>
<ParentTransactionId>-1</ParentTransactionId>
<Quantity>1</Quantity>
<Actualized>0</Actualized>
<AssetId>2555</AssetId>
<OrderNumber>23456</OrderNumber>
<TransactionStatus>OPEN</TransactionStatus>
<UnitPrice>3.95</UnitPrice>
<TransactionDate>2015-10-25</TransactionDate>
</ItemStatus>
</TransactionStatusResponse>
</DAMResponse>