Sovos.com Contact Support

e-invoicing

TrustWeaver

Retrieve documents

TrustWeaver provides several operations for retrieving stored invoices and documents from the storage service.

After invoices are stored in the TrustWeaver storage service, you can retrieve them individually by reference, search for invoices using metadata criteria, or download all documents in a section at once.

Available retrieval operations

The following operations are available for retrieving and managing stored documents:

GetInvoice
Retrieves a store invoice by reference, including the document, signature, metadata, and all attachments.
SearchInvoices
Searches for invoices in a storage area using metadata criteria and only returns references and metadata. To retrieve the full invoice or attachment data, use GetInvoice.
ListInvoiceReferences
Returns all references for invoices stored in a named section and supports pagination.
ListExpiringInvoiceReferences
Returns references for invoices whose storage period is approaching expiration.
UpdateInvoice
Updates the metadata or document data of a stored invoice.
CreateToken
Creates a single-use access token for downloading a specific document without client certificate authentication.
OffloadSection
Bulk downloads all section documents, as long as the section is in the LockedForArchiving state. Intended for offboarding or bulk retrieval.

References

Each stored invoice is identified by a unique reference string. The reference is returned when you store the invoice, and you need it to retrieve the invoice later. An invoice stored for both the supplier and the buyer results in two stored invoices, each with a separate reference: One where the supplier is the principal party and one where the buyer is the principal party.

Section states and retrieval

You can retrieve documents from sections in the Enabled or Locked state. Retrieval is not available for sections in the Closed state.

Note: Lock the section before performing bulk retrieval using ListInvoiceReferences. Locking prevents race conditions that could occur if documents are stored while the listing is in progress, which could cause recently stored documents not to be included.

Retrieve an invoice through the API

You must have the reference string for the stored invoice. The reference is returned in the StoreInvoice response or from a SearchInvoices call.

The GetInvoice operation returns the full invoice document, including the electronic signature and all attachments. It also returns metadata such as invoice number, date, supplier and buyer information, custom properties, storage time, and the storage period end date.

To share a document with a recipient who doesn't have a client certificate, generate a single-use download token. See Create a download token through the API.

  1. Build the GetInvoice request with a unique TransactionId and the Reference of the stored invoice.

    Example request:

    CODE 
    <GetInvoice xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
  </Request>
</GetInvoice>
  2. Send the request to the storage service endpoint using HTTPS with client certificate authentication.
  3. Process the GetInvoiceResponse.

    The response contains the following elements:

    Element Type Occurrences Description
    Document tas:Document 1 The archived invoice, including the electronic signature.
    InvoiceInfo tas:InvoiceInfo 1 Invoice metadata such as invoice number, date, and purchase order numbers.
    SupplierInfo tas:InvoicingPartyInfo 0..1 Information about the supplier. Present when the invoice is stored on behalf of the supplier (StoreFor is true).
    BuyerInfo tas:InvoicingPartyInfo 0..1 Information about the buyer. Present when the invoice is stored on behalf of the buyer (StoreFor is true).
    Attachments tas:Attachments 1 All documents attached to the invoice.
    CustomProperties tas:CustomProperties 1 Custom string properties associated with the invoice.
    CustomNumericProperties tas:CustomNumericProperties 0..1 Custom numeric properties associated with the invoice. Only included for invoices that have numeric properties.
    StoredTime xs:dateTime 1 The date and time the invoice was stored, in UTC.
    StoragePeriodEndDate xs:dateTime 1 The date when the storage period for the invoice ends. This is a calculated value and may change over time if the configuration changes.
    ClosureEvidences tas:ClosureEvidences 0..1 Closure evidence documents associated with the invoice. Omitted if there are no closure evidences.

    Example response:

    CODE 
    <GetInvoiceResponse xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result>
    <Document>
      <Data>ABCD1234</Data>
      <DocumentFormat>OTHER</DocumentFormat>
      <ExplicitSignatureInfo>
        <DetachedSignature>MIME...</DetachedSignature>
        <SignatureFormat>PKCS7D</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ExplicitSignatureInfo>
    </Document>
    <InvoiceInfo>
      <InvoiceNo>1234</InvoiceNo>
      <InvoiceDate>2010-09-06T00:00:00</InvoiceDate>
    </InvoiceInfo>
    <SupplierInfo>
      <Name>customer1</Name>
      <StoreFor>true</StoreFor>
      <CountryCode>SE</CountryCode>
      <VatNo>ABCD1234</VatNo>
    </SupplierInfo>
    <BuyerInfo>
      <Name>customer2</Name>
      <StoreFor>false</StoreFor>
      <CountryCode>DE</CountryCode>
      <VatNo>ABCD1234</VatNo>
    </BuyerInfo>
    <Attachments />
    <CustomProperties>
      <Property>
        <Name>MyProperty</Name>
        <Value>some value</Value>
      </Property>
    </CustomProperties>
    <StoredTime>2010-09-07T13:15:44Z</StoredTime>
    <StoragePeriodEndDate>2020-09-06T00:00:00</StoragePeriodEndDate>
  </Result>
