Tax Declarations UI

From the Tax Declarations page of the SBS portal, you can perform the following actions:

• Generate tax declarations and track their status
• View all tax declarations for the currently selected account, application, tenant, and organization
• View all representatives and update their details (first name, last name, phone, email address).
• For each declaration, you can view its processes, input files, and representative details
• Filter, search and sort tax declarations.

Access

You can access the Tax Declarations page of the portal as follows:

1. Sign in to the SBS Portal. During the sign-in process, you will be prompted to select the account, app, and tenant where you are entitled to sign in.
2. Click tax-declarations-api in the left hand-side menu.
3. If applicable, select the organization from the drop-down list at the top of the page.

To interact with the Tax Declarations service, you can use either the Web UI or a GraphQL interface. You can switch at any time between the two interfaces by clicking the switch displayed at the top of the page:

View tax declarations

After you access the Tax Declarations UI, the tax declarations stored in SBS for the selected account, application, and tenant are displayed in the upper grid. To view details about a particular tax declaration, click the respective row in the grid. This loads all processes, files and representative details of that declaration in the lower grid, for example:

Tax declaration structure

The table below shows the declaration fields that are exposed through the Web UI. To return a declaration’s full list of fields, query it through GraphQL.

Process structure

A tax declaration may have multiple processes. A new process is created every time the declaration is computed (through a call to generateDeclaration mutation). A tax declaration’s process has the following structure:

Field	Description
ID	The unique identifier of the process in SBS.
Status	The status of the declaration. Valid values: NEW - computation has not started yet, INPROCESS - computation is in progress, DONE - computation has completed without errors, ERROR - computation has completed with errors.
Errors	This fields reports errors that occurred during processing, if applicable.
Created at	The date and time when the process was created.
	Click the icon to download the declaration’s result file to the local disk.

File structure

A tax declaration may have multiple input files. A tax declaration’s file has the following structure:

Representative structure

A tax declaration has one representative (that is, the legal person who submits the tax declaration). A tax declaration’s representative has the following structure:

Filter, search, and sort tax declarations

To filter tax declarations by the values displayed in the grid, click the Filter icon on the respective column header in the grid. The colour of the Filter icon on each column header denotes whether the filter is active:

Icon	Meaning
	Filter is not active
	Filter is active

To search tax declarations, type your search text in the Search text box available in the right-upper corner of the grid. You can use any field as search term (for example, the tax declaration ID).

To sort tax declarations, click the respective column of the grid. The arrow indicates the current sorting order.

Generate declarations

The high-level steps for generating a declaration are as follows:

1. Obtain from your ERP system the input CSV files to be used as input to the tax declaration.
2. Create a representative.
3. Initiate the declaration.
4. Add the input CSV files to the declaration.
5. Generate the declaration.
6. View the declaration status and download the result file.

Step 1: Obtain the input CSV files from your ERP

A tax declaration will typically need the following CSV files as input (depending on the case, fewer files will be required):

1. BusinessPartners.csv
2. GeneralLedgerAccounts.csv
3. GeneralLedgerEntries.csv
4. Invoices.csv
5. Payments.csv
6. PhysicalStock.csv
7. MovementOfGoods.csv
8. Assets.csv
9. AssetTransactions.csv

The file names above are just an example; the actual file names may differ. Also note that you may provide multiple files of the same type as input. For example, you may use multiple CSV files of type “Invoice”.

For the expected structure of each file, see Appendix A: Input CSV Files.

Step 2: Create a representative

A representative is the person that submits the declaration from a legal perspective. To create a declaration, at least one representative must be defined. Once added, you can use the representative’s details in multiple declarations.

To create a representative:

1. Click the Representatives button at the top of the page.
2. In the representatives grid, click Add and fill in the representative’s information. The fields First name, Last name, and Phone are mandatory.

3. Click Save.

You can update a representative’s details at any time later. To do that, click the Update button for the respective row on the grid.

Deleting representatives is available only through GraphQL. To do that, run the deleteRepresentative mutation of the Tax Declarations Service.

Step 3: Initiate the declaration

To initiate a declaration:

1. Click Declarations at the top of the page.

2. If applicable, select an organization from the drop-down list.

3. In the declarations grid, click Add and fill in the declaration details, for example:

   

4. Click Initiate. A new dialog box pops up where you can add the input CSV files to the declaration.

Step 4: Add the input CSV files

