Configuration

Starting with version 2 of the Configurations resource, clients can now create the necessary information to start archiving invoices.

Other backend configuration is handled by the Sovos Professional Services team during the implementation phase. If the Company already exists and the client is using the CTC process for a specific country, then a separate configuration for archiving isn't needed.

Prerequisites

These are the configuration prerequisites:

An account on developer.sovos.com to use Configurations v2. This also requires customers (for now) to contact Sovos' Professional Services team to obtain special authorization to use it and to obtain their organization ID.
A configured company and product.

Note:

Organization IDs differ between Sandbox and Production.

Once customers have access to Configuration v2 and have obtained their Organization ID, they can call the dedicated Create a Company endpoint to create a company and assign a product.

Create a Company and Assign a Product

Sandbox: To create a company with a product in the Sandbox environment, use https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies by configuring the company with the Sovos Professional Services team or choosing self-service as an option.
Production: To create a company with a product in the Production environment, use https://api.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies and the credentials obtained from developer.sovos.com, along with the appropriate organization ID.

Note:

If the products array is empty, the created Company will acquire all the products assigned to the organization.

Always save the company ID value from the response when creating a company, as it will be required for future calls. To find it, look for the YOUR-COMPANYID value in the samples.

Request Samples

Here is a request sample for creating a company and assigning a product:

curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "taxId": "YOUR-TAXID",
    "legalName": "YOUR-LEGAL-NAME",
    "dba": "YOUR-DOING-BUSINESS-AS-NAME",
    "products": ["pl_Faktura__1.0", "pl_Faktura_Polling_1.0"]
}'

Here is a request sample for creating a company and assigning a product (with an empty products list):

curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "taxId": "YOUR-TAXID",
    "legalName": "YOUR-LEGAL-NAME",
    "dba": "YOUR-DOING-BUSINESS-AS-NAME",
    "products": []
}'

Here is a request sample for adding products to a company:

curl --location --request PUT 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies/YOUR-COMPANYID/products' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "items": ["NEW-PRODUCT"]
}'

Response Samples

Here is a response sample for creating a company and assigning a product:

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1672405631469,
    "data": {
        "id": "YOUR-COMPANYID",
        "orgId": "YOUR-ORG-ID",
        "taxId": "YOUR-TAXID",
        "legalName": "YOUR-LEGAL-NAME",
        "dba": "YOUR-DOING-BUSINESS-AS-NAME",
        "createdAt": "2022-12-30T13:07:10.8491501Z",
        "createdBy": "user@company.com"
    }
}

Here is a response sample for adding products to a company:

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1687903917359,
    "data": {
        "items": [
            "NEW-PRODUCT"
        ]
    }
}

Error Handling

The client must adhere to the error handling principles, outlined on the responses page.

In general, all error codes in the 400 range are client errors and must be analyzed by the client. After fixing the error, the client can try to resend the request. Error codes 408 and 429 are exceptions, in these cases the client must wait 60 seconds before retrying. The error codes in the 500 range are server errors, in case of such an error, the client should retry sending the request, according to the instructions given on the responses page which also includes a full list of error codes the API can return.

Sovos Docs

Configuration

Prerequisites

Create a Company and Assign a Product

Error Handling

sovos-footer