Step 1: Supplier creates the Standard Business Document

Every invoice sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Besides the SCI format, the payload can use the Malaysian UBL 2.1 format. The structure of the Malaysian format is explained here.

Here is a list of supported e-invoice types (InvoiceTypeCode):

• Invoice (01)

• Credit Note (02)

• Debit Note (03)

• Refund Note (04)

• Self-billed Invoice (11)

• Self-billed Credit Note (12)

• Self-billed Debit Note (13)

• Self-billed Refund Note (14)

SBDH - Invoice

The Standard Business Document Header (SBDH) must use the following values when issuing a document in the SCI format:

Node	Required	Attributes	Value
StandardBusinessDocumentHeader.Sender.Identifier	Yes	Authority="MY"	Supplier's tax ID
StandardBusinessDocumentHeader.Receiver.Identifier	Yes	Authority="MY"
StandardBusinessDocumentHeader.DocumentIdentification.Standard	Yes		urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion	Yes		2.1
StandardBusinessDocumentHeader.DocumentIdentification.Type	Yes		Invoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Country Child node Identifier: MY
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: ProcessType Child node Identifier: Outbound
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: CompanyCode Child node Identifier: Supplier's tax ID
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: SenderDocumentId Child node Identifier: A unique document ID. We recommend the ERP document ID.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: SenderSystemId Child node Identifier: The system ID configured in the backend. This parameter is used to determine which notifications are returned to the client and what attachments they include. If SenderSystemId is not configured on the client side, it'll use the default value of "DefaultSystemERP". For more information, see this topic.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Mapping.OutputSchema Child node Identifier: UBLInvoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Mapping.TransformDocument Child node Identifier: SCI-TO-LEGAL_INVOICE
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Transmission.OperationType Child node Identifier: SIGNING
StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName	Yes		Default
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: BusinessCategory Child node Identifier: B2B
SovosDocument.SovosCanonicalInvoice.Invoice	Yes		SCI
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Version Child node Identifier: 1.0

Local format - Invoice

The supplier can use the local format (XML) instead of SCI. Use the following values in the SBDH for documents that use the local format:

Node	Required	Value
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes	Child node Type: Mapping.TransformDocument Child node Identifier: LEGAL-TO-SCI_INVOICE
SovosDocument.SovosLegalDocument.Base64Document	Yes	A local format

Note:

The local format (XML) document must be Base64-encoded before it can be added to the SBD.

</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
	<svs:SovosLegalDocument>
		<enc:Base64Document>
			<enc:EmbeddedDocument id="1" filename="invoice.xml" mimeCode="application/xml">PD94bWwgdmVyc...FRdHVyYT4NCg==<enc:EmbeddedDocument>
		</enc:Base64Document>
	</svs:SovosLegalDocument>
</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Note:

Include all the mandatory nodes as specified in the SBDH schema. If the information cannot be provided and the respective mandatory node has not been mentioned on the current page, the node can be left empty but must still be included in the SBDH.

SBD Sample

Below is a sample of the SBD. In addition, there's a full sample of the SBD in the Postman Samples page.

<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="MY">123456789</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>123456789</sbd:Contact>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="MY"/>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Receiver>
		<sbd:DocumentIdentification>
			<sbd:Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</sbd:Standard>
			<sbd:TypeVersion>2.1</sbd:TypeVersion>
			<sbd:InstanceIdentifier/>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2020-06-16T00:31:52Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Version</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>1.0</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>321412</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UAT101</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>123456789</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>MY</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.OutputSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UBLInvoice</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SubSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier/>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>B2B</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Transmission.OperationType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SIGNING</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessProcess</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:BusinessService>
					<sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
				</sbd:BusinessService>
			</sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
			*UBL Elements*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>a
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Important:

If you have configured a certificate, the listVersionID attribute with value "1.1" needs to be provided for the node InvoiceTypeCode.

<cbc:InvoiceTypeCode listVersionID="1.1">

Currently, you don't need to sign documents to submit them to IRBM. If you don't have a certificate, you can use the following scope in the SBDH instead.

<cbc:InvoiceTypeCode listVersionID="1.0">

<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
	<sbd:StandardBusinessDocumentHeader>
        ...
		<sbd:Scope>
			<sbd:Type>Transmission.OperationType</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>SIGNING</sbd:Identifier>
		</sbd:Scope>
        ...
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
			    ...
			    <cbc:InvoiceTypeCode listVersionID="1.1">...</cbc:InvoiceTypeCode>
			    ...
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint. The request must include the following request body parameters:

