Invoices cannot be stored for an Invoicing Party. The Invoicing Party exists as either just a trading partner (without archiving capabilities), or it can become a User Organization (with archiving capabilities) at a later stage (see step 2).

The following design considerations for the request parameters should be taken into account:

countryCode

The countryCode parameter must be set in the request for a legal entity's country of establishment to be taken into account when calculating the storage period for the invoice. Hence, the countryCode value determines the storage period. The value of the countryCode parameter must be an ISO 3166-1 alpha-2 country code.

You'll need to implement a filtering function, so that the countryCode parameter can only be set to a country code that's supported by Sovos eArchive.

Note:

Once a country code has been set, it cannot be changed.

Note:

If there are Hungarian or Italian legal unit(s) for which the countryCode parameter is set to "HU" or "IT", then the Hungarian or Italian e-invoices must be stored in this section. This is required for the Hungarian and Italian preservation (time-stamping) processes.

companyId

The companyId parameter in the request should be a unique identity of an Invoicing Party you have defined, e.g., an existing identity number within your e-invoicing network.

Note:

The companyId shouldn't contain any white spaces.

name

The name parameter in the request should be the full name of the legal entity for which the company is created.

Note:

See the API Specifications page for more information about the request.

curl --location --request POST 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
    "companyId": "CompanyX",
    "name" : "Company X Ltd."
}'

Response sample

{
    "success": true,
    "status": 200,
    "message": "Company created",
    "timestamp": 637274678557640000,
    "data": {}
}

To make this request, set the following parameters:

Name	Type	Required	Parameter Type	Description
countryCode	string	Yes	Path	Set it to the same country code used in step 1.
companyId	string	Yes	Path	Set it to the company ID of the company registered in step 1.
status	string	Yes	Request body	Set it to "Enabled".

Request sample

curl --location --request PATCH 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--data-raw '{
	"status": "Enabled"
}'

Response sample

{
    "success": true,
    "status": 200,
    "message": "Company Enabled",
    "timestamp": 1603098455907,
    "data": {
        "superAdminUsername": "SuperAdmin",
        "superAdminPwd": "kpK5We",
        "companyPath": "/archive/CompanyGroup/CompanyXYZ"
    }
}

There are several API endpoints available for maintaining and monitoring all created companies:

Reset Company Password

In case the SuperAdmin credentials have been lost, it's possible to send a POST request to the /config/{countryCode}/companies/{companyId}/reset-password endpoint with the input parameters countryCode and companyId. This request call returns a new password for the SuperAdmin user of the given company.

To make this request, set the following path parameters:

Name	Type	Required	Description
countryCode	string	Yes	Set it to the same country code used in step 1.
companyId	string	Yes	Set it to the company ID of the company registered in step 1.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}/reset-password' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "success": true,
    "status": 200,
    "message": "Password Reset",
    "timestamp": 1603099522229,
    "data": {
        "superAdminPwd": "o7KHFy"
    }
}

List Companies

To obtain a list of all registered companies, it's possible to send a GET request to the /config/{countryCode}/companies endpoint. This gives an overview of all companies registered in your area.

To make this request, set the following parameters:

Name	Type	Required	Parameter Type	Description
countryCode	string	Yes	Path	Set it to the country code, as specified by the ISO 3166-1 alpha-2 standard.
perPage	integer	Yes	Query	Set it to the maximum number of hits to return.
page	integer	Yes	Query	Specifies the starting point of the hits to be returned.

Note:

Although the country code is specified in the path, the output is a list of all the companies created in your area, so it doesn't return, for example, only Indian companies.

Note:

See the API specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample

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

Response sample

{
    "success": true,
    "status": 200,
    "message": "Companies Listed",
    "timestamp": 1602770463414,
    "data": {
        "pageState": {
            "page": "1",
            "perPage": "2",
            "moreResults": "true"
        },
        "items": [
            {
                "name": "CompanyX"
            },
            {
                "name": "CompanyY"
            }
        ]
    }
}

Get Company Information

This endpoint can be used to retrieve information from a given company. Send a GET request to the /config/{countryCode}/companies/{companyId} endpoint.

To make this request, set the following path parameters:

Name	Type	Required	Description
countryCode	string	Yes	Set it to the country code, as specified by the ISO 3166-1 alpha-2 standard.
companyId	string	Yes	Set it to the company ID of the company registered in step 1.

Note:

See the API specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample

curl --location --request GET 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "success": true,
    "status": 200,
    "message": "Company Returned",
    "timestamp": 1602771739509,
    "data": {
        "metadata": {
            "archivePath": "/archive/CompanyX/08AAACI9260R002",
            "storageInfo": {
                "friendlyName": "Company X Ltd.",
                "countryOfEstablishment": "IN"
            },
            "status": "Registered"
        }
    }
}