</GetInvoiceResponse>

A successful call returns the invoice document, signature data, and all associated metadata. Either SupplierInfo or BuyerInfo have StoreFor set to true, identifying the party that owns the stored invoice. For error codes returned by this operation, see Storage service error codes.

Search criteria reference

Criteria and combination logic

A criterion is a condition on a single invoice metadata property. A criterion is fulfilled when the property value matches the condition. By default, all criteria in a request are combined with AND logic. An invoice is returned only when every criterion is fulfilled.

To apply OR logic across a criteria group, assign them to the same disjunction group. A disjunction group is fulfilled when at least one of its criteria is fulfilled. Disjunction groups are combined with each other and with any ungrouped criteria using AND logic.

For a request with criteria A, B, C, D, and E, where A and B belong to group 1, C and D belong to group 2, and E is ungrouped, the combined condition is:

CODE 
(A OR B) AND (C OR D) AND E
Note:

The name given to a disjunction group has no meaning beyond grouping. Any criteria that share the same group name are treated as belonging to the same disjunction group. Group names are case-sensitive.

DisjunctionGroup element

The DisjunctionGroup element is a child of the base Criterion type. It is available on every criterion element in the request, including StringCriterion, TimeRangeCriterion, and BooleanCriterion.

Element Type Cardinality Description
DisjunctionGroup xs:string 0..1 The case-sensitive name of the disjunction group this criterion belongs to. When present, the criterion is combined with other criteria in the same group using OR logic. When absent, the criterion is combined with all others using AND logic. Because the maximum length is not specified in the source; any non-empty string is valid.

Here is an example that returns invoices where the invoice number starts with "INV-" OR the original invoice number starts with "INV-":

CODE 
<InvoiceInfo>
  <InvoiceNo>
    <DisjunctionGroup>invoiceNumberGroup</DisjunctionGroup>
    <MatchType>StartsWith</MatchType>
    <CriterionValues>
      <CriterionValue>INV-</CriterionValue>
    </CriterionValues>
  </InvoiceNo>
  <OriginalInvoiceNo>
    <DisjunctionGroup>invoiceNumberGroup</DisjunctionGroup>
    <MatchType>StartsWith</MatchType>
    <CriterionValues>
      <CriterionValue>INV-</CriterionValue>
    </CriterionValues>
  </OriginalInvoiceNo>
</InvoiceInfo>

Match types

String criteria and numeric criteria use different match type enumerations.

String match types (StringMatchType)
Value Description
Exact The entire property value must match the criterion value. Case sensitivity depends on the property.
StartsWith The property value must begin with the criterion value. Case sensitivity depends on the property.

A StringCriterion can include up to 20 criterion values. The criterion is fulfilled if the property matches any one of the values.

Numeric match types (NumericMatchType)
Value Description
LessThan The property value must be strictly less than the criterion value.
LessThanOrEqualTo The property value must be less than or equal to the criterion value.
EqualTo The property value must equal the criterion value.
GreaterThan The property value must be strictly greater than the criterion value.
GreaterThanOrEqualTo The property value must be greater than or equal to the criterion value.
NotEqualTo The property value must not be equal to the searched value.
Time range criteria (TimeRangeCriterion)

Time range criteria don't use a MatchType element. Instead, provide the StartTime or EndTime as xs:dateTime values. Both bounds are inclusive. Either bound can be omitted to leave it open.