Request Sample

curl --location --request POST 'https://api-test.sovos.com/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'

Response Sample

{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "DOCUMENT-ID"
    }
}

Step 3: Sovos maps the SCI into XML

Upon receiving the SCI file, Sovos maps it into the required XML format.

Step 4: Sovos validates the XML

Sovos validates the schema based on the information provided by the tax authority. If there are errors in the document that the client sent, Sovos detects them instead of waiting for the tax authority's response.

Step 5: Sovos signs the XML

Sovos signs the file using the taxpayer's certificate, which generates the legalSigned attachment .

Step 6: Sovos batches the XMLs

After the XML file is signed, the request is placed into a batch before being transmitted to IRBM. The batch is transmitted after one of the following limits is met:

Production

• Time limit: Five minutes have passed since the batch was created.

• Number of documents limit: 100 documents have been added to the batch.

• Total size limit: Five megabytes of documents have been added to the batch.

Important:

Documents need to be less than 300KB; Otherwise, Sovos rejects them.

UAT

• Time limit: One minute has passed since the batch was created.

• Number of documents limit: 100 documents have been added to the batch.

• Total size limit: Five megabytes of documents have been added to the batch.

Important:

Documents need to be less than 300KB; Otherwise, Sovos rejects them.

Step 7: Sovos transmits the XML

Sovos transmits the batch to the Tax Authority's e-Invoice system (IRBM).

Step 8: IRBM processes the XML

The IRBM system proceeds to validate the schema documents and verify that business logic, signature, taxpayer information and duplicates are checked before returning a success message or rejection message indicating IRBM has approved the document.

The XML file is then also made available for the counterparty to retrieve, and potentially reject, within 72 hours. If the counterparty rejects the invoice, it is still considered active until the taxpayer cancels the invoice separately or issues a credit note or a debit note. After 72 hours of issuance, the counterparty can still reject out-of-band and thus it is not implicitly accepted just because 72 hours have passed without a rejection.

The counterparty can't reject consolidated invoices.

Step 9: IRBM sends the response to Sovos

After performing its services, the IRBM system sends the response to Sovos.

Step 10: Taxpayer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and also contain the signed XML encoded in Base64 when it's available.

You can retrieve application responses (notifications) in two ways:

Fetch everything in one single response (notification)

When polling for responses, Sovos returns one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data.

To complete a transaction, the supplier retrieves only one notification, with an SCICloudStatusCode of 209 and all the necessary attachments and data. The notification needs to be parsed for the SCIResponseCode value. There are two possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP UBLExtensions in the ApplicationResponse will contain: Uuid - Assigned to each document accepted by IRBM. LongId - Assigned to each document accepted by IRBM in order to allow for querying data anonymously. validationLink - A link to be embedded into the QR code generated for human readable representation of the invoice. receptionDate - The date and time when the document was submitted to IRBM.	Workflow successfully completed
209	RE	Workflow successfully completed

Fetch multiple responses (notifications) containing different information

When polling for responses, Sovos returns multiple notifications with different SCICloudStatusCode values containing different attachments and data until the final one (with status 209) is returned.

To complete a transaction, the supplier must retrieve the application responses until the transaction has finished. If the supplier has subscribed to multiple notifications, the transaction can generate different application responses, as shown in the table below. The transaction finishes when a notification containing SCICloudStatusCode with value of 209 has been received.

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range indicates a server error. In this case, the workflow would not complete and will not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
100	IP	Document received successfully
101	IP	Document mapped successfully
200	IP/AP Initially IP is sent and when the workflow finishes (after 72h) AP is sent. UBLExtensions in the ApplicationResponse will contain: Uuid - Assigned to each document accepted by IRBM. LongId - Assigned to each document accepted by IRBM to allow for querying data anonymously. validationLink - A link to be embedded into the QR code generated for human readable representation of the invoice. receptionDate - The date and time when the document was submitted to IRBM.	Authorized by the Tax Authority
207	AP	PDF created successfully
209	AP	Workflow successfully completed
400	RE	Rejected by the Tax Authority or the counterparty
400 (401)	RE	Rejected by the Tax Authority or the counterparty

The taxpayer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/MY

• GET /documents/MY/{documentId}/notifications

GET /notifications/MY