After you initiate a declaration, a dialog box pops up from where you can add the input CSV files to the declaration.

To add input CSV files to a declaration:

1. Click Add .

2. In the dialog box that pops up, select a file type (for example “Invoices”), and then click Select CSV Files(s) to add the respective file from your hard drive.

   

3. Click Add, and be patient while the file is uploading. The upload may take several seconds to several minutes, depending on the size of the input file, and your internet connection speed. After a successful upload, the dialog box closes, and the declaration file should appear in the list of declaration files.

4. Repeat steps 1-3 for all files that should be added as input to the declaration.

Step 5: Generate the declaration

After you have added all files to the declaration, you can trigger the actual generation process.

To generate the declaration, click Update and Run. The declaration dialog box closes, and you can now track the declaration status from the Processes tab.

Step 6: View the declaration status and download the result file

Whenever you run a declaration, a new process is added to the declaration that reports its status. Note that, if you run the same declaration multiple times, a new process will start for each run.

To view a declaration’s processes, click a declaration record in the Declarations grid. The lower grid should now be populated with that declaration’s processes, if any (in the “Processes” tab). The declaration’s files and representatives can be viewed from the Files and Representative tabs, respectively.

Initially, each process has the status NEW. After a short time (approx. 1 minute), the status changes to INPROCESS. This status will keep showing for as long as the declaration is being computed, which may take several minutes to several hours, depending on the size of the input files.

The Processes grid does not refresh automatically; click Refresh to obtain the latest process status.

If validation or other errors are encountered during the computation, the process status changes to ERRORS and the actual errors are reported in the respective column.

If the declaration was generated successfully, the process status changes to DONE, and an XML download icon becomes available. Click the icon to download the generated declaration file.

Delete declarations

You can delete declarations only from the GraphQL interface.

To delete a declaration from GraphQL:

1. Switch to the GraphQL interface.
2. Run the deleteDeclaration mutation.

An example is provided below. Make sure to replace the input data as applicable.

mutation deleteDeclaration($id:ID!) {
  deleteDeclaration(id:$id) {
    id
  }
}

{
  "id": "YOUR_DECLARATION_ID"
}

For details, see the API reference to the Tax Declarations Service.

GraphQL

Query tax declarations

To query tax declarations through GraphQL:

1. Switch to the GraphQL interface.
2. Run the declarations query of the Tax Declaration Service, for example:

query declarations ($filter:DeclarationsFilter!, $processFilter:ProcessesFilterInput) {
  declarations(filter:$filter) {
    id
    organization { id, name, tin }
    representative { id, firstName, lastName, phone, email }
    headerComment 
    from
    to
    files { id, fileType, name, createdAt }
    processes (filter: $processFilter) {
      id, 
      status, 
      errorMessages,
      createdAt,
      result { id name createdAt downloadUrl(expiresIn:3600) },
      totals {
          csvLines {
              generalLedgerAccounts
              businessPartners
              assets
              physicalStock
              generalLedgerEntries
              invoices
              payments
              movementOfGoods
              assetTransactions
              allFileLines
          }
          csvBusinessPartnerAccountTotals {
              accountID
              debitCredit {
                  totalDebitOpen
                  totalDebitClose
                  totalCreditOpen
                  totalCreditClose
              }
          }
          csvGeneralLedgerAccountsMonthTotals {
                totalDebitOpen
                totalDebitClose
                totalCreditOpen
                totalCreditClose
          }
          csvGeneralLedgerEntriesMonthTotals {
              totalCredit
              totalDebit
          }
          csvInvoiceTotals {
              allInvoices
              customerInvoices
              supplierInvoices
              customerInvoicesTotal
              supplierInvoicesTotal
              customerInvoicesCurrencyTotal {
                  currency
                  amount
              }
              supplierInvoicesCurrencyTotal {
                  currency
                  amount
              }
          }
          csvPaymentTotals {
              allPayments
              debitPayments
              creditPayments
              debitTotal
              creditTotal
              debitCurrencyTotal {
                  currency
                  amount
              }
          }
      },
    }
    createdAt
  }
}

{
  "filter": {
    "id": "YOUR_DECLARATION_ID",
    "organizationId": "YOUR_ORGANIZATION_ID"
  }
}

Generating declarations

For instructions about generating a declaration through GraphQL, see the Generating declarations section of the Tax Declaration API reference.