Element Type Cardinality Description
StartTime xs:dateTime 0..1 The beginning of the time range (inclusive). Omit for no lower bound. If you don't specifiy a time zone, it uses UTC.
EndTime xs:dateTime 0..1 The end of the time range (inclusive). Omit for no upper bound. If you don't specify a time zone, it uses UTC.
Note: For InvoiceDate, only the date part of the value is used for matching. Time and time zone information in InvoiceDate criteria are ignored.

Search invoices through the API

The SearchInvoices operation returns invoice metadata and references for all invoices matching your criteria. Document and attachment data are not included in the results. Use the returned references with GetInvoice to retrieve full document data.

  1. Build the SearchInvoices request and include the criteria you want to filter by.

    The following criteria are available as request elements:

    Element Type Occurrences Description
    DisjunctionGroup (within any criterion) xs:string 0..1 per criterion Groups criteria for OR logic. Criteria sharing the same group name are combined with OR and groups are combined with AND. When absent, the criterion uses AND logic. See Search criteria reference.
    InvoiceInfo tas:InvoiceInfo 0..1 Criteria for invoice metadata: Invoice number, invoice date, original invoice number, and purchase order numbers.
    IsPrincipalPartySupplier tas:BooleanCriterion 0..1 Filters by principal party role. Set to true to return only invoices where the supplier is the principal party, or false for the buyer. Omit to return invoices for either role.
    PrincipalParty tas: InvoicingPartyInfoCriteria 0..1 Criteria for the invoicing party that owns the stored invoice: Name, country code, and VAT number.
    Counterparty tas: InvoicingPartyInfoCriteria 0..1 Criteria for the counterparty: Name, country code, and VAT number.
    CustomProperties tas:CustomPropertyCriteria 0..1 Criteria for custom string properties of the invoice.
    CustomNumericProperties tas:CustomNumericPropertyC riteria 0..1 Criteria for custom numeric properties of the invoice.
    StoredTime Tas:TimeRangeCriterion 0..1 Criterion for the storage time range. If you don't specify a time zone, it uses UTC.
    MaxHits xs:int 1 The maximum number of results to return, capped at the server-configured limit. Must be non-negative.
    AllowFastSearch xs:boolean 1 If true, a faster search algorithm might be used. This algorithm might not include recently stored invoices. The default value is false.
    Offset xs:int 0..1 The number of results to skip from the start of the sorted result set. Use with MaxHits to paginate results. Must be non-negative.

    For a full explanation of match types, multiple values, AND/OR combination logic, and disjunction groups, see Search criteria reference.

    Example request:

    CODE 
    <SearchInvoices xmlns="http://www.trustweaver.com/trustarchive/storage/v1" 
xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1"> 
 <tac:TransactionId>3580f...</tac:TransactionId> 
 <InvoiceInfo> 
  <InvoiceNo> 
   <MatchType>Exact</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
    <CriterionValue>5678</CriterionValue> 
   </CriterionValues> 
  </InvoiceNo> 
  <InvoiceDate> 
   <StartTime>2017-02-27T00:00:00</StartTime> 
   <EndTime>2017-02-28T00:00:00</EndTime> 
  </InvoiceDate> 
  <OriginalInvoiceNo> 
   <MatchType>StartsWith</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
   </CriterionValues> 
  </OriginalInvoiceNo> 
  <PurchaseOrderNos> 
   <MatchType>StartsWith</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
    <CriterionValue>abc123</CriterionValue> 
   </CriterionValues> 
  </PurchaseOrderNos> 
 </InvoiceInfo> 
 <IsPrincipalPartySupplier> 
  <Value>true</Value> 
 </IsPrincipalPartySupplier> 
 <PrincipalParty> 
  <Name> 
   <MatchType>Exact</MatchType> 
   <CriterionValues> 
    <CriterionValue>sectionToSearchIn</CriterionValue> 
   </CriterionValues> 
  </Name> 
  <CountryCode> 
   <MatchType>Exact</MatchType> 
   <CriterionValues> 
    <CriterionValue>SE</CriterionValue> 
   </CriterionValues> 
  </CountryCode> 
  <VatNo> 
   <MatchType>StartsWith</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
   </CriterionValues> 
  </VatNo> 
 </PrincipalParty> 
 <Counterparty> 
  <Name> 
   <MatchType>Exact</MatchType> 
   <CriterionValues> 
    <CriterionValue>Counterparty1</CriterionValue> 
   </CriterionValues> 
  </Name> 
  <CountryCode> 
   <MatchType>Exact</MatchType> 
   <CriterionValues> 
    <CriterionValue>SE</CriterionValue> 
   </CriterionValues> 
  </CountryCode> 
  <VatNo> 
   <MatchType>StartsWith</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
   </CriterionValues> 
  </VatNo> 
 </Counterparty> 
 <CustomProperties> 
  <CustomProperty> 
   <Name>custProp1</Name> 
   <MatchType>StartsWith</MatchType> 
   <CriterionValues> 
    <CriterionValue>1234</CriterionValue> 
   </CriterionValues> 
  </CustomProperty> 
 </CustomProperties> 
 <CustomNumericProperties> 
  <CustomNumericProperty> 
   <Name>custNumProp1</Name> 
   <MatchType>GreaterThan</MatchType> 
   <CriterionValues> 
    <NumericCriterionValue>1</NumericCriterionValue> 
   </CriterionValues> 
  </CustomNumericProperty> 
  <CustomNumericProperty> 
   <Name>custNumProp2</Name> 
   <MatchType>LessThan</MatchType> 
   <CriterionValues> 
    <NumericCriterionValue>5</NumericCriterionValue> 
   </CriterionValues> 
  </CustomNumericProperty> 
 </CustomNumericProperties> 
 <StoredTime> 
  <StartTime>2017-02-27T09:08:28.3428624+01:00</StartTime> 
  <EndTime>2017-02-28T09:08:28.3428624+01:00</EndTime> 
 </StoredTime> 
 <MaxHits>10</MaxHits> 
 <Offset>0</Offset> 