The supplier can send a GET request to the /notifications/MY endpoint to retrieve application responses that match the set search criteria. This endpoint allows using the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value is related to the CompanyCode set in the SBDH. Note: If a request does not include this parameter, it returns all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications, within 24 hours of their acknowledgment, in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/MY?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "my_UBLInvoice__1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/MY/{documentId}/notifications

The supplier can send a GET request to the /documents/MY/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, use the following path parameter:

Name	Type	Required	Description
documentId	string	Yes	The document ID returned in step 2

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/MY/{documentId}/notifications?' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "my_UBLInvoice__1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 11: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. To do this, send a PUT request to the /notifications/MY endpoint.

To make this request, use the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/MY' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76"
    }
]'

Response sample

{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Sovos generates the PDF

Sovos generates a PDF that contains the content of the invoice XML in a human-readable format along with the QR code. The QR code itself contains a public link to the invoice on the IRBM portal.

Archiving

Archiving can be done as a bundle, for example, as part of the Clearance flow, and is recommended for suppliers integrating with the Sovos solution for Malaysia for the first time. It can also be done separately, using an explicit API call that uses another archive. For more information on standalone archiving, see the e-Archiving documentation page.

Bundled e-invoice archiving on the new platform is optional. Existing customers can choose to use their current solution and include e-Archiving.

Distribution

The invoice can be communicated to the counterparty by Sovos or the taxpayer.

Sovos shares the invoice with the counterparty

For Sovos to be able to distribute the invoice to the counterparty, the taxpayer needs an email distribution channel. For more information contact Sovos Professional Services.

After a distribution channel is configured, the taxpayer should no longer send the invoice to the counterparty.

Taxpayer shares the invoice with their counterparty

In cases where a distribution channel has not been configured, the tTaxpayer is responsible for distributing the invoice to the Counterparty.

The invoice can be communicated to the Counterparty with the QR code included if the human readable version is shared. The invoice data is made available in IRBM's system and can be consulted by the Counterparty using the QR code.

When communicating the invoice, it's important to ensure the invoice's authenticity and integrity. See our post-audit signing and validation service for more information on how to sign electronic documents in Malaysia.

Step 1: Sovos retrieves the documents from the IRBM system

Sovos uses the buyer's credentials to authenticate with the IRBM system to collect the documents that have been made available (either in JSON or XML formats).

Step 2: Sovos generates the PDF

Sovos generates a PDF from each document from IRBM and generates a notification. That includes the content of the QR code and the validation link for this document.

Step 3: Sovos maps the retrieved document into SCI and makes them available

Sovos stores the retrieved documents, maps them to SCI, and makes them available for buyers to get. The PDF version of the documents is also made available.

Step 4: Sovos distributes the PDF

Sovos can distribute the PDF through email to a configurable email address.

Step 5: Buyer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

To complete a transaction, the buyer must use the GET /notifications/MY endpoint to retrieve the application responses until the transaction has finished. If the buyer has subscribed to all notifications, the transaction can generate different application responses, as shown in the table below:

GET /notifications/MY

The buyer can send a GET request to

the /notifications/MY endpoint to retrieve application responses that match the set search criteria. This endpoint allows using the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, only use values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system.
includeAckwnowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "1" to only include notifications related to inbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/MY?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=1' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "my_UBLInvoice_Polling_1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 6: Buyer acknowledges the retrieved documents

After retrieving the documents, the buyer must process them and mark them as acknowledged. To do this, send a PUT request to the /notifications/MY endpoint.

To make this request, use the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/MY' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76"
    }
]'

Response sample

{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Step 1: Buyer sends a POST Request to Sovos

The buyer sends a POST request to the /documents/MY/action endpoint. To make this request, set the following request body parameters:

Request sample

curl --location 'https://api-test.sovos.com/v1/documents/MY/action' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
  "actionCode": "document.reject",
  "documents": [
    {
      "metadata": {
        "reason": "reject action test"
      },
      "documentId": "70acd7b6595bd6c27c7f760d594c89a0"
    }
  ]
}

Response sample

{
	"status": 202,
	"message": "Accepted",
	"success": true,
	"timestamp": 1724404345626
	"data":[
		{
			"status": 202,
			"transactionId": "564c4995-ecc9-4ba0-a578-4a3976feb6ea",
			"documentId": "70acd7b6595bd6c27c7f760d594c89a0"
		}
	]
}

Step 2: Sovos transmits request to IRBM

