South Korea
Enabling support for South Korea requires NTS registration, a Business Registration Number, a valid certificate, an ASP user ID and token, among other things.
Prerequisites
-
NTS registration (required for sending invoices).
-
A valid Business Registration Number (obtained through the NTS), which is required for sending invoices. You can either obtain it online through Hometax or by visiting a local tax office.
-
A valid certificate with a password, which are required by the ASP system. You can obtain it from the NTS or from an accredited certificate authority (CA).
-
An ASP user ID and token. You can obtain them from the ASP system after uploading the certificate.
Create a developer account to use the Configuration v2 API resource. You also need (for now) to contact the Sovos' Professional Services team to obtain special authorization to use this resource and to obtain your organization ID.
Note:Organization IDs differ between sandbox and production.
A configured company and product.
-
The API credentials for production.
-
For both sandbox (UAT) and production, you need to fill out the following documents and share them with the Professional Services team:
Available products
kr_TaxInvoice__3.0
Error handling
When handling errors, the client application must follow the Indirect Tax API's error handling principles, as specified in the error handling documentation.
In general, all error codes in the 400 range are client errors, which you need to analyze. After fixing the error, you can resend the request. Error codes 408 and 429 are exceptions: In these cases, you should wait at least 60 seconds before retrying. Error codes in the 500 range are server errors. In that case, resend the request according to the instructions given on the error handling documentation, which also includes a full list of error codes Indirect Tax API can return.
See the following spreadsheets for more details around the possible errors returned by the tax authority:
Configure transmission credentials for South Korea
Because NTS does not have a UAT environment, transactions sent to the ASP remain in an "In Progress" state. To make UAT tests, you need to use the mock UAT environment Sovos implemented against the ASP. This lets you simulate a successful E2E transaction and negative scenarios.
The use of the mock environment comes with its own set of prerequisites:
A predefined value for
taxId
set to "1232526378".A predefined value for
smartBillUserId
set to "kgj0915".A predefined value for
authenticationCode
set to "571C018E18214B20B1736DE67859B261".Any arbitrary value such as "password" can be used for
certificatePassword
.
You must set up transmission credentials to let the Indirect Tax API communicate with the ASP system, which connects to the South Korean NTS system to let you perform authentication and transmit documents.
All other backend configuration is handled by the Professional Services team during the implementation phase.
Upon successful creation, the API will return a JSON object containing the uploaded transmission credentials and their assigned SETTING-ID
Samples for uploading transmission credentials for South Korea
Request sample
Request sample for uploading new transmissions credentials:
curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/{organizationId}/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
{
"context": "transmission",
"configurations": [
{
"name": "partner_credentials_businesson",
"value": {
"smartBillUserId": "SMARTBILL-USERID",
"authenticationCode": "AUTH-CODE",
"certificatePassword": "CERT-PASSWORD"
},
"scope": {
"category": "KR_INV",
"productId": "kr_TaxInvoice__3.0",
"orgId": "YOUR-ORG-ID",
"taxId": "YOUR-TAXID"
}
}
]
}
]'
Response sample
Response sample for uploading new transmissions credentials:
{
"status": 201,
"message": "Created",
"success": true,
"timestamp": 1684958007526,
"data": [
{
"message": "Configurations are created",
"statusCode": 201,
"configurationContextResponse": {
"context": "Transmission",
"configurations": [
{
"id": "SETTING-ID",
"name": "partner_credentials_businesson",
"value": {
"smartBillUserId": "*******",
"authenticationCode": "*******",
"certificatePassword": "*******"
},
"scope": {
"category": "KR_INV",
"productId": "kr_TaxInvoice__3.0",
"orgId": "YOUR-ORG-ID",
"taxId": "YOUR-TAXID"
},
"auditData": {
"createdAt": 1684958007,
"createdBy": "user@company.com",
"isDeleted": false,
"version": 1
}
}
]
}
}
]
}
Report invoice
Reporting an invoice in South Korea is based on the Default business process, which follows this order: Mapping and Transmission. The following diagram provides a detailed overview of this process:
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 in turn includes a Sovos Canonical Invoice (SCI) — except when the local format is used. To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.
Here are some key elements that should be included in the SBD and in the invoice:
Use the following values in the SBDH for documents that use the SCI format:
Node | Required | Attributes | Value |
---|---|---|---|
StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="KR" | Supplier's TIN |
StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="KR" | |
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 Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes | Child node Type : SubSchema | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | No |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
SovosDocument.SovosCanonicalInvoice.Invoice | Yes | SCI |
Alternatively, 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.DocumentIdentification.Standard | Yes | urn:kr:or:kec:standard:Tax:ReusableAggregateBusinessInformationEntitySchemaModule:1:0 |
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes | 3.0 |
StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes | TaxInvoice |
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node |
SovosDocument.SovosLegalDocument.Base64Document | Yes | A local format |
You need to encode the local format (XML) document in Base64 before you can add it as part of the SBD. Here is a sample:
</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>
</svs:StandardBusinessDocument>
Supported document types for the local format (XML) document:
-
"0101" - Normal e-tax invoice
-
"0201" - Amended e-tax invoice
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, for example the receiver.identifier
, 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 on 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="KR">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="KR">444555666</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>444555666</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>2022-06-16T00:31:52Z</sbd:CreationDateAndTime> </sbd:DocumentIdentification> <sbd:BusinessScope> <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>SystemERP</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>KR</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>TaxInvoice</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessCategory</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>B2B</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SubSchema</sbd:Type> <sbd:InstanceIdentifier/> <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:Scope> <sbd:Type>Version</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>3.0</sbd:Identifier> </sbd:Scope> </sbd:BusinessScope> </sbd:StandardBusinessDocumentHeader> <svs:SovosDocument> <sci:SovosCanonicalInvoice> <inv:Invoice> *UBL Elements* </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:
Name | Type | Required | Description |
---|---|---|---|
data | string | Yes | The SBD encoded in Base64, as created in step 1 |
dataEncoding | string | Yes | Enter "base64" |
- 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
-
{ "status": 202, "message": "Accepted", "success": true, "timestamp": 1684959137541, "data": { "transactionId": "18576c36-...-ad24204f5db6", "documentId": "e23...ba6f" } }
Step 3: Sovos maps the SCI into XML
This step will be skipped if the SBD contains the invoice in the local format (XML).
Step 4: Sovos performs the schema validation
Sovos performs a schema validation based on the information provided by the tax authority. If there are errors in the document, Sovos detects detects them instead of waiting for the tax authority's response.
Step 5: Sovos transmits the XML
Sovos transmits the XML file to the ASP system for signing and transmission.
In the UAT environment, the XML file goes to mock instead of the ASP system. In the Production environment, it goes to the ASP.
Step 6: ASP or NTS processes the XML
The ASP system or the NTS performs a schema validation and several business validations. Then they generate an approval or rejection response message along with an error message, where applicable.
Step 7: ASP or NTS sends the response to Sovos
After performing its services, either the ASP or NTS sends the response back to Sovos.
Step 8: Sovos generates a PDF
Sovos generates a PDF file.
Step 9: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the Professional Services team.
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 the cleared XML encoded in Base64 after it's available during the process.
Additionally, you must consider the following details included in the response:
- Transmission message
- It maps to the
SCIGovtStatusCode
andStatusReason
elements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The South Korean tax authority doesn't define any specific set of rules about what action to take on each warning. Depending on the type of message, the user may have to modify the invoice, take some additional action, or simply make a note for the future.
Options for retrieving application responses (notifications):
- Fetch everything in one single response (notification)
- When polling for responses, Sovos only returns one final notification with
SCICloudStatusCode
of 209 that contains all the relevant attachments and data. Detailed description follows. - 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. Detailed description follows.
To configure notifications for your company or update your current configuration, contact the Professional Services team.
To complete a transaction, the supplier retrieves only one notification, the complete workflow one, with SCICloudStatusCode
of 209 and all the necessary attachments and data. Afterwards, the notification needs to be parsed for the SCIResponseCode
value. Possible values for SCIResponseCode
:
- AP
- The document's compliance status has been accepted with all the necessary attachments and data included.
- RE
- The document's compliance status has been rejected, and more parsing is needed:
-
If
SCIGovtStatusCode
is present, the error can be found by readingStatusReason
. -
if
SCIInternalValidationCode
is present, the error can be found by readingStatusReason
.
-
# | SCICloudStatusCode | SCIResponseCode | Sample |
---|---|---|---|
1 | 209 | AP |
Workflow Successfully Completed
|
2 | 209 | RE |
Workflow Successfully Completed
|
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 the value of 209 has been received.
# | SCICloudStatusCode | SCIResponseCode | Sample |
---|---|---|---|
1 | 100 | IP |
Document received successfully
|
2 | 101 | IP |
Document mapped successfully
|
3 | 200 | AP |
Authorized by the tax authority
|
4 | 209 | IP |
Workflow Successfully Completed
|
5 | 400 | RE |
Rejected by the tax authority or the counterparty
|
6 | 401 | RE |
Error processing document
|
SCICloudStatusCode
with a value in the 5xx range still remains an option, as it indicates a server error. In this case, the workflow doesn't finish in the sense that it doesn't return a notification with SCICloudStatusCode
of 209.The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/KR
-
GET /documents/KR/{documentId}/notifications
- GET /notifications/KR
- The supplier can send a GET request to the /notifications/KR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:
Name Type Required Default Description taxId string No Include only notifications related to the specified
taxId
. This value relates to theCompanyCode
set in the SBDH.Note: If a request doesn't include this parameter, it will return all the notifications related to the country and the
sourceSystemId
parameter.page integer No 1 To specify the page to be returned, enter a value between 1 and 10. perPage integer No 10 To specify the number of results for the returned page, enter a value between 1 and 100.
Note: 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 Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/KR?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE'
- Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 1682630764844, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "4a179a83-...-30d04b1b7807", "correlationId": "rrt-...-229692-1", "appPrefix": "DLT", "metadata": { "productId": "kr_TaxInvoice__3.0", "transactionId": "18576c36-...-ad24204f5db6", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "ERPSystem", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "100", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...lPg==", "createdDate": 1684959137 } ] } }
- GET /documents/KR/{documentId}/notifications
- The supplier can send a GET request to the /documents/KR/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following parameter:
Name Type Required Parameter type Default Description documentId string Yes Path The ID of the document returned in step 2 - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/KR/{documentId}/notifications' \ --header 'Content-Type: application/json' \ --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": [ { "notificationId": "4a179a83-...-30d04b1b7807", "correlationId": "rrt-...-229692-1", "appPrefix": "DLT", "metadata": { "productId": "kr_TaxInvoice__3.0", "transactionId": "18576c36-...-ad24204f5db6", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "ERPSystem", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "100", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...lPg==", "createdDate": 1684959137 } ] } }
Step 9: Supplier marks the application responses as acknowledged
The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/KR endpoint.
To make this request, set the following request body parameters:
Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | Enter "read". |
notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId
values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/KR' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]'
- Response sample
-
{ "timestamp": 1601673284, "status": 200, "success": true, "message": "Notifications acknowledged successfully." }
Step 10: Sovos generates a PDF
Sovos generates a PDF that presents the content of the invoice XML in a human-readable format.
Step 11: Email distribution
Sovos can distribute the PDF by email after the document distribution details have been configured.
Step 12: Archiving
You can compliantly archive the legally signed invoice using Sovos' Compliant Archive.
For suppliers integrating with the Sovos solution for South Korea for the first time, we recommend the bundled approach, in which archiving is part of the invoice reporting flow. Archiving can also be done separately through an explicit API call that uses another archive. For more information on standalone archiving, see the eArchiving documentation page.
Step 13: Supplier sends the invoice to the buyer
The supplier can send the invoice to the buyer before or after it has been reported to the tax authority.
The delivery of the invoice to the buyer is outside Sovos' scope. So, it is up to the supplier to design a solution to accommodate the preferred business processes.
Scenario examples
All examples shown here apply only to Sovos' Sandbox (UAT) environment.
Successful invoice reporting
When you report an invoice using the correct values, you should receive a signed invoice containing a randomly generated key. Here are the predefined values:
- smartBillUserId
- Enter "kgj0915"
- authenticationCode
- Enter "571C018E18214B20B1736DE67859B261"
- taxId (required)
- Enter "1232526378"
Unsuccessful invoice reporting
Instructions to test different failure scenarios:
- Option 1: Use at least one incorrect value
-
Enter at least one wrong value for the predefined values during configuration:
smartBillUserId
,authenticationCode
, ortaxId
(required). In this scenario, you should receive a success response when reporting an invoice but get an error when polling for notifications, so you will not receive a signed invoice.The response should contain the following values when using an incorrect
taxId
:- sciCloudStatusCode
- "500"
- sciResponseCode
- "RE"
- sciStatusAction
- "OTH"
- Option 2: Enter an incorrect IssueId
-
When you enter a
IssueId
that is not in the expected format, you should receive a success response when reporting an invoice but get an error when polling for notifications, so you will not receive a signed invoice.The
IssueId
format consists of:- First eight digits
- The current date (YYYYMMDD)
- Next eight digits
- A constant value of "41000008"
- Next three digits
- The "uup" business code stringNote:
This string is only valid for the UAT environment. For the production environment, "fsb" is the expected value.
- Last five digits
- Unique invoice identifier that is incremented sequentiallyNote:
Repeating the last five
IssueId
digits within the same day causes a duplication error.
Expected response for a duplicate
IssueId
:- sciCloudStatusCode
- "400"
- sciResponseCode
- "RE"
- sciStatusAction
- "NIN"
- sciGovtStatusCode
- "37025"
- Option 3: Enter an incorrect sender TaxId
-
The sender
TaxId
is incorrect when it is different from the companyTaxId
informed in the invoice. In this scenario, you should receive a success response when reporting an invoice but get an error when polling for notifications, so you will not receive a signed invoice.Note:Both the sender (
SenderCompanyId
) and the company (CompanyCode
)TaxId
are under theStandardBusinessDocumentHeader.BusinessScope.Scope
node.The response should contain the following values:
- sciCloudStatusCode
- "500"
- sciResponseCode
- "RE"
- sciStatusAction
- "OTH"
- Option 4: Enter an incorrect IssueDate
-
The
IssueDate
must be the current date and match the date fromIssueId
. Anything other than the required values will return an error. In this scenario, you should receive a success response when reporting an invoice but get an error when polling for notifications, so you will not receive a signed invoice.The response should contain the following values for a duplicate
IssueId
:- sciCloudStatusCode
- "400"
- sciResponseCode
- "RE"
- sciStatusAction
- "NIN"
- sciGovtStatusCode
- "33127"
Payload samples
Sovos Canonical Invoice (SCI)
The provided SCI and Local XML samples are meant to be guidelines for integration with the Indirect Tax API and should be treated as such, since each integrating system is unique and has different requirements. This means that the samples cannot be copied directly, and must be adapted to your system when integrating with the Indirect Tax API.
<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:chl="ChileExtension.xsd" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:dea="urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2" xmlns:enc="http://www.sovos.com/namespaces/base64Document" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inj="http://www.sovos.com/namespaces/injections" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:leg="http://www.sovos.com/namespaces/sovosExtensions/LegalExtension" xmlns:mex="MexicoExtension.xsd" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#">
<sbd:StandardBusinessDocumentHeader>
<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
<sbd:Sender>
<sbd:Identifier Authority="KR">1232526378</sbd:Identifier>
</sbd:Sender>
<sbd:Receiver>
<sbd:Identifier Authority="KR">0000000000</sbd:Identifier>
</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>2023-11-28T15:42:02Z</sbd:CreationDateAndTime>
</sbd:DocumentIdentification>
<sbd:BusinessScope>
<sbd:Scope>
<sbd:Type>Country</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>KR</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SubSchema</sbd:Type>
<sbd:InstanceIdentifier/>
<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>TaxInvoice</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>CompanyCode</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>1232526378</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Version</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>3.0</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderDocumentId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>000000001</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderSystemId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>ERPSystem</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>ProcessType</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>Outbound</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:Scope>
<sbd:Type>BusinessCategory</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>B2B</sbd:Identifier>
</sbd:Scope>
</sbd:BusinessScope>
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<sci:SovosCanonicalInvoice>
<inv:Invoice>
<cbc:ID>1900051497</cbc:ID>
<cbc:UUID>2024010441000008uup00001</cbc:UUID>
<cbc:IssueDate>2024-01-04</cbc:IssueDate>
<cbc:IssueTime>15:27:17</cbc:IssueTime>
<cbc:InvoiceTypeCode>0101</cbc:InvoiceTypeCode>
<cac:InvoicePeriod>
<cbc:EndDate>2024-01-04</cbc:EndDate>
</cac:InvoicePeriod>
<cac:AccountingSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID schemeID="TaxID">1232526378</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cac:AddressLine>
<cbc:Line>91900 Tyree Springs, South Marisha, WV 46715-4190</cbc:Line>
</cac:AddressLine>
</cac:PostalAddress>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Yellow W Foods Limited</cbc:RegistrationName>
</cac:PartyLegalEntity>
<cac:Person>
<cbc:JobTitle>CEO</cbc:JobTitle>
<cac:Contact>
<cbc:Name>Yellow W Foods Limited</cbc:Name>
</cac:Contact>
</cac:Person>
</cac:Party>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>6222100241</cbc:ID>
</cac:PartyIdentification>
<cac:PostalAddress>
<cac:AddressLine>
<cbc:Line>982 Leonardo Inlet, Hegmannbury, SC 81004-5334</cbc:Line>
</cac:AddressLine>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cac:TaxScheme>
<cbc:ID>01</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Food Service Center </cbc:RegistrationName>
</cac:PartyLegalEntity>
<cac:Person>
<cbc:JobTitle>CEO</cbc:JobTitle>
<cac:Contact>
<cbc:Name>Food Service Center</cbc:Name>
</cac:Contact>
</cac:Person>
</cac:Party>
</cac:AccountingCustomerParty>
<cac:TaxTotal>
<cbc:TaxAmount>347945</cbc:TaxAmount>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
<cbc:ChargeTotalAmount>3479455</cbc:ChargeTotalAmount>
<cbc:PayableAmount>3827400</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
<cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:Note>Hamburguer</cbc:Note>
<cbc:InvoicedQuantity unitCode="EA">10.000</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount>3019091</cbc:LineExtensionAmount>
<cac:TaxTotal>
<cbc:TaxAmount>301909</cbc:TaxAmount>
</cac:TaxTotal>
<cac:Item>
<cbc:Name>Hamburguer</cbc:Name>
</cac:Item>
<cac:Price>
<cbc:PriceAmount>332100</cbc:PriceAmount>
</cac:Price>
</cac:InvoiceLine>
<cac:InvoiceLine>
<cbc:ID>2</cbc:ID>
<cbc:Note>French Fries</cbc:Note>
<cbc:InvoicedQuantity unitCode="EA">4.000</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount>460364</cbc:LineExtensionAmount>
<cac:TaxTotal>
<cbc:TaxAmount>46036</cbc:TaxAmount>
</cac:TaxTotal>
<cac:Item>
<cbc:Name>French Fries</cbc:Name>
</cac:Item>
<cac:Price>
<cbc:PriceAmount>126600</cbc:PriceAmount>
</cac:Price>
</cac:InvoiceLine>
</inv:Invoice>
</sci:SovosCanonicalInvoice>
</svs:SovosDocument>
</sbd:StandardBusinessDocument>
Local format
<sbd:StandardBusinessDocument xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns="http://uri.etsi.org/01903/v1.4.1#" 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:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.sovos.com/namespaces/base64Document">
<sbd:StandardBusinessDocumentHeader>
<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
<sbd:Sender>
<sbd:Identifier Authority="KR">1232526378</sbd:Identifier>
</sbd:Sender>
<sbd:Receiver>
<sbd:Identifier Authority="KR">0000000000</sbd:Identifier>
</sbd:Receiver>
<sbd:DocumentIdentification>
<sbd:Standard>urn:kr:or:kec:standard:Tax:ReusableAggregateBusinessInformationEntitySchemaModule:1:0</sbd:Standard>
<sbd:TypeVersion>3.0</sbd:TypeVersion>
<sbd:InstanceIdentifier/>
<sbd:Type>TaxInvoice</sbd:Type>
<sbd:MultipleType>false</sbd:MultipleType>
<sbd:CreationDateAndTime>2023-11-28T15:42:02Z</sbd:CreationDateAndTime>
</sbd:DocumentIdentification>
<sbd:BusinessScope>
<sbd:Scope>
<sbd:Type>Country</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>KR</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SubSchema</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier/>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Mapping.TransformDocument</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>LEGAL-TO-SCI_INVOICE</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Mapping.OutputSchema</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>TaxInvoice</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>CompanyCode</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>1232526378</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Version</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>3.0</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderDocumentId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>000000001</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderSystemId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>ERPSystem</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>ProcessType</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>Outbound</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:Scope>
<sbd:Type>BusinessCategory</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>B2B</sbd:Identifier>
</sbd:Scope>
</sbd:BusinessScope>
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<svs:SovosLegalDocument>
<enc:Base64Document>
<enc:EmbeddedDocument mimeCode="application/xml">
<TaxInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:kr:or:kec:standard:Tax:ReusableAggregateBusinessInformationEntitySchemaModule:1:0" xsi:schemaLocation="urn:kr:or:kec:standard:Tax:ReusableAggregateBusinessInformationEntitySchemaModule:1:0 http://www.kec.or.kr/standard/Tax/TaxInvoiceSchemaModule_1.0.xsd">
<ExchangedDocument>
<ID>1900051497</ID>
<IssueDateTime>20240104152717</IssueDateTime>
</ExchangedDocument>
<TaxInvoiceDocument>
<IssueID>2024010441000008uup00001</IssueID>
<TypeCode>0101</TypeCode>
<IssueDateTime>20240104</IssueDateTime>
</TaxInvoiceDocument>
<TaxInvoiceTradeSettlement>
<InvoicerParty>
<ID>1232526378</ID>
<NameText>Yellow W Foods Limited</NameText>
<SpecifiedPerson>
<NameText>Yellow W Foods Limited</NameText>
</SpecifiedPerson>
<SpecifiedAddress>
<LineOneText>91900 Tyree Springs, South Marisha, WV 46715-4190</LineOneText>
</SpecifiedAddress>
</InvoicerParty>
<InvoiceeParty>
<ID>6222100241</ID>
<NameText>Food Service Center </NameText>
<SpecifiedOrganization>
<BusinessTypeCode>01</BusinessTypeCode>
</SpecifiedOrganization>
<SpecifiedPerson>
<NameText>Food Service Center</NameText>
</SpecifiedPerson>
<SpecifiedAddress>
<LineOneText>982 Leonardo Inlet, Hegmannbury, SC 81004-5334</LineOneText>
</SpecifiedAddress>
</InvoiceeParty>
<SpecifiedMonetarySummation>
<ChargeTotalAmount>3479455</ChargeTotalAmount>
<TaxTotalAmount>347945</TaxTotalAmount>
<GrandTotalAmount>3827400</GrandTotalAmount>
</SpecifiedMonetarySummation>
</TaxInvoiceTradeSettlement>
<TaxInvoiceTradeLineItem>
<SequenceNumeric>1</SequenceNumeric>
<DescriptionText>Hamburguer</DescriptionText>
<InvoiceAmount>3019091</InvoiceAmount>
<ChargeableUnitQuantity unitCode="EA">10.000</ChargeableUnitQuantity>
<NameText>Hamburguer</NameText>
<TotalTax>
<CalculatedAmount>301909</CalculatedAmount>
</TotalTax>
<UnitPrice>
<UnitAmount>332100</UnitAmount>
</UnitPrice>
</TaxInvoiceTradeLineItem>
<TaxInvoiceTradeLineItem>
<SequenceNumeric>2</SequenceNumeric>
<DescriptionText>French Fries</DescriptionText>
<InvoiceAmount>460364</InvoiceAmount>
<ChargeableUnitQuantity unitCode="EA">4.000</ChargeableUnitQuantity>
<NameText>French Fries</NameText>
<TotalTax>
<CalculatedAmount>46036</CalculatedAmount>
</TotalTax>
<UnitPrice>
<UnitAmount>126600</UnitAmount>
</UnitPrice>
</TaxInvoiceTradeLineItem>
</TaxInvoice>
</enc:EmbeddedDocument>
</enc:Base64Document>
</svs:SovosLegalDocument>
</svs:SovosDocument>
</sbd:StandardBusinessDocument>