Sign documents

For post-audit countries, document signing and validation are handled through the signing web services interface.

The signing service exposes three operations relevant to post-audit compliance: Sign, Validate, and ValidateArchive. All operations use SOAP 1.1 messaging over HTTPS and require a valid client certificate for authentication.

Technically, both signing and validation operations in post-audit flows are executed as corroborate calls to the storage service: the sign operation maps to a corroborate call in sign mode, and the Validate operation maps to a corroborate call in validate mode. For post-audit countries, because synchronous processing applies, UseBranchKey must be set to false and AsyncBehaviorMode must be set to NotExpected.

You can also call the corroborate operation directly on the storage service for post-audit operations, without going through the signing service interface.

Note:

Use this approach when your integration already uses the storage service or when you want to combine signing and validation in a single call.

Services and operations

The signing service WSDL is available at the following address:

CODE

https://<Host Address>/ts/svs.asmx?WSDL

https://<Host Address>/ts/svs.asmx?WSDL

It exposes two ports. Use only the SwitchServiceSoap port (SOAP 1.1 binding). Don't use the SwitchServiceSoap12 port.

The following operations are covered in this section:

Sign: Applies a digital signature to a document on behalf of the supplier. The operation returns the signed document and, for job types that produce long-term verifiable signatures such as CADESA and XADESA), it also returns the audit data bundled with the document. See Sign a document through the API.
Validate: Verifies the integrity and authenticity of a signed document's signature on behalf of the buyer. The operation returns a validation outcome and, when requested, full audit details. See Validate a document through the API.
ValidateArchive: Confirms that a signature remains valid after long-term storage. This operation is not required as part of the initial flow but is recommended for periodic audit processes. See Validate a signature through the API.

Signing and archiving workflow

The typical outbound post-audit workflow uses two services in three steps:

Step 1: Sign: Call the Sign operation on the signing service to apply a digital signature. See Signing and archiving workflow.
Step 2: Store: Call the StoreInvoice operation on the storage service to archive the signed document. The operation returns a 32-digit hexadecimal reference required for all retrieval operations. See Store an invoice through the API.
Step 3: Validate archive (optional): Call the ValidateArchive operation on the signing service to confirm that the signature remains valid. See Validate a signature through the API.

Note: For document types that require individual party signing keys or a clearance flow, use the corroborate operation on the storage service instead of a direct sign call. A separate storeInvoice call is still required after corroborate. See Clearance e-invoicing.

Integration scenarios

The integration scenarios determine how the hub structures its sign and validate calls. The choice depends on which trading parties the hub serves and whether sign and validate are executed in the same call or separately. These scenarios are covered in Post-audit process flows.

Compliance Map and country codes

The Compliance Map specifies the signature format and document format required for each supported country and document type. The SenderInfo.CountryCode and ReceiverInfo.CountryCode parameters in each corroborate request must be set to valid ISO 3166-1 alpha-2 country codes listed in the Compliance Map. Only country codes included in the Compliance Map may be submitted to the signing service for post-audit processing. Contact Sovos Support to confirm the country scope applicable to your agreement.

Sign a document through the API

Before signing a document, confirm the following:

You have a valid client certificate configured for the sign operation.
You have established an SSL connection to the TrustWeaver server.
You know the SenderTag and ReceiverTag values for your signing policy.
Your document format (InputType) and signature format (OutputType) combination is valid. See Job types and signature profiles.
If your source document requires format conversion before signing, use Transform a document through the API.

The sign operation sends a document to TrustWeaver and returns a signed document. Documents are transmitted as Base64-encoded strings.

Build a SignRequest with the required elements.

The following table describes all SignRequest elements:


Element	Required	Type	Description
InputType	Yes	string	A document format code such as `GENERIC`, `XML`, or `PDF`. See Supported countries and formats for all format codes.
OutputType	Yes	string	A signature format code such as `SMIME` or `PDF`). See Send documents for all format codes.
Document	Yes	Base64 string	The document to sign, encoded as Base64.
SenderTag	Yes	string	Identifies the sender's country. Combined with `ReceiverTag` to select the signing policy.
ReceiverTag	Yes	string	Identifies the recipient's country. Combined with `SenderTag` to select the signing policy.
JobType	No	string	Specifies the signing profile. See Job types and signature profiles. If not specified, a signature without integrated validation data is generated (CAdES-T or XAdES-T).
AgreementIdentifier	No	string (max 256 chars)	Logged identifier used to group transactions. For example, a pricing model agreed in contract with Sovos. Allowed characters: A-Z, a-z, 0-9, hyphen, @, dot, and underscore.
SignerIdentifier	No	string (max 256 chars)	Reserved for future use. Associates a signing transaction with a specific signing entity for PKCS7-based formats. Same character restrictions as `AgreementIdentifier`.
ClientData	No	string (max 64 chars)	Opaque logged string. Meaning is defined by the client. Allowed characters: A-Z, a-z, 0-9, hyphen, semicolon, @, dot, underscore.

Send the request as a SOAP 1.1 message to the SwitchServiceSoap port.
Example request:
CODE
<SignRequest xmlns="http://www.trustweaver.com/tsswitch"> <InputType>GENERIC</InputType> <OutputType>SMIME</OutputType> <Document>MII…</Document> <SenderTag>SE</SenderTag> <ReceiverTag>DE</ReceiverTag> <AgreementIdentifier>agreement1</AgreementIdentifier> <ClientData>abc;123</ClientData> </SignRequest>
```
<SignRequest xmlns="http://www.trustweaver.com/tsswitch">
  <InputType>GENERIC</InputType>
  <OutputType>SMIME</OutputType>
  <Document>MII…</Document>
  <SenderTag>SE</SenderTag>
  <ReceiverTag>DE</ReceiverTag>
  <AgreementIdentifier>agreement1</AgreementIdentifier>
  <ClientData>abc;123</ClientData>
</SignRequest>
```
Process the SignResponse.
Example response:
CODE
<SignResult xmlns xmlns="http://www.trustweaver.com/tsswitch"> <Result> <Code>OK</Code> <Desc>The operation completed successfully</Desc> </Result> <SignedDocument>MII…</SignedDocument> <Details> <details> ... </details> </Details> </SignResult>
```
<SignResult xmlns xmlns="http://www.trustweaver.com/tsswitch"> 
	<Result> 
		<Code>OK</Code> 
		<Desc>The operation completed successfully</Desc> 
	</Result> 
	<SignedDocument>MII…</SignedDocument> 
	<Details> 
	<details> 
		... 
	</details> 
	</Details> 
</SignResult>
```
Note:
See Sign response reference for response elements, result codes, and SOAP fault codes.

Sign response reference

Response elements

A SignResponse can contain up to four elements:


Element	Description
Result	Always returned. Contains a `Code` and a `Desc`.
SignedDocument	Contains the signed document as a Base64-encoded string. Not set for PKCS7D, since the caller already holds the detached document.
Archive	Contains detached evidence data. Only returned for signature formats PKCS7D and EANCOM.
Details	Contains signature details. Only returned when the `JobType` is CADESA, XADESA, PADESLTV, or EVIDENCE.

Response elements by signature format


Signature format	Result	SignedDocument	Archive
PKCS7	Always	Always	Never
PKCS7D	Always	CADEST	CADESA
SMIME	Always	Always	Never
PDF	Always	Always	Never
XMLSIG	Always	Always	Never
XMLCON	Always	Always	Never
XMLSIGED	Always	Always	Never
IDEAL	Always	Always	EVIDENCE
GS1AT	Always	Always	EVIDENCE
AECOC	Always	Always	EVIDENCE
FACTURAE	Always	Always	Never
FATTURAPA	Always	Always	Never
ESLOG	Always	Always	Never
MYUBL	Always	Always	Never
MYJSON	Always	Always	Never
CII	Always	Always	Never
BIS3	Always	Always	Never