Sovos finds the corresponding document in the system and transmits the rejection request to IRBM.

Step 3: IRBM processes the request

IRBM verifies that the 72-hour window has not passed since the original document was issued, and that the document can be rejected successfully.

Step 4: IRBM returns the response

IRBM returns the success message, or the error message if the rejection could not be performed.

Step 5: Buyer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information.

Clients have the option to retrieve application responses (notifications) in one of two ways:

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos only returns one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos returns multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Single response

To complete a transaction, the buyer retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range still remains an option, as it indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP	Workflow successfully completed
209	RE	Workflow successfully completed

Multiple responses

To complete a transaction, the buyer retrieves only one notification with SCICloudStatusCode of 209 and all the necessary attachments/data. The notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option, as it indicates a server error. In this case the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
101	IP	Document mapped successfully
212	AP	Rejection Request Accepted
209	AP	Workflow successfully completed

The buyer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/MY

• GET /documents/MY/{documentId}/notifications

GET /notifications/MY

The buyer can send a GET request the /notifications/MY endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value is related to the CompanyCode in the SBDH. Note: If a request does not include this parameter, it returns all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/MY?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "78bd5a18-...-73bfbdb3bf21",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "my_UBLInvoice_Polling_1.0",
                "transactionId": "43...d94",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "192714478",
                "erpSystemId": "ERPSystem",
                "processType": "1",
                "taxId": "C873686030",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

GET /documents/MY/{documentId}/notifications

The buyer can send a GET request to the /documents/MY/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, set the following parameters:

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The document ID returned in step 1
includeAcknowledged	boolean	No	Query	false	Use "true" to include previously acknowledged notifications in the result

Request sample

curl --location 'https://api-test.sovos.com/v1/documents/MY/DOCUMENT-ID/notifications?includeAcknowledged=false' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "78bd5a18-...-73bfbdb3bf21",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "my_UBLInvoice_Polling_1.0",
                "transactionId": "43...d94",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "192714478",
                "erpSystemId": "ERPSystem",
                "processType": "1",
                "taxId": "C873686030",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

Step 6: Buyer marks the application responses as acknowledged

The buyer must process the retrieved application responses and mark them as acknowledged. To do this, send a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/MY' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--data '[
    {
        "status": "read",
        "notificationId": "e7b32eda-cb67-43b9-91de-f6d9c90f60d9"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1708509282198,
    "data": {}
}

Step 1: Supplier sends a POST request to Sovos

The supplier sends a POST request to the /documents/MY/action endpoint. To make this request, set the following request body parameters:

Request sample

curl --location 'https://api-test.sovos.com/v1/documents/MY/action' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "Wrong total submitted"
        },
        "documentId": "DOCUMENT-ID"
      }
    ]
  }'

Response sample

{
    "status": 202,
    "message": "Accepted",
    "success": true,
    "timestamp": 1708018192828,
    "data": [
        {
            "status": 202,
            "documentId": "DOCUMENT-ID"
        }
    ]
}

Step 2: Sovos transmits the request to IRBM

Sovos finds the corresponding document in the system and transmits the cancellation request to IRBM.

Step 3: IRBM processes the request

IRBM verifies that the 72-hour window has not passed since the original document was issued, and that the document can be cancelled successfully. If the 72-hour window has passed, the taxpayer can still cancel the document by issuing a credit note, debit note, or refund note separately.

Step 4: IRBM returns the response

IRBM returns the success or error message if the cancellation could not be performed.

Step 5: Taxpayer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the taxpayer must retrieve the application responses that become available during the transaction, which provide status information.

Clients have the option to retrieve application responses (notifications) in one of two ways:

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos only returns one final notification with SCICloudStatusCode of 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos returns multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Single response

To complete a transaction, the supplier retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP	Workflow successfully completed
209	RE	Workflow successfully completed

Multiple responses

To complete a transaction, the supplier retrieves only one notification with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range indicates a server error. In this case the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
101	IP	Document mapped successfully
201	AP	Cancelled
209	AP	Workflow successfully completed

The supplier can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/MY

• GET /documents/MY/{documentId}/notifications

GET /notifications/MY

The supplier can send a GET request to the /notifications/MY endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified tax ID. This value relates to the CompanyCode set in the SBDH. Note: If a request doesn't include this parameter, it returns all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/MY?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "40e2ef57-...-8e1c9e8de016",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "my_UBLInvoice__1.0",
                "transactionId": "78...5f0",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "172012265",
                "erpSystemId": "ERPSystem",
                "processType": "0",
                "taxId": "11161161",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

