Clear documents

Clearance is a subprocess of corroboration. In clearance countries, TrustWeaver submits the document to the relevant tax authority on behalf of the supplier.

The document is not returned to your system until the tax authority authorizes it.

Clearance flows are always handled through the corroborate operation on the storage service. There is no direct equivalent in the signing service for clearance operations.

Corroboration with clearance has a precisely defined meaning: An electronic invoice is signed and cleared with the relevant authority on behalf of the supplier. Inbound and delivery scenarios can vary depending on the country of issue. This is distinct from corroboration without clearance, where the calling system defines the meaning of the operation.

The form of the tax authority response varies by country. In some countries, clearance information is embedded in the returned document. For example, a government-issued signature or authorization identifier added to the invoice. In others, the tax authority returns a separate signed response, or generates distinct artifacts such as a reference number or QR code that accompany but are not part of the original document. See Country-specific e-invoicing requirements.

When clearance applies

Clearance is triggered when a clearance-specific signature format is used in the corroborate request. The Compliance Map specifies which signature formats require clearance for each country and document type. The following constraints apply whenever a clearance signature format is used:

The signature format can only be used by and for parties in the relevant country.
The format is highly specialized and tightly coupled with the invoice document format required by that country.
The same invoice can't be processed more than once.
Signing can only be performed on behalf of the supplier. Clearance is requested as part of the sign operation.
Validation can only be performed on behalf of the buyer.

Corroborate operation and clearance flow

All clearance flows use the corroborate operation on the storage service. Corroboration applies the signature, submits the document to the tax authority for clearance, and produces audit data in a single operation. A separate StoreInvoice call is required to archive the result after corroborate returns.

TrustWeaver may process a corroborate request asynchronously when clearance with a tax authority is required. In this case, the response includes an AsyncState element that must be used in subsequent polling requests. For details on the asynchronous processing behavior, see About the Corroborate operation.

For individual signing keys required by specific countries and document formats, such as the Mexican CFDI or the South Korean invoices, provide the key using one of two approaches in CorroborationSpec:

Key references: Include one or more tac:Reference values in the KeyReferences element. Each reference is a 32-digit hexadecimal identifier of a key stored using the StoreCryptoKey operation.
Branch key: Set UseBranchKey to true and include the party's CountryCode and TaxId in SenderInfo. TrustWeaver looks up the registered branch for that tax entity and uses its associated key. Don't include explicit key references when using a branch key.

Prerequisites for clearance operations

Before submitting a document for clearance, make sure that:

You have a valid client certificate configured for storage service access.
The storage section for the signing or validating party is registered and enabled. See Configure storage sections.
If the operation requires individual signing keys such as the Mexican CFDI or the South Korean invoices, the keys are stored in the correct storage section. See About stored cryptographic keys.

If the operation requires branch registration, the relevant branch is registered for the invoicing party. Branch registration requirements vary by country:


Country	Section registration required	Branch registration required	Notes
Mexico	Yes	Yes	Branch holds the individual signing key.
India	Yes	Yes	Branch holds GST portal credentials for IRP access.
South Korea	Yes	Yes	Branch holds the private signing key.
Italy	Yes	No	Signing key is Sovos-managed; no branch needed.
Turkey	Yes	No	Signing is handled without a party-specific key.

Country-specific requirements

The clearance process varies by country. Each clearance country has specific document format requirements, branch registration prerequisites, and in some cases country-specific API parameters.

Clearance response and document status

When TrustWeaver submits a document for clearance, the document status changes to pending until the tax authority responds. After the tax authority approves the document, the status changes to cleared and the document is legally valid. If the tax authority rejects the document, your system must resolve the rejection and resubmit. For the full list of status values and error codes, see Error handling and status codes.

About the corroborate operation

Using individual signing keys

For some countries and document formats such as the Mexican CFDI and the South Korean invoices, TrustWeaver requires a cryptographic key belonging to the signing party rather than a Sovos-managed key. Provide the key using one of the following approaches in CorroborationSpec:

Key references: Include one or more tac:Reference values in the KeyReferences element. Each reference is a 32-digit hexadecimal identifier of a key stored using the StoreCryptoKey operation. You can also provide the signing party section name in SenderInfo/Name to restrict key selection to keys in that section.
Branch key: Set UseBranchKey to true and include the party's CountryCode and TaxId in SenderInfo. TrustWeaver looks up the registered branch for that tax entity and uses its associated key. Don't include explicit key references when using a branch key.

Note: TrustWeaver determines whether individual keys are required based on the policy tag values. You don't need to track this. Provide the key or branch information and TrustWeaver applies the correct selection logic.

Asynchronous processing

TrustWeaver may process a corroborate request asynchronously, such as when clearance with a tax authority is required. When this occurs, the response contains an AsyncState element and other response elements might be absent. Poll by resending the request with the AsyncState value from the previous response and omitting Document, SenderInfo, ReceiverInfo, and CorroborationSpec.

Note: Set AsyncBehaviorMode in the initial request to indicate that your client can handle asynchronous responses. TrustWeaver makes the final decision on whether to process the request asynchronously.

Error codes

The client error codes are specific to the corroborate operation. Common storage service error codes also apply. See Storage service error codes.

Corroborate a document through the API

Before corroborating a document, make sure that:

You have a valid client certificate configured for storage service access.
The storage section for the signing or validating party is registered and enabled.
If the operation requires individual signing keys such as the Mexican CFDI or the South Korean invoices, the keys are stored in the correct storage section.
If the operation involves clearance, the relevant branch is registered for the invoicing party.
To confirm a trading partner's tax identifier before storing, use Validate a tax identifier through the API.

The corroborate operation signs and validates a document and creates long-term audit data on behalf of one or more transacting parties. Use it when the storage service must handle the signature operation, such as when individual party keys or clearance flows are involved.

Choose the invocation mode that matches your operation.

The mode is determined by the values of SigningFor, ValidatingFor, and RegisteringFor in the CorroborationSpec element:


Mode	CorroborationSpec settings	Description
Sign	`SigningFor` = Sender or Receiver; `ValidatingFor` = NotSpecified	Applies a signature to an unsigned document. The response includes the signed document. `ValidationOutcome` is never returned.
Sign and validate	`SigningFor` = Sender or Receiver; `ValidatingFor` = Sender or Receiver	Applies a signature and immediately validates it. The response includes the signed document and a `ValidationOutcome` element with code `Ok`. Any other validation result is treated as an internal error.
Validate	`SigningFor` = NotSpecified; `ValidatingFor` = Sender or Receiver	Validates an existing signature. The input document must be signed. The `ValidationOutcome` element is always returned and may contain codes other than `Ok`. New audit data is returned only if requested and validation succeeds.
Register	`SigningFor` = NotSpecified; `ValidatingFor` = NotSpecified; `RegisteringFor` = Sender or Receiver	Registers a response to a signed document with a third party, such as a tax authority. Used by the receiver to acknowledge a cleared invoice. The input document must be signed. The `RegistrationOutcome` element is always returned.

Build a CorroborateRequest with the required elements.

The following table describes the CorroborateRequest elements. All elements are optional when polling an asynchronous operation.


Element	Type	Cardinality	Description
Document	`tas:Document`	0..1	The document to process. Must be unsigned when signing and must be signed when validating or registering. Required unless polling an asynchronous operation.
SenderInfo	`tas:CorroborationPartyInfo`	0..1	Information about the sender, including section name and policy tag. Combined with `ReceiverInfo` to determine the signing or validation policy. Required unless polling an asynchronous operation.
ReceiverInfo	`tas:CorroborationPartyInfo`	0..1	Information about the receiver, including policy tag. Required unless polling an asynchronous operation.
CorroborationSpec	`tas:CorroborationSpec`	0..1	Controls the invocation mode and the signature format and audit category to use. See the mode table in the previous step. Required unless polling an asynchronous operation.
CreateAuditDetails	`xs:boolean`	0..1	Set to `true` to include audit details in the response. Must be `false` when signing only with an audit category that does not include audit data, such as CAdES-T.
AgreementId	`xs:string`	0..1	An identifier logged and used to group transactions, such as by pricing model. Maximum 32 characters. Must be omitted when polling an asynchronous operation.
AsyncBehaviorMode	`tac:AsyncBehaviorMode`	0..1	Indicates whether the client can handle asynchronous processing. TrustWeaver decides whether to process the request asynchronously regardless of this value.
AsyncState	`tac:AsyncState`	0..1	Used to link a polling request to the original asynchronous invocation. Don't construct this value, take it from the previous `CorroborateResult`. Must not be included in the initial request.
AuxiliaryFunctions	`tas:AuxiliaryFunctions`	0..1	Include when auxiliary functions are required. For example, "GraphicalRepresentation", which is supported for some countries and signature formats. Note: The exact countries and formats are out of scope for this document.