</SearchInvoices>
  2. Send the request to the storage service endpoint using HTTPS with client certificate authentication.
  3. Process the SearchInvoicesResponse.

    The response contains the following elements:

    Element Type Occurrences Description
    Hits tas:InvoiceSearchHits 1 The matching invoices, ordered by invoice date descending. If two invoices have the same date, their relative order is arbitrary but consistent across repeated searches.
    MaxHitsExceeded xs:boolean 1 Returns true when it finds more invoices than the MaxHits value (taking Offset into account). Use Offset to retrieve the next page.

    Each hit in Hits contains the invoice Reference, document metadata (format and signature info), InvoiceInfo, supplier and buyer information, attachment metadata (without data), and custom properties. The actual document and attachment data are not included.

  4. Optional: If MaxHitsExceeded is true, repeat the request with an incremented Offset to retrieve the next page of results.
  5. Optional: To retrieve the full document data, call GetInvoice with a Reference from the search results.

The response returns invoice metadata and unique references for all invoices that match the criteria, up to the MaxHits limit. For error codes returned by this operation, see Storage service error codes.

Invoice reference operations

ListInvoiceReferences operation

Returns the references of all invoices stored in a named section. Supports pagination using MaxHits and Offset. The result list is stable: New invoices stored during a paginated sequence always appear at the end of the list and don't affect the order of existing results.

Request elements

Request type tas:ListInvoiceReferencesRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Section xs:string 1 The section name. Maximum 80 characters.
MaxHits xs:int 1 The maximum number of references to return, capped at the server-configured limit. Must be non-negative.
Offset xs:int 0..1 The number of results to skip from the start of the list. Set to the total number of references already retrieved to fetch the next page. Must be non-negative if specified.
Request example
CODE 
<ListInvoiceReferences
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <TransactionId
      xmlns="http://www.trustweaver.com/trustarchive/common/v1"
      >d651...</TransactionId>
    <Section>section1</Section>
    <MaxHits>5</MaxHits>
    <Offset>3</Offset>
  </Request>
</ListInvoiceReferences>
Response elements

Result type: tas:ListInvoiceReferencesResult

Element Cardinality Description
Hits 1 A collection of 32-digit hexadecimal Reference values ordered by stored time (ascending). This order is stable across paginated calls.
MaxHitsExceeded 1 Returns true when more invoices exist beyond the returned page. Increment Offset by MaxHits and repeat to retrieve the next page.
CODE 
<ListInvoiceReferencesResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Hits xmlns:a="http://www.trustweaver.com/trustarchive/common/v1">
      <a:Reference>ABCD1234</a:Reference>
      <a:Reference>ABCD1234</a:Reference>
      <a:Reference>ABCD1234</a:Reference>
    </Hits>
    <MaxHitsExceeded>true</MaxHitsExceeded>
  </Result>
</ListInvoiceReferencesResponse>
Error codes
For error codes returned by this operation, see Storage service error codes.

ListExpiringInvoiceReferences operation

Returns section invoices whose storage period ends within a specified date range. Use this operation to identify invoices approaching expiration beforeoffboarding or updating your UI. Supports pagination using MaxHits and Offset.

CAUTION: The result list is not stable. If new invoices are stored during a paginated sequence and those invoices fall within the expiry date range, the results might shift between pages. Keep this in mind if youwhen store invoices with short expiry dates while paginating.
Request elements

Request type tas:ListExpiringInvoiceReferencesRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Section xs:string 1 The section name with up to 80 characters.
ExpiryStartDate tac:OmittableDateTime 1 The earliest expiry date to include. Must be before the ExpiryEndDate. For the structure of omittable types, see Omittable types.
ExpiryEndDate tac:OmittableDateTime 1 The latest expiry date to include. Must be after ExpiryStartDate.
IncludeInvoicesWithExplicitExpiryDate xs:boolean 0..1 When true, invoices that have an explicit StoragePeriodEndDate set are included in results. When false or omitted, they are excluded.
MaxHits xs:int 1 The maximum number of results to return capped by the server-configured limit. Must be non-negative.
Offset xs:int 0..1 The number of results to skip. Set to the total number of results already retrieved to fetch the next page. If specified, it must be non-negative.
Request example
CODE 
<ListExpiringInvoiceReferences
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <TransactionId
      xmlns="http://www.trustweaver.com/trustarchive/common/v1"
      >d651...</TransactionId>
    <Section>section1</Section>
    <ExpiryStartDate>
      <i:Value>2020-04-30T11:18:02.3576459Z</i:Value>
    </ExpiryStartDate>
    <ExpiryEndDate>
      <i:Value>2020-05-30T11:18:02.3576459Z</i:Value>
    </ExpiryEndDate>
    <IncludeInvoicesWithExplicitExpiryDate>true</IncludeInvoicesWithExplicitExpiryDate>
    <MaxHits>100</MaxHits>
    <Offset>0</Offset>
  </Request>
</ListExpiringInvoiceReferences>
Response elements

Result type: tas:ListExpiringInvoiceReferencesResult

Element Cardinality Description
Hits 1 A collection of ExpiredInvoice entries. See the ExpiredInvoice elements entry.
MaxHitsExceeded 1 Returns true when more invoices exist beyond the returned page. Increase the Offset and repeat.
ExpiredInvoice elements
Element Cardinality Description
Reference 1 The 32-digit hexadecimal reference to the stored invoice.
InvoiceDate 1 The invoice date specified when the invoice is stored.
ExpiryDate 1 The date when the invoice storage period ends.
HasExplicitExpiryDate 1 Returns true when the invoice has an explicit StoragePeriodEndDate set.
CODE 
<ListExpiringInvoiceReferencesResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Hits>
      <ExpiredInvoice>
        <Reference>ABCD1234</Reference>
        <InvoiceDate>2019-08-10T00:00:00+02:00</InvoiceDate>
        <ExpiryDate>2024-08-10T00:00:00+02:00</ExpiryDate>
        <HasExplicitExpiryDate>false</HasExplicitExpiryDate>
      </ExpiredInvoice>
      <ExpiredInvoice>
        <Reference>ABCD1234</Reference>
        <InvoiceDate>2019-07-26T00:00:00+02:00</InvoiceDate>
        <ExpiryDate>2021-07-26T00:00:00+02:00</ExpiryDate>
        <HasExplicitExpiryDate>true</HasExplicitExpiryDate>
      </ExpiredInvoice>
    </Hits>
    <MaxHitsExceeded>true</MaxHitsExceeded>
  </Result>
</ListExpiringInvoiceReferencesResponse>
Error codes
For error codes returned by this operation, see Storage service error codes.

Update and inspect stored invoices

UpdateInvoice operation

This operation adds attachments, custom properties, or custom numeric properties to a stored invoice, or updates its storage period end date. At least one of these updates must be included. A request with no updates is rejected.

CAUTION: Setting an incorrect StoragePeriodEndDate might cause the document to be deleted before its legally required retention period ends. The date must be at least three days in the future.
Request elements

Request type tas:UpdateInvoiceRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Reference xs:string 1 The 32-digit hexadecimal reference to the stored invoice.
AddAttachments tas:Attachments 0..1 Attachments to add to the stored invoice. You can add up to seven attachments per invoice. The limit applies to the invoice as a whole, not only to what is added in this request.
AddCustomProperties tas:CustomProperties 0..1 Custom string properties to add. You can add up to seven custom properties per invoice.
AddCustomNumericProperties tas:CustomNumericProperties 0..1 Custom numeric properties to add. You can add up to seven custom numeric properties per invoice.
StoragePeriodEndDate tac:OmittableDateTime 0..1 The new storage period end date. Must be at least three days in the future (UTC). For the structure of omittable types, see Omittable types.
Request example
CODE 
<UpdateInvoice xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
               xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
    <AddAttachments>
      <Attachment>
        <Filename>Attachment1.xml</Filename>
        <MimeType>text/xml</MimeType>
        <Description>Attachment</Description>
        <Data>ABCD1234</Data>
      </Attachment>
    </AddAttachments>
    <AddCustomProperties>
      <Property>
        <Name>Property1</Name>
        <Value>Value1</Value>
      </Property>
    </AddCustomProperties>
    <StoragePeriodEndDate>
      <tac:Value>2030-01-01T00:00:00</tac:Value>
    </StoragePeriodEndDate>
  </Request>
</UpdateInvoice>
Response

A successful response contains no sub-elements:

CODE 
<UpdateInvoiceResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1"/>
Error codes
For error codes returned by this operation, see Storage service error codes.

GetDocumentMetadata operation

Retrieves metadata for a stored invoice or custom document. Only metadata fields are returned. Use GetInvoice to retrieve the full document content.

Request elements

Request type tas:GetDocumentMetadataRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Reference xs:string 1 The 32-digit hexadecimal reference to the stored invoice.
Request example
CODE 
<GetDocumentMetadata
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
  </Request>
</GetDocumentMetadata>
Response elements

Request type: tas:GetDocumentMetadataResult

Element Cardinality Description
Document 1 Document format and signature metadata. Document content data is not included.
DocumentPartyInfo 1 Information about the document owner: section name and country code.
Attachments 0..1 Metadata for all attached documents. Attachment content data is not included.
CustomProperties 0..1 Custom string properties associated with the document.
CustomNumericProperties 0..1 Custom numeric properties associated with the document.
StoredTime 1 The UTC date and time when the document is stored.
StoragePeriodEndDate 0..1 The date when the storage period ends. This is a calculated value and may change if configuration changes.
ClosureEvidences 0..1 Metadata for all closure evidence documents associated with the document. Closure evidence content data is not included. Omitted if there are no closure evidences.
CODE 
<GetDocumentMetadataResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result>
    <Document>
      <DocumentFormat>PDF</DocumentFormat>
      <ImplicitSignatureInfo>
        <SignatureFormat>PDF</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ImplicitSignatureInfo>
    </Document>
    </DocumentPartyInfo> 
      <Attachments> 
         <Attachment> 
            <Filename>attached.xml</Filename> 
            <MimeType>text/xml</MimeType> 
            <Description>Some XML attachment</Description> 
         </Attachment> 
      </Attachments> 
      <CustomProperties> 
         <Property> 
            <Name>MyProperty</Name> 
            <Value>some value</Value> 
         </Property> 
      </CustomProperties> 
      <CustomNumericProperties> 
         <Property> 
            <Name>MyNumericProperty</Name> 
            <Value>1234</Value> 
         </Property> 
      </CustomNumericProperties> 
      <StoredTime>2010-09-07T13:15:44Z</StoredTime> 
      <StoragePeriodEndDate>2020-09-06T00:00:00</StoragePeriodEndDate> 
   </Result> 
</GetDocumentMetadataResponse>
Error codes
For error codes returned by this operation, see Storage service error codes.

Create a download token through the API

The CreateToken operation generates an access token that allows a single download of a specific invoice or document without requiring client certificate authentication. The token is valid for one download only and expires 30 days after creation.

  1. Build the CreateToken request with the reference of the invoice or document to download.

    Request type tas:CreateTokenRequest extends tac:TrustArchiveRequest.

    Element Type Cardinality Description
    Reference xs:string 1 The 32-digit hexadecimal reference to the stored invoice or document.

    Example request:

    CODE 
    <CreateToken
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>4685...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
  </Request>
</CreateToken>
  2. Send the request to the storage service endpoint using HTTPS with client certificate authentication.
  3. Retrieve the token from the CreateTokenResponse, then pass it to the recipient so they can download the document.

    Result type: tas:CreateTokenResult.

    Element Type Description
    Token xs:string The generated access token, which is valid for one download within 30 days of creation.

    Example response:

    CODE 
    <CreateTokenResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result>
    <Token>1234...</Token>
  </Result>
</CreateTokenResponse>
    CAUTION:

    The token is valid for a single download only and must be concatenated with a specific URL. After it is used or after 30 days, it cannot be reused. Generate a new token if another download is needed.

    Available URLs by environment:

You can now share the generated token with the recipient. They can use it to download the specified document once, without authentication.

Tip:

For error codes returned by this operation, see Storage service error codes.

Download all section documents

The section must be in the LockedForArchiving status before you can start a bulk download. Call LockSection to lock the section. Locking prevents issues between storing new documents and listing the documents of a section.

Note: You can download documents from a section that is not locked, but the listing might not include all documents if new invoices are stored at the same time.

A bulk download is typically used during offboarding, the process of permanently removing documents from the TrustWeaver storage service. TrustWeaver provides two options:

  • An automatic download using the OffloadSection endpoint.

  • A self-service approach using standard API operations.

  1. To download all documents in a section (automatic download):
    1. Send an HTTPS GET request to the following URL:
      CODE 
      https://<fqdn>/OffloadSection.ashx?section=<section>
      <fqdn>
      The storage service URL provided during onboarding
      <section>
      The section name relative to the caller's authorized area
    2. The request requires HTTPS with client certificate authentication, the same as the storage and admin web services.
    3. The response is a single XML document containing GetInvoiceResult elements for all invoices in the section, wrapped in an OffloadSectionResult root element. To support streaming of large data sets, this operation is implemented as a web endpoint rather than a standard web service operation.

      Example response structure:

      XML 
      <?xml version="1.0" encoding="utf-8"?>
<OffloadSectionResult
  sectionPath="/archive/area1/section4"
  friendlyName="Locked section"
  countryOfEstablishment="DE"
  state="LockedForArchiving"
  xmlns="http://www.trustweaver.com/ta-hub-services" />
      Note: The example shows the wrapper element only. In a real response, GetInvoiceResult elements for each invoice are included inside the wrapper.
      Attribute Description
      sectionPath An identifier for the storage section that you can append to the archive GUI base URL provided during onboarding to access the section directly in the archive GUI.
      friendlyName A human-readable name for the section used in searches for invoices where this invoicing party is involved. Absent if not set during section registration.
      countryOfEstablishment The ISO 3166 alpha-2 code for the country of establishment of the invoicing party. Used when determining the storage period for invoices. Absent if not set during section registration.
      state The current state of the section. Possible values: Registered, Enabled, LockedForArchiving, or ClosedForArchiving.
  2. If you prefer to implement the download yourself (self-service download), follow these steps:
    1. Call GetSectionInfo and confirm the section is in the LockedForArchiving state.
    2. Call ListInvoiceReferences to get a list of references for the section's documents. Set MaxHits to the number of references to retrieve per call. Set Offset to the total number of references already retrieved (use 0 for the first call).
    3. Call GetInvoice for each reference returned.
    4. If MaxHitsExceeded in the ListInvoiceReferences response is true, repeat from second step with the updated Offset.

After downloading all documents, call CloseSection to put the section in the ClosedForArchiving state. This hides all documents in the section and starts a grace period before permanent deletion. You must close the section before youpermanently delete the documents.

Note:

The final step in authorizing permanent deletion of the section's documents (offboarding) is an out-of-band process. Contact Sovos Support to complete this irreversible step.

For the full request and response reference for ListInvoiceReferences and ListExpiringInvoiceReferences, see Invoice reference operations.

Trustweaver

Last updated: September 30, 2026