GET /documents/MY/{documentId}/notifications

The supplier can send a GET request to the /documents/MY/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, use the following parameters:

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The document ID returned in step 1
includeAcknowledged	boolean	No	Query	false	Use "true" to include previously acknowledged notifications in the result

Request sample

curl --location 'https://api-test.sovos.com/v1/documents/MY/DOCUMENT-ID/notifications?includeAcknowledged=false' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "40e2ef57-...-8e1c9e8de016",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "my_UBLInvoice__1.0",
                "transactionId": "78...5f0",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "172012265",
                "erpSystemId": "ERPSystem",
                "processType": "0",
                "taxId": "11161161",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

Step 6: Taxpayer marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. To do this, send a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/MY' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--data '[
    {
        "status": "read",
        "notificationId": "e7b32eda-cb67-43b9-91de-f6d9c90f60d9"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1708509282198,
    "data": {}
}

Step 1: Buyer sends a consultation request for a specific UUID to Sovos

The customer sends a POST request to the /v1/documents/MY/consultation endpoint.

Request body parameters:

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/consultations' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "consultationCode": "document.retrieval",
    "productId": "MY_UBLInvoice__1.0",
    "country": "MY",
    "company": {
        "taxId": "<company tax id>"
    },
    "documents": [
    {
        "metadata": {
            "uuid": <UUID of the document>
        }
     }
   ]
}

Response sample

{
    "message": "OK",
    "status": 200,
    "success": true,
    "data": {
        "completed": true,
        "detailsDto": {
            "completed": "Success",
            "messages": [],
            "documents": [
                {
                    "key": "M32Z3ZDRJVK2W0535KXFK2DJ10_DocumentDetails.json",
                    "data": "eyJ1dWlkIjoiTTMyWjNaRFJKVksyVzA1MzVLWEZLMkRKMTAiLCJzdWJtaXNzaW9uVWlkIjoiNDE2SEZLWDZXUThGRDBZMzVLWEZLMkRKMTAiLCJsb25nSWQiOiJONDZFNjM3ME5RWDJEQ1pFNUtYRksyREoxMFEwcnhhbjE3MzIwMzMxMTUiLCJkYXRlVGltZVJlY2VpdmVkIjoiMjAyNC0xMS0xOVQxNjoxODozNVoiLCJkYXRlVGltZVZhbGlkYXRlZCI6IjIwMjQtMTEtMTlUMTY6MTg6MzZaIiwic3RhdHVzIjoiVmFsaWQiLCJjcmVhdGVkQnlVc2VySWQiOiJDODczNjg2MDMwOmZkNTlmY2NkLTk1OTctNDY0OS1iNmNiLWI4MTc4OGJmNzgyOCIsImRvY3VtZW50U3RhdHVzUmVhc29uIjpudWxsLCJjYW5jZWxEYXRlVGltZSI6bnVsbCwicmVqZWN0UmVxdWVzdERhdGVUaW1lIjpudWxsLCJ2YWxpZGF0aW9uUmVzdWx0cyI6eyJTdGF0dXMiOiJWYWxpZCIsIlZhbGlkYXRpb25TdGVwcyI6W3siU3RhdHVzIjoiVmFsaWQiLCJFcnJvciI6bnVsbCwiTmFtZSI6IlN0ZXAwMy1EdXBsaWNhdGVkIFN1Ym1pc3Npb24gVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA0LUNvZGUgRmllbGQgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA1LVRheHBheWVyIFByb2ZpbGUgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA2LURvY3VtZW50IFJlZmVyZW5jZXMgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA3LURvY3VtZW50IEN1cnJlbmN5IFZhbGlkYXRvciJ9XX0sImludGVybmFsSWQiOiIwMS1CdXllci1yZWplY3Rpb24iLCJkYXRlVGltZUlzc3VlZCI6IjIwMjQtMTEtMTdUMDA6MDA6MDBaIiwidHlwZU5hbWUiOiJJbnZvaWNlIiwidHlwZVZlcnNpb25OYW1lIjoiVmVyc2lvbiAxIiwiaXNzdWVyVGluIjoiQzg3MzY4NjAzMCIsImlzc3Vlck5hbWUiOiJBTVMgU2V0aWEgSmF5YSBTZG4uIEJoZC4iLCJyZWNlaXZlcklkIjoiQzg3MzY4NjAzMCIsInJlY2VpdmVyTmFtZSI6IkhlYmF0IEdyb3VwIiwidG90YWxFeGNsdWRpbmdUYXgiOiIxNDM2LjUiLCJ0b3RhbERpc2NvdW50IjoiMTQzNi41IiwidG90YWxOZXRBbW91bnQiOiIxNDM2LjUiLCJ0b3RhbFBheWFibGVBbW91bnQiOiIxNDM2LjUifQ==",
                    "mimeType": "application/json"
                }
            ]
        }
    }
}