Example request (sign mode, S/MIME signature):

CODE

<Corroborate xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
             xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Document>
      <Data>ABCD1234</Data>
      <DocumentFormat>OTHER</DocumentFormat>
      <InitialContentEncoding>MIME</InitialContentEncoding>
    </Document>
    <SenderInfo>
      <Name>Customer1</Name>
      <PolicyTag>DE</PolicyTag>
    </SenderInfo>
    <ReceiverInfo>
      <Name>Customer2</Name>
      <PolicyTag>IT</PolicyTag>
    </ReceiverInfo>
    <CorroborationSpec>
      <ImplicitSignatureSpec>
        <SignatureFormat>SMIME</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ImplicitSignatureSpec>
      <SigningFor>Sender</SigningFor>
      <ValidatingFor>Receiver</ValidatingFor>
    </CorroborationSpec>
    <CreateAuditDetails>true</CreateAuditDetails>
    <AgreementId>someIdentifier</AgreementId>
  </Request>
</Corroborate>

<Corroborate xmlns="http://www.trustweaver.com/trustarchive/storage/v1"
             xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Document>
      <Data>ABCD1234</Data>
      <DocumentFormat>OTHER</DocumentFormat>
      <InitialContentEncoding>MIME</InitialContentEncoding>
    </Document>
    <SenderInfo>
      <Name>Customer1</Name>
      <PolicyTag>DE</PolicyTag>
    </SenderInfo>
    <ReceiverInfo>
      <Name>Customer2</Name>
      <PolicyTag>IT</PolicyTag>
    </ReceiverInfo>
    <CorroborationSpec>
      <ImplicitSignatureSpec>
        <SignatureFormat>SMIME</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ImplicitSignatureSpec>
      <SigningFor>Sender</SigningFor>
      <ValidatingFor>Receiver</ValidatingFor>
    </CorroborationSpec>
    <CreateAuditDetails>true</CreateAuditDetails>
    <AgreementId>someIdentifier</AgreementId>
  </Request>
</Corroborate>

Send the request to the storage service endpoint provided during onboarding.

Process the CorroborateResponse.

The response contains the following elements:


Element	Cardinality	Description
SignedDocument	0..1	The result of the corroboration process. Returned only when the output differs from the input, such as when a signature is applied or new audit data is created. Not returned when validation fails.
AuditDetails	0..1	Audit details for the signature. Returned only when `CreateAuditDetails` was `true` and validation succeeded. For the details structure, see Long-term archiving and audit data .
ValidationOutcome	0..1	Returned when validation is performed. In sign and validate mode, the code is always `Ok`. In validate mode, the code may be `Ok`, `SignatureInvalid`, or `SignerInvalid`.
RegistrationOutcome	0..1	Returned when registration is performed. Always present in register mode.
AsyncState	0..1	Returned only when the operation is processed asynchronously and the request indicated the client can handle asynchronous responses. Use this value in the following polling requests.
AuxiliaryResults	0..1	This element is included only if any auxiliary functions were specified in the request.

Example response (sign and validate mode):

CODE

<CorroborateResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result>
    <Document>
      <Data>ABCD1234</Data>
      <DocumentFormat>MIME</DocumentFormat>
      <ImplicitSignatureInfo>
        <SignatureFormat>SMIME</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ImplicitSignatureInfo>
    </Document>
    <AuditDetails>...</AuditDetails>
    <ValidationOutcome>
      <Code>Ok</Code>
    </ValidationOutcome>
  </Result>
</CorroborateResponse>

<CorroborateResponse
  xmlns="http://www.trustweaver.com/trustarchive/storage/v1">
  <Result>
    <Document>
      <Data>ABCD1234</Data>
      <DocumentFormat>MIME</DocumentFormat>
      <ImplicitSignatureInfo>
        <SignatureFormat>SMIME</SignatureFormat>
        <AuditCategory>CADESA</AuditCategory>
      </ImplicitSignatureInfo>
    </Document>
    <AuditDetails>...</AuditDetails>
    <ValidationOutcome>
      <Code>Ok</Code>
    </ValidationOutcome>
  </Result>
</CorroborateResponse>