Result codes


Code	Desc	Description
OK	The operation completed successfully	The document was signed and returned in the response.
SignerInvalid	<Descriptive message>	The signing certificate is invalid (revoked, expired, or not trusted). Only returned when an archive for long-term validation is created (job type CADESA, XADESA, PADESLTV, or EVIDENCE).

Note:

For error codes this operation returns, see Sign error reference.

Response example

CODE

<SignResult xmlns="http://www.trustweaver.com/tsswitch">
  <Result>
    <Code>OK</Code>
    <Desc>The operation completed successfully</Desc>
  </Result>
  <SignedDocument>MII…</SignedDocument>
  <Details>
    <details>
      ...
    </details>
  </Details>
</SignResult>

<SignResult xmlns="http://www.trustweaver.com/tsswitch">
  <Result>
    <Code>OK</Code>
    <Desc>The operation completed successfully</Desc>
  </Result>
  <SignedDocument>MII…</SignedDocument>
  <Details>
    <details>
      ...
    </details>
  </Details>
</SignResult>

PDF countersignatures

A PDF countersignature adds an additional signature to an already-signed PDF document.

To create a PDF countersignature, invoke the sign operation with a document that already contains a PDF signature. All valid job type combinations are supported, including no job type, which generates a CAdES-T signature.

Job types and signature profiles

Job types control the signing profile applied to a document and determine whether long-term validation data is included in the response.

The optional JobType element in a sign or validate request specifies what type of signature or validation processing to apply. The valid job types and their compatible signature formats are described in the following sections.

Sign job types

The following table shows which job types are valid for each signature format in a sign request:


Job type	PKCS7	PKCS7D	SMIME	XMLSIG	PDF	XMLCON	XMLSIGED, CII, BIS3	IDEAL, GS1AT, AECOC	FACTURAE	FATTURAPA
BASIC							Yes
XADESBES							Yes
XADESEPES				Yes		Yes	Yes		Yes	Yes
XADEST							Yes
CADESEPES	Yes	Yes	Yes					Yes
CADESA	Yes	Yes	Yes					Yes
XADESA				Yes		Yes	Yes
PADESEPES					Yes
PADESLTV					Yes
EVIDENCE								Yes

Job type behavior

XADESA, CADESA, PADESLTV, EVIDENCE: Generates a validation details element and a signature suitable for long-term validation.
XADESEPES, CADESEPES, PADESEPES: Generates a signature conforming to the XAdES-EPES, CAdES-EPES, or PAdES-EPES profile.
BASIC: Applies to enveloped XML signature format (XMLSIGED) only. Generates a pure XMLDSIG signature without any XAdES extensions.
XADESBES: Applies to XMLSIGED only. Generates a signature according to the XAdES-BES profile.
XADEST: Applies to XMLSIGED only. Generates a signature conforming to the XAdES-T profile.
EVIDENCE: Applies to formats not compatible with any other job type. Creates a detached CAdES-A using the original signature from the signed document.

If no job type is specified for PKCS7, PKCS7D, SMIME, XMLSIG, XMLCON, XMLSIGED, PDF, FACTURAE, or FATTURAPA, a signature without integrated validation data is generated (CAdES-T or XAdES-T).

If no job type is specified for IDEAL, GS1AT, or AECOC, no detached evidence data is created, but the generated EDIFACT signature is the same as when specifying job type EVIDENCE.

Validate job types

The following job types are valid in a validate request:


Job type	PKCS7	PKCS7D	SMIME	XMLSIG	PDF	XMLCON	XMLSIGED	IDEAL, GS1AT, AECOC	FACTURAE	FATTURAPA	ESLOG
CADESA	Yes	Yes	Yes	Yes
XADESA						Yes	Yes	Yes
PADESLTV					Yes
EVIDENCE								Yes	Yes
DETAILS	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes

Validate a document through the API

Before validating a document, confirm the following:

You have a valid client certificate authorized for validation operations.
You know the signature format (InputType) of the signed document.
For detached PKCS7 signatures (PKCS7D), you have both the detached signature and the original unsigned document.

The validate operation verifies a signature and optionally creates or recreates a long-term verifiable archive. The behavior depends on the JobType and whether the document already contains long-term validation data.

Build a ValidateRequest with the required elements.

The following table describes all ValidateRequest elements:


Element	Required	Type	Description
InputType	Yes	string	A signature format code such as `SMIME`, `PDF`). See Send documents.
OutputType	Yes	string	A document format code such as `GENERIC` for the response.
SignedDocument	Yes	Base64 string	The signed document. For PKCS7D, this element holds only the detached signature and the original document must be in the `Document` element.
SenderTag	Yes	string	Identifies the sender and must be combined with `ReceiverTag` to select the validation policy. If present in the sender and the ReceiverTag, the request value takes precedence. Sender and receiver tags must use the same values as during signing. This is the expected configuration for Independent Software Vendors (ISVs) that sign documents and then validate them on behalf of the buyer. To validate an externally signed document: Use `EU-EU` to validate an externally signed document or verify that the signature is complaint with the European Trusted List. Use `XT-XT` to make a generic validation.
ReceiverTag	Yes	string	Identifies the recipient. Same rules as `SenderTag`.
JobType	No	string	Specifies validation processing. See Job types and signature profiles. Note: If `JobType` is omitted and the input document already contains a long-term verifiable signature (CAdES-A, XAdES-A, PAdES-LTV, or detached evidence data), TrustWeaver treats it as a standard signature and validates it without creating or returning a validation details element. The existing long-term verifiable signature is not upgraded or replaced.
Document	No	Base64 string	Required when `InputType` is PKCS7D. Specifying this element for any other signature type results in a client fault.
AgreementIdentifier	No	string (max 256 chars)	Logged identifier for grouping transactions. Same format restrictions as in the sign operation.
ClientData	No	string (max 64 chars)	Opaque logged string. Same format restrictions as in the sign operation.
ExcludeOriginalDocument	No	boolean	When `true`, the original unsigned document is not included in the response. Default is `false`.

Send the request as a SOAP 1.1 message to the SwitchServiceSoap port.
Example request:
CODE
<ValidateRequest xmlns="http://www.trustweaver.com/tsswitch"> <InputType>SMIME</InputType> <OutputType>GENERIC</OutputType> <SignedDocument>MII…</SignedDocument> <SenderTag>SE</SenderTag> <ReceiverTag>DE</ReceiverTag> <AgreementIdentifier>agreement1</AgreementIdentifier> <ClientData>abc ;123</ClientData> <ExcludeOriginalDocument>false</ExcludeOriginalDocument> </ValidateRequest>
```
<ValidateRequest xmlns="http://www.trustweaver.com/tsswitch"> 
	<InputType>SMIME</InputType> 
	<OutputType>GENERIC</OutputType> 
	<SignedDocument>MII…</SignedDocument> 
	<SenderTag>SE</SenderTag> 
	<ReceiverTag>DE</ReceiverTag> 
	<AgreementIdentifier>agreement1</AgreementIdentifier> 
	<ClientData>abc ;123</ClientData> 
	<ExcludeOriginalDocument>false</ExcludeOriginalDocument> 
</ValidateRequest>
```

Process the ValidateResponse.

A ValidateResponse can contain the following elements:


Element	Description
Result	Always returned. Contains a `Code` and a `Desc`. Possible codes: `OK`, `SingatureInvalid`, and `SignerInvalid`.
Document	The original unsigned document as a Base64-encoded string. Not returned for PKCS7D or when `ExcludeOriginalDocument` is `true`.
Archive	Contains the resulting document from the validation such as CAdES-A, XAdES-A, or PADESLTV. Only returned when `JobType` is CADESA, XADESA, or EVIDENCE. Only if requested.
Details	Contains signature details that are identical to the European-defined "Validation Report" that we produce as part of our trusted service. Only returned when request and when `JobType` is CADESA, XADESA, PADESLTV, EVIDENCE, or DETAILS.

For error codes returned by this operation, see Sign error reference.

Validate a signature based on included audit data through the API

Before validating a signature based on included audit data, make sure that:

You have the signed document with archive data in the CAdES-A, XAdES-A, or detached evidence data format, or you have the original signed document.
You know the signature format (InputType) of the archived document.
Note:
Validating a signature is also available through the Archive GUI.

The ValidateArchive operation validates a signature along with its validation data archive. You should use this operation to validate documents that were previously signed with a long-term verifiable signature.

Build a ValidateArchiveRequest with the required elements.

The following table describes the ValidateArchiveRequest elements:


Element	Required	Type	Description
InputType	Yes	string	A signature format code such as `SMIME`.
OutputType	Yes	string	A document format code such as `GENERIC`) for the response.
JobType	No	string	Only DETAILS is supported. When specified, the `Details` element is included in the response.
SignedDocument	No	Base64 string	Holds the encapsulated CAdES-A, XAdES-A, or PAdES_LTV long-term verifiable signature, the signed document part of detached evidence data, or the document part of a detached PKCS7 CAdES-A signature. If this element contains CAdES-A, XAdES-A, or detached evidence data, don't include a `ValidationResult` element.
Archive	No	Base64 string	Holds detached evidence data or a detached PKCS7 signature with CAdES-A profile. Required for PKCS7D and EANCOM-based formats.
ValidationResult	No	XML	Used when `SignedDocument` is not in the CAdES-A, XAdES-A, or detached evidence format. Don't include both `ValidationResult` and a CAdES-A or XAdES-A signature in `SignedDocument`.

The following table shows which elements are required by signature format:


Signature format	JobType	SignedDocument	Archive
PKCS7	NONE \| DETAILS	Always	Never
PKCS7D	NONE \| DETAILS	Always	Always
SMIME	NONE \| DETAILS	Always	Never
PDF	NONE \| DETAILS	Always	Never
XMLSIG	NONE \| DETAILS	Always	Never
XMLCON	NONE \| DETAILS	Always	Never
XMLSIGED	NONE \| DETAILS	Always	Never
IDEAL	NONE \| DETAILS	Always	Always
GS1AT	NONE \| DETAILS	Always	Always
AECOC	NONE \| DETAILS	Always	Always
FATTURAPA	NONE \| DETAILS	Always	Never

Send the request as a SOAP 1.1 message to the SwitchServiceSoap port.
Example request:
CODE
<ValidateArchiveRequest xmlns="http://www.trustweaver.com/tsswitch"> <InputType>SMIME</InputType> <OutputType>GENERIC</OutputType> <SignedDocument>MII…</SignedDocument> <ValidationResult>…</ValidationResult> </ValidateArchiveRequest>
```
<ValidateArchiveRequest xmlns="http://www.trustweaver.com/tsswitch"> 
	<InputType>SMIME</InputType> 
	<OutputType>GENERIC</OutputType> 
	<SignedDocument>MII…</SignedDocument> 
	<ValidationResult>…</ValidationResult> 
</ValidateArchiveRequest>
```

Process the ValidateArchiveResponse.

The response contains the following elements:


Element	Description
Result	Always returned. Contains a `Code` and a `Desc`.
Document	The original document as a Base64-encoded string. Not returned for detached PKCS7 with the CAdES-A profile (PKCS7D).
Details	Signature details equivalent to an European style validation report. Only returned when `JobType` DETAILS was specified in the request.

For error codes returned by this operation, see Sign error reference.

Post-audit process flows

TrustWeaver supports integration scenarios for post-audit e-invoicing, which differ by the hub's role and whether signing and validation occur in separate or combined API calls.

In post-audit countries, a hub typically acts as an intermediary between suppliers and buyers, processing e-invoices on behalf of both parties. The hub uses TrustWeaver to sign invoices on behalf of the supplier and validate them on behalf of the buyer. The integration scenario depends on whether the hub serves both parties (outbound and inbound flows) or only one.

The corroborate operation is used as an alternative to all signing and validation calls in post-audit flows. The following key parameters apply across all post-audit scenarios:

AsyncBehaviorMode must be set to NotExpected. Post-audit corroboration is always synchronous.
UseBranchKey must be set to false. Branch keys are not applicable for post-audit countries.
TransactionId must be set to a Universally Unique Identifier (UUID) for each transaction submitted.
SenderInfo.CountryCode and ReceiverInfo.CountryCode must be set to valid ISO 3166-1 alpha-2 country codes from the Sovos Compliance Map. See Supported countries for the country code requirements and exceptions.

Scenario 1: Separate sign and validate calls

In this scenario, the hub makes two separate corroborate calls: one in sign mode on behalf of the supplier when issuing the invoice, and one in validate mode on behalf of the buyer to verify the invoice.

Note: The signing service's sign operation maps technically to a corroborate call in sign mode (SigningFor = Sender, ValidatingFor = NotSpecified). The validate operation maps to a corroborate call in validate mode (SigningFor = NotSpecified, ValidatingFor = Receiver).

Not all process steps apply to every real-world implementation. The extent depends on which services the hub provides and which the trading parties use. The process steps are as follows:

The supplier provides unsigned invoice data to the hub in a predetermined format. The hub maps and transforms the invoice data into the final format required for signing. This format is usually decided between the trading parties, typically in consultation with the hub.
The hub sends the invoice data to TrustWeaver with the proper country parameters and a corroborate request in sign mode. TrustWeaver performs supplier services, which include the required signatures according to the Compliance Map, signed certificate validation data from the applicable certification authority, and timestamps associating a secure time assertion with the signing step.
The supplier's e-invoice is archived. This can be done in one of two ways:
- The hub stores the signed original invoice on behalf of the supplier using a StoreInvoice call. If the supplier outsources archiving, the proper legal instruments must be in place.
- The hub returns the signed invoice to the supplier for the supplier to archive it directly.
The hub sends the signed invoice to TrustWeaver with a corroborate request in validate mode on behalf of the buyer. TrustWeaver performs buyer services, which include cryptographic verification of the signature and replacement of the validation data and timestamp with new signed validation data from the applicable certification authority.

Note: Sovos recommends waiting 20 seconds or more before sending the signed invoice to the buyer validation step. This introduces a grace period between signing and validation, which increases the quality of the returned validation data. This wait is not technically required.
The buyer's e-invoice is archived. This can be done in one of two ways:
- The hub stores the signed and validated invoice on behalf of the buyer using a StoreInvoice call. If the buyer outsources archiving, the proper legal instruments must be in place.
- The hub sends the signed and validated invoice to the buyer for the buyer to archive it directly.
A tax inspector may require access to the stored signed invoices at any time for audit purposes.

Scenario 2: Combined sign and validate call

In this scenario, the hub makes one corroborate call in sign and validate mode instead of two separate calls. This combines the supplier signing and the buyer validation into a single request (SigningFor = Sender, ValidatingFor = Receiver).

The process steps are equivalent to those in Scenario 1. The only difference is that a single corroborate call handles both signing and validation. The response includes the signed document and a ValidationOutcome element with code Ok when the combined operation succeeds.

Note: The combined Sign and Validate call eliminates the separate timing consideration between signing and validation that applies in Scenario 1. Use this scenario when the hub manages both supplier and buyer services in a single transaction and the grace period between signing and validation is not a compliance requirement.

Outbound-only process

When the hub serves only a supplier (outbound flows), the process follows the outbound steps of Scenario 3 (steps 1-4) and ends with the delivery of the signed invoice. There is no separate inbound flow, and no validation call is made on behalf of a buyer. The five steps are: Transmit invoice data, convert to document format, sign (corroborate), store (optional), and deliver the signed invoice.