Response sample with an error

{
    "timestamp": 1732034087,
    "message": "TaxAuthorityRejectedError",
    "status": 200,
    "success": false,
    "errors": [
        {
            "subCode": "404",
            "message": "It seems that you are not authorized to get document details"
        }
    ]
}

Step 2: Sovos validates the request and calls IRBM

Upon receipt of the request, Sovos validates the request and calls IRBM to retrieve the details for the given UUID.

Step 3: IRBM Returns the document details

IRBM returns all the details for the given UUID.

Step 4: Sovos returns the document details

After receiving the details for the given UUID from IRBM, the Sovos Platform builds the consultation response that is returned to the user. This response contains a Base64-encoded JSON object representing the details of the document.

Outbound mock

The outbound mock simulates sending documents to the tax authority. To use the mock service, customers must upload specific credentials using the Configurations v2 resource. Afterward, they can proceed to issue documents.

How to configure the outbound mock

To use the mock service for Malaysia outbound, configure any arbitrary credentials (inside the value object) through the settings endpoint from configurations v2.

Here is a sample request:

curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/settings' \
--header 'x-correlationId: developer-guide' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "context": "transmission",
        "configurations": [
            {
                "name": "partner_credentials_irbm",
                "value": {
                    "client_id": "INSERT-ARBITRARY-CLIENTID-HERE",
                    "client_secret": "INSERT-ARBITRARY-SECRET-HERE"
                },
                "scope": {
                    "category": "MY_INV",
                    "productId": "my_UBLInvoice__1.0",
                    "orgId": "YOUR-ORG-ID",
                    "taxId": "YOUR-COMPANY-TAXID"
                }
            }
        ]
    }
]'

How to use the outbound mock

When sending a document with a POST request to the Send a new Document endpoint to reach the mocked services, the x-correlationId value must end with "-mock". For example, x-correlationId = "123-mock". Sovos' solution distinguishes between the mocked outbound service and the real tax authority UAT environment based on the presence of this value.

When using the GET method with the Notifications endpoints, the x-correlationId doesn't need to end with "-mock". This is because the Sovos solution does not differentiate between mocked notifications and notifications related to the real tax authority UAT environment — they are both treated as "notifications", which can be retrieved normally. The same reasoning applies to using the PUT method with the Mark Notifications as acknowledged endpoint: There's no need to add an x-correlationId ending with "-mock".

To test outbound against the real tax authority UAT environment, it is crucial to follow the correct prerequisites and configuration steps. This involves obtaining the real tax authority credentials and configuring them in the Sovos solution. So, when issuing the document, ensure that the x-correlationId doesn't end with "-mock".

Outbound mock validation

The main purpose of the mocked service is to allow customers in the early stages of integration to test the end-to-end flow without being blocked by the lack of real tax authority credentials. Only a limited set of scenarios can be tested based on the document's content, as explained in the list below:

• If one or more required fields in the document are missing or empty.

• Submit exactly same document (same hash) within 10 minutes.

  Request payload is identical to a previous payload sent in the last 10 minutes. Try to submit payload after {secondsRemaining} seconds (seconds remaining replaced with actual value).

• If the request hash value of the document is not the same as the hash we compute based on the document.

  Document hash is not valid.

• IssueDate or IssueTime missing in the document.

  IssueDate OR IssueTime is missing in the document.

• IssueDate or IssueTime are not valid date times.

  IssueDate OR IssueTime is not in a valid format.

• IssueDateTime (which is created combining IssueDate and IssueTime from document) is over 72 hours in the past.

  Issuance date time value of the document is too old that cannot be submitted.

• If IssueDateTime is in the future.

  Document issuance date time is in the future.

• UUID is not found.

  Document UUID :uuid is not found. Please ensure the UUID is correct.