Tax Declarations Service

The Tax Declarations service enables calling applications to generate the SAF-T XML file (Standard Audit File for Tax) required for mandatory tax reporting to Bulgarian and Romanian tax authorities.

Access info

Usage

Prerequisites

• The organization(s) for which reporting is done must exist in the SBS system. You can add new organizations either from the SBS Portal or programmatically by calling the Organizations Service.
• The organization object in SBS must contain at least the following fields: name, tin (Tax Identification Number), regNo (registration number issued by the National Trade Registration Office), country, streetAddress, ibanNumber, taxAccountingBasis.
• For Bulgarian tax declarations, the organization’s ownership structure must be defined (ownershipStructureBG) in accordance with the rules laid out for elements S.O.1 through S.O.11 in the SAF-T Schema. You can define these fields when creating or updating the organization, either from the SBS Portal or programmatically by calling the createOrganization or updateOrganization mutations of the Organizations Service.
• You must prepare several CSV files to be used as input to te Tax Declarations service. The exact set of files depends on the audit file country and the tax residence status of the reporting organization. Typically, an API caller generates or exports the CSV files from an enterprise resource planning (ERP) system. For details, see:
  • Appendix 1: Input CSV Files (Romania Tax Residents)
  • Appendix 2: Input CSV Files (Romania Non-Residents)
  • Appendix 3: Input CSV Files (Bulgaria Tax Residents).

SAF-T Schema

Bulgaria

The SAF-T schema files for Bulgaria can be downloaded from https://nra.bg/wps/portal/nra/proekti/sistema-za-schetovodno-otchitane/sistema-za-schetovodno-otchitane.

Romania

The Romanian National Agency of Fiscal Administration (ANAF) has published (and periodically updates) an Excel sheet which contains information about the structure of the SAF-T file, field validation rules and format, as well as valid codes required for specific field types. The file is called “Schema Fișierul Standard de Control (Standard Audit File – SAF-T)” and will be subsequently referred to as the SAF-T Schema in this documentation.

To locate the SAF-T schema on ANAF website (https://anaf.ro), navigate to Despre ANAF > Strategii ANAF > Proiecte de digitalizare > SAF-T and look for the most recently published version of the “schema xls” file.

Generating a declaration

To generate a declaration:

1. Obtain from your ERP system the input CSV files to be used as input to the tax declaration. For the structure of each file, see:

   • Appendix 1: Input CSV Files (Romania Tax Residents)
   • Appendix 2: Input CSV Files (Romania Non-Residents)
   • Appendix 3: Input CSV Files (Bulgaria Tax Residents).

2. Create a representative through a call to the createRepresentative mutation.

3. Initiate a declaration through a call to the initiateDeclaration mutation. As a result, a new declaration object is created, and the response contains the unique declaration ID. You will need to work with this declaration ID in subsequent steps to further process the declaration and monitor its status.

4. Add all the input CSV files to the declaration. See Preparing declaration files. Upload every mandatory file for the declaration’s headerComment, and only file types that this declaration type permits; otherwise, the next step fails. See Appendix 10: Input file types by declaration type (Romania).

5. Run the generateDeclaration mutation. This triggers a computation that takes place from several minutes to several hours, depending on the size of input CSV files. In either case, the outcome, including any possible errors, is reported in the returned Process object. If the computation was successful, the response includes a download URL at which you can download the generated XML file.

Preparing declaration files

After you have initiated the declaration, you can add all the CSV input files to it.

For each input CSV file, the steps are as follows:

• Run the prepareFile mutation. In the response, you get the file’s upload URL at which you can upload the actual file.
• In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL. This step is similar to how you would create a file and then upload its content in the File Management Service, as described in the Tutorial: Create a file.

Note that you can add multiple files of the same type for the same declaration. For example, you can add several input CSV files of type “Invoices”. If multiple files of the same type exist, SBS will aggregate and compute data found in all respective files.

After adding all the CSV files, you can check if they are indeed attached to the declaration by running the declarations query, 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 }
    createdAt
  }
}

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

If your declaration looks good so far, you can proceed to running the generateDeclaration mutation, for example:

mutation generateDeclaration($declarationId:ID!) {
  generateDeclaration(declarationId:$declarationId) {
    id
    status
  }
}

{
    "declarationId": "YOUR_DECLARATION_ID"
}

Dealing with large input files

As mentioned above, when you add a file to the declaration, there are two steps involved:

1. Run prepareFile and obtain the upload URL.
2. In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL.

For the second step, note, however, that the maximum file size that you can send in a single PUT request is 5 GB. Should you need to add larger files to the declaration, you can do so through the multipart upload mutations provided by the File Management Service. In this scenario, the process looks as follows:

1. Run prepareFile and take note of the data.prepareFile.id returned in the response body. This ID corresponds to a file id of a file in File Management Service.
2. Provide the id above as input to the initiateMultipartUpload mutation and continue with the rest of steps required for multipart upload, as described in Uploading large files.

Processes

Each time when you run generateDeclaration, a new process with status NEW is attached to the declaration. You can view the declaration and the status of all its processes by running the declarations query and requesting the processes field in the response, for example:

query declarations ($filter:DeclarationsFilter!) {
  declarations(filter:$filter) {
    id
    processes{
      id,
      status,
      errorMessages,
      totalSegmentsInSequence,
      createdAt,
      result {
        id
        name
        createdAt
        downloadUrl(expiresIn:3600)
      }      
    }
    createdAt
  }
}

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

The status of any process is initially NEW. The status NEW will normally change to INPROCESS after approximately 1 minute. Note that, if you run generateDeclaration multiple times for the same declaration, each run will start a new process for the same declaration. In this case, you will need to track the status of each process separately. The processes field of the declarations query provides a filter (by process ID) for that purpose.

The INPROCESS status of a process may take from a few minutes to a few hours, depending on the size of the input CSV files. After the INPROCESS status, the status may change to either ERROR (if errors are encountered) or DONE (upon successful processing).

If the status is ERROR, the process reports what went wrong in two fields:

• errorMessages — a human-readable summary, with one entry per failed rule and up to ten example records each.
• errors — one finding per offending input line, with a stable rule code and the identifiers that locate the record in your ERP system. See Reading validation errors.

If the process completes with status DONE, it generates a result XML file whose download URL is available in the result response field of the respective process. Also, the totals counters of the declaration object are now populated with data as computed from the input CSV files.

Additionally, when the process status is DONE for a monthly Romanian D406 declaration, the roD406AnalysisData field of the process is populated with financial KPIs. This data is also accessible directly via the roD406AnalysisData query.

If necessary, you may stop a running process through a call to killProcess. However, this is possible only if the process has not generated any results (that is, if the result field of the process is empty).

You may also delete a process through the deleteProcess mutation. Deleting a running process is possible only if the process has generated no result yet.

Reading validation errors

When the input CSV files fail validation, the process ends with status ERROR, and its errors field lists every offending input line as a ProcessValidationError. Each finding carries:

• a code that identifies the rule, so that your ERP system can react to each kind of problem. See Appendix 11: Validation rule codes.
• the fileType and, when the rule checks a single column, the field that holds the wrong value.
• the identifiers of the record — documentId, documentContextId, systemId, and lineId — and a documentDescription, so that you can direct your users to the document that needs correcting. See Identifiers per file type.
• a message in the language of the declaration.

The findings are paginated. Request the first page without nextToken, then pass the returned nextToken to get the next page, until nextToken is null. totalCount reports the number of findings across all pages. For example:

query declaration($id:ID!, $processFilter:ProcessesFilterInput, $nextToken:String) {
  declaration(id:$id) {
    processes(filter:$processFilter) {
      id
      status
      errorMessages
      errors(limit:100, nextToken:$nextToken) {
        totalCount
        nextToken
        items {
          code
          fileType
          field
          documentId
          documentContextId
          documentDescription
          systemId
          lineId
          message
        }
      }
    }
  }
}

{
  "id": "YOUR_DECLARATION_ID",
  "processFilter": {
    "id": "YOUR_PROCESS_ID"
  }
}

Deleting declarations

You can delete declarations through a call to deleteDeclaration. Note, however, that it is not possible to delete a declaration if it has at least one running process that has already generated some result file. To delete such a declaration, you will need to wait for the process to finish first.

Validation

Validation of data provided as input to the Tax Declarations service takes place at two levels:

1. A first validation takes place after you submit the generateTaxDeclaration mutation. This validation is performed by the SBS API. Any errors encountered at this stage are reported in the errorMessages and errors attributes of the returned Process object. See Reading validation errors.
2. A second level of validation is provided by the DUK Integrator tool available for download from the ANAF website (https://anaf.ro). The same tool is used to generate the PDF (including the signed XML SAF-T file) that is to be submitted to ANAF. To download the tool, navigate to Despre ANAF > Strategii ANAF > Proiecte de digitalizare > SAF-T and look for the latest available version of the validator.

In addition to the two validation levels above, ANAF defines a set of consistency tests that are not necessarily covered by the DUK Integrator tool. For Romanian D406 declarations, the results of these tests are returned in the validations field of ROD406AnalysisData, as a list of ROD406Validation objects.

These consistency tests have recommendation status only: because some of them can yield false positives in situations to which they do not apply, a failed test does not prevent a declaration from being generated or submitted, and is surfaced for your awareness.

The tests are as defined in the following ANAF communiqués:

• Set 1: comunicat_saft_teste_v2.pdf
• Set 2: testedeconsistenta2.pdf

Alongside the tests ANAF publishes, the validations field carries five additional checks that verify the dates on your records fall inside the declaration’s reporting period. ANAF rejects a D406 file whose document dates lie outside the declared period, so these checks catch such records before you submit. They are identified by four-letter codes rather than ANAF test numbers. See Period-date checks.

How to view consistency-test results

The consistency tests are evaluated together with the RO D406 analysis data when you generate a Romanian D406 declaration, so no separate request is needed to run them. Once the declaration has been computed, you read the results from the validations field of ROD406AnalysisData.

To obtain the consistency-test results for a declaration:

1. Generate the declaration as described in Generating a declaration, and take note of the process id returned by the generateDeclaration mutation.
2. Wait for the process to reach status DONE. You can poll the process status through the declarations query, as shown under Processes.
3. Once the process is DONE, call the roD406AnalysisData query with the organization ID, declaration ID, and process ID, requesting the validations field. Until the analysis data has been computed, the query returns null.
4. Inspect each returned ROD406Validation object. The status indicates the outcome of the test (SUCCEEDED, FAILED, or SKIPPED). For a FAILED test, the message field carries the failure reason; a SKIPPED test may also carry a message explaining why the test did not apply.

Remember that these results are informational only: a FAILED consistency test does not prevent the declaration from being generated or submitted.

Period-date checks

Five of the validations verify that the dates on your records fall inside the declaration’s reporting period. Each one covers a single input file type and checks that file type’s primary date:

Each check reports one of three outcomes:

• SUCCEEDED — every date in the file falls inside the period. A file that contains no records also succeeds.

• FAILED — at least one date falls outside the period. The message reports how many records are out of period, then lists up to 10 of them as the record identifier paired with its out-of-period date. When more than 10 records are out of period, the message ends with a (+N more) suffix so that it stays a manageable length. For example:

  3 Invoices record(s) with InvoiceDate outside [2024-03-01, 2024-03-31]: InvoiceNo 4521 (2024-02-28), InvoiceNo 4530 (2024-04-02), InvoiceNo 4533 (2024-04-05)

• SKIPPED — the declaration has no file of that type, so the check has nothing to examine. The message reads No <file type> file was provided for the declaration, for example No Payments file was provided for the declaration. A SKIPPED result is routine — each declaration type accepts only some of the nine input file types (see Appendix 10: Input file types by declaration type (Romania)) — and says nothing about the quality of your data.

Both ends of the period count as inside it: a record dated exactly on from or exactly on to is never reported. A record with an empty date is ignored, because there is nothing to compare with the period.

Example

query roD406AnalysisData($organizationId:ID!, $declarationId:ID!, $processId:ID!) {
  roD406AnalysisData(
    organizationId: $organizationId
    declarationId: $declarationId
    processId: $processId
  ) {
    validations {
      code
      description
      status
      message
    }
  }
}

{
  "organizationId": "YOUR_ORGANIZATION_ID",
  "declarationId": "YOUR_DECLARATION_ID",
  "processId": "YOUR_PROCESS_ID"
}

A declaration returns the full standard list of tests. The description field is in Romanian — quoted from the ANAF communiqués for the numbered tests, and describing the date checked for the period-date checks. The message field for a FAILED or SKIPPED test is in English. A sample response, abbreviated to one test of each status plus one period-date check, looks as follows:

{
  "data": {
    "roD406AnalysisData": {
      "validations": [
        {
          "code": "1.1",
          "description": "În secțiunea Header, subsecțiunea Header Structure - Company - Company Header Structure - Adress - verificarea completării câmpurilor City și Country",
          "status": "SUCCEEDED",
          "message": null
        },
        {
          "code": "1.5",
          "description": "În secțiunea Master File, subsecțiunea General Ledger Accounts verificarea completării câmpurilor: Account ID, Account description, Account Type, Opening Debit/Credit Balance, Closing Debit/Credit Balance",
          "status": "FAILED",
          "message": "29 account(s) missing required fields (AccountID, AccountDescription, AccountType, or balance fields)"
        },
        {
          "code": "1.14",
          "description": "În secțiunea Master File verificarea soldurilor finale (Closing Debit Balance și Closing Credit Balance) ale lunii să coincidă cu soldurile inițiale (Opening Debit Balance și Opening Credit Balance) ale lunii următoare",
          "status": "SKIPPED",
          "message": "Single-period declaration (period null/null): cross-period validation requires data from consecutive declarations"
        },
        {
          "code": "INVD",
          "description": "În secțiunea Source Documents - Sales/Purchase Invoices se verifică dacă data facturii (InvoiceDate) se încadrează în perioada de raportare a declarației.",
          "status": "FAILED",
          "message": "2 Invoices record(s) with InvoiceDate outside [2024-03-01, 2024-03-31]: InvoiceNo 4521 (2024-02-28), InvoiceNo 4530 (2024-04-02)"
        }
      ]
    }
  }
}

Comparing tax reported per tax code

For a Romanian D406 declaration, the tax base and tax amount reported for a given tax code should agree across the three SAF-T sources — General Ledger Entries (GLE), Invoices, and Payments — and the applied rate should match the official rate ANAF publishes for that code.

The taxCodeCentralizer field of ROD406AnalysisData surfaces these numbers per tax code so you can spot such discrepancies without cross-checking the raw CSV files by hand. It is computed together with the declaration, so no separate request is needed. Each ROD406TaxCodeCentralizerEntry reports the tax base, tax amount, and tax percentage aggregated independently from each source, alongside the code’s official name and percentage from the ANAF nomenclature.

To read the centralizer for a declaration:

1. Generate the declaration as described in Generating a declaration, and take note of the process id returned by the generateDeclaration mutation.
2. Wait for the process to reach status DONE, polling the process status through the declarations query as shown under Processes.
3. Call the roD406AnalysisData query with the organization ID, declaration ID, and process ID, requesting the taxCodeCentralizer field. Until the analysis data has been computed, the query returns null.
4. Inspect each entry. Compare gle, invoices, and payments against one another, and their taxPercentage against nomenclaturePercentage, to find inconsistencies.

The centralizer is populated only for resident monthly (L) and quarterly (T) declarations. It is null for annual (A), on-request (C), and non-resident (NL, NT) declarations. A source object is null when that source reports no rows for the tax code, and nameRo, nameEn, and nomenclaturePercentage are null when the code is not present in the ANAF nomenclature. Divergent rates are reported as they occur and are not reconciled: if the same code carries different rates across sources, each source keeps its own.

A sample response, abbreviated to one code reported by all three sources and one code whose rate differs between sources, looks as follows:

{
  "data": {
    "roD406AnalysisData": {
      "taxCodeCentralizer": [
        {
          "taxCode": "301104",
          "nameRo": "Achiziţii de bunuri şi servicii taxabile cu cota de 9%",
          "nameEn": "Acquisitions of goods and services taxable at a rate of 9%",
          "nomenclaturePercentage": 9,
          "gle": { "taxBase": 4825.00, "taxAmount": 1013.25, "taxPercentage": 21 },
          "invoices": { "taxBase": 4825.00, "taxAmount": 434.25, "taxPercentage": 9 },
          "payments": null
        },
        {
          "taxCode": "310344",
          "nameRo": "Livrări de bunuri şi prestări de servicii taxabile cu cota 21%",
          "nameEn": "Supplies of goods and services taxable at a rate of 21%",
          "nomenclaturePercentage": 21,
          "gle": { "taxBase": 13250.00, "taxAmount": 2782.50, "taxPercentage": 21 },
          "invoices": { "taxBase": 13250.00, "taxAmount": 2782.50, "taxPercentage": 21 },
          "payments": { "taxBase": 8350.00, "taxAmount": 1753.50, "taxPercentage": 21 }
        }
      ]
    }
  }
}

In this example, tax code 301104 is reported by GLE at 21% but by Invoices at 9% (which matches its official nomenclaturePercentage), signalling a rate inconsistency to investigate, while 310344 is consistent across every source and matches the nomenclature.

Service plans

Your tenant’s service plan for this service decides which features you can use. The STANDARD plan applies by default. To check or change your tenant’s plan, use the Account API’s servicePlans query and setServicePlan mutation.

On the LIMITED plan:

• When you create a KPI declaration with initiateDeclaration, or compute one with generateDeclaration, the call fails with the error code PLAN_FEATURE_NOT_AVAILABLE.
• Your Romanian D406 declarations complete without analysis data. The roD406AnalysisData query and the analysisDataViewerUrl field of the Process type return null, without an error.
• Declarations you compute add no mappings to supplierProductMappings.

Analysis data and supplier product mappings that you obtained before your tenant moved to the LIMITED plan stay available.

If your tenant moves back to the STANDARD plan, you get analysis data for the declarations you compute from then on. To obtain analysis data for a declaration you computed on the LIMITED plan, run generateDeclaration again for that declaration.

The plan applies to this service only. A LIMITED plan that your tenant has for another service does not change what you can do here.

Queries

declarations

Lists the declarations defined for the given tenant. The results of their computation processes can be found in the corresponding declaration process list.

Arguments

DeclarationsFilter input

Result

Declaration type

Representative type

File type

ProcessesFilter input

Process type

ProcessValidationErrorList type

ProcessValidationError type

Identifiers per file type

The identifiers and the description that a ProcessValidationError carries depend on its fileType. Each cell names the input CSV column that the value comes from. A dash means that the file type has no such column, so the field is always absent. A field is also absent when the offending line leaves its column empty. LineNumber is optional in Invoices and Payments, so lineId may be absent for findings on those files.

ROD406AnalysisData type

Supplier invoice matches artifact

The JSON artifact downloaded from supplierInvoiceMatchesUrl holds every supplier invoice and its lines for a single process — both matched and non-matched. For each supplier invoice line, it records whether the line was matched between the SAF-T (ERP) data and the corresponding e-factura invoice, and, for matched lines, the ERP product code and the e-factura product identity.

The artifact has no expiry: it exists for as long as its process and is removed only when the process, or its declaration, is deleted. The full line set is served through the presigned URL and is intentionally not embedded inline in the roD406AnalysisData record, so that a large number of lines does not bloat that record.

The artifact has the following structure:

{
  "process": {
    "tenantId": "9b1c…", "organizationId": "org-42",
    "declarationId": "dec-7", "processId": "proc-9", "processCreatedAt": "2026-06-10T08:12:00Z",
    "country": "RO", "declarationType": "D406", "declarationFrequency": "L",
    "periodStart": "2026-05-01", "periodEnd": "2026-05-31"
  },
  "invoices": [
    {
      "invoiceNo": "FCT-1001", "invoiceType": "380", "invoiceDate": "2026-05-18",
      "supplierName": "FURNIZOR SRL", "supplierTin": 15832829,
      "netTotal": 1050.0, "grossTotal": 1249.5, "invoiceLineCurrencyCode": "RON",
      "lineCount": 4, "matchedLineCount": 3,
      "lines": [
        {
          "lineNumber": "3", "matchStatus": "MATCHED",
          "goodsServicesId": "…", "quantity": 10, "invoiceUom": "BUC",
          "unitPrice": 12.5, "invoiceLineAmount": 125.0, "debitCreditIndicator": "D",
          "saftProductCode": "ART-00731", "saftProductDescription": "Hârtie A4 80g",
          "efacturaSellerItemId": "SUP-PAP-A4", "efacturaStandardItemId": null,
          "efacturaItemName": "Hartie copiator A4", "efacturaItemDescription": null,
          "normalizedProductKey": "sup-pap-a4", "productKeyBasis": "sellerItemId"
        },
        {
          "lineNumber": "1", "matchStatus": "SAFT_ONLY",
          "quantity": 1, "unitPrice": 240.0, "invoiceLineAmount": 240.0,
          "saftProductCode": "ART-00120", "saftProductDescription": "Toner negru"
        },
        {
          "lineNumber": "2", "matchStatus": "EFACTURA_ONLY",
          "quantity": 2, "unitPrice": 90.0, "invoiceLineAmount": 180.0,
          "efacturaSellerItemId": "SUP-INK-22", "efacturaItemName": "Cartus cerneala"
        }
      ]
    }
  ]
}

The process header block provides the following fields:

Each entry in invoices[] has the following header fields:

Each entry in an invoice’s lines[] has the following fields. The Present on column indicates for which matchStatus values a field is populated:

ROD406Profitability type

For formulas, see Appendix 9.

ROD406Liquidity type

ROD406Activity type

ROD406TaxAnalysis type

ROD406AssetAnalysis type

ROD406StandardBalanceSheet type

The standard balance sheet maps the organization’s account balances to the standard chart of accounts prescribed by the tax authority for the corresponding tax accounting basis.

ROD406StandardBalanceClass type

ROD406StandardBalanceAccount type

ROD406SystemBalanceSheet type

The system balance sheet provides the organization’s actual (system-of-record) account balances, as opposed to the standard balance sheet, which maps balances to the standard chart of accounts prescribed by the tax authority. Both balance sheets are populated only for monthly (HeaderComment = L) or quarterly (HeaderComment = T) Romanian D406 declarations.

ROD406SystemBalanceClass type

ROD406SystemBalanceAccount type

ROKPIAnalysisDataElement type

Provides the RO D406 KPI analysis for a single month of the reporting period. A process returns one element per month covered by the declaration.

ROD406Validation type

Represents the outcome of a single consistency test applied to the analysis data. These tests are the additional checks that the DUK Integrator tool described under Validation does not cover: the tests ANAF requires, plus the five period-date checks.

ROD406TaxCodeCentralizerEntry type

Represents a single tax code in the centralizer, with the amounts reported for that code by each SAF-T source and, when available, the matching entry from the ANAF nomenclature. There is one entry per distinct tax code in the computed declaration, ordered by taxCode ascending. An empty or absent tax code is normalized to 000000.

ROD406TaxCodeCentralizerSourceMetrics type

The tax base, tax amount, and tax percentage reported for a single tax code by one SAF-T source. Each source is aggregated independently, so its rate is reported as-is and is not reconciled against the other sources or against the nomenclature.

ResultFile type

Totals type

CsvFileLines type

AccountTotal type

DebitCreditOpenClose type

DebitCredit type

CsvInvoiceTotals type

CsvPaymentTotals type

CurrencyAmount type

MasterFilesTotals type

GeneralLedgerAccountsTotals type

BusinessPartnersTotals type

GeneralLedgerEntriesTotals type

SourceDocuments type

InvoicesTotals type

PaymentsTotals type

Header type

CompanyHeaderStructure type

Address type

ContactHeaderStructure type

PersonNameStructure type

TaxIdStructure type

BankAccount type

SelectionCriteriaStructure type

SupplierProductMappingList type

Returned by the supplierProductMappings query.

SupplierProductMapping type

A single (supplier, product) → ERP product code mapping. Only the product- and supplier-related fields are exposed.

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"
  }
}

declaration

Retrieves a single declaration by its identifier.

Arguments

Result

See the Declaration type.

Example

query declaration($id:ID!) {
  declaration(id:$id) {
    id
    organization { id, name, tin }
    representative { id, firstName, lastName, phone, email }
    headerComment
    declarationType
    from
    to
    files { id, fileType, name, createdAt }
    processes { id, status, createdAt }
    createdAt
  }
}

{
  "id": "YOUR_DECLARATION_ID"
}

organizations

Returns a list of active organizations defined for the given tenant.

Result

The result is an array of Organization.

Organization type

Example

The following query retrieves the currently active organizations defined in the Organizations Service.

query Organizations {
  organizations {
    id
    name
    tin
    regNo
    country
    createdAt
 }
}

representatives

Returns a list of representatives created for the given tenant.

Arguments

None.

Result

See the Representative type.

Example

The following query retrieves all the representatives.

query representatives {
  representatives {
    id
    firstName
    lastName
    phone
    email
    otherTitles
  }
}

roD406AnalysisData

Returns comprehensive RO D406 analysis data for the month or period for which the declaration was computed. On the STANDARD plan, you get analysis data for every Romanian D406 declaration you compute. Analysis data is not available on the LIMITED plan: if your tenant is on that plan, the query returns null without an error, as it does for analysis data not yet computed. See Service plans. Which individual fields are populated depends on the declaration type and on the input files you provided: taxCodeCentralizer, for example, is populated only for monthly (L) and quarterly (T) declarations.

The analysis data is computed together with the declaration and no extra steps are required to generate it, apart from generating the RO D406 declaration itself, see Generating a declaration.

Arguments

Result

Returns ROD406AnalysisData, or null if not yet computed.

Example

query roD406AnalysisData($organizationId:ID!, $declarationId:ID!, $processId:ID!) {
  roD406AnalysisData(
    organizationId: $organizationId
    declarationId: $declarationId
    processId: $processId
  ) {
    from
    to
    currency
    periodDays
    profitability { CA EAT EBT EBIT EBITDA MB MPN RCT VE CT }
    liquidity { CR DAT CL }
    activity { NFC NFF VMF NPC RRC RAC RRF }
    tax { TVAC TVAD TVAN }
    assets { VBI AMP RAI }
    standardBalanceSheet {
      classes {
        id name
        openingDebit openingCredit currentDebit currentCredit closingDebit closingCredit
        accounts {
          id name
          openingDebit openingCredit currentDebit currentCredit closingDebit closingCredit
        }
      }
    }
    systemBalanceSheet {
      openingDebit openingCredit currentDebit currentCredit closingDebit closingCredit
      classes {
        id name
        openingDebit openingCredit currentDebit currentCredit closingDebit closingCredit
        accounts {
          id standardId name
          openingDebit openingCredit currentDebit currentCredit closingDebit closingCredit
        }
      }
    }
    validations { code description status message }
    taxCodeCentralizer {
      taxCode nameRo nameEn nomenclaturePercentage
      gle { taxBase taxAmount taxPercentage }
      invoices { taxBase taxAmount taxPercentage }
      payments { taxBase taxAmount taxPercentage }
    }
  }
}

{
  "organizationId": "YOUR_ORGANIZATION_ID",
  "declarationId": "YOUR_DECLARATION_ID",
  "processId": "YOUR_PROCESS_ID"
}

roKPIAnalysisData

Returns historical RO D406 KPI analysis data, broken down by month. Applicable only for declarations that use monthly (not quarterly) reporting.

KPI declarations are not available on the LIMITED plan. See Service plans.

To obtain KPI data:

1. Initiate a Romanian declaration with a call to initiateDeclaration. Set declarationType to KPI.
2. Set the from and to dates for the period you want to cover (for example, the past 3 years up to current date).
3. Set the headerComment to L (Monthly).
4. Add the GeneralLedgerAccounts and GeneralLedgerEntries CSV files to the declaration (for the latest month) with prepareFile, as described in Preparing declaration files. You can optionally also add an Invoices file for that month to populate the invoice-derived activity KPIs (NFC, NFF, VMF, and NPC).
5. Trigger the computation with generateDeclaration and note the id of the returned Process.
6. Once the process reaches status DONE, call roKPIAnalysisData with the organization ID, declaration ID, and that process ID. Until then, the query returns null.

NOTE: No SAF-T XML file is generated when you set the declarationType to KPI.

Arguments

Result

Returns a list of ROKPIAnalysisDataElement objects, one per month of the reporting period, or null if not yet computed.

Example

query roKPIAnalysisData($organizationId:ID!, $declarationId:ID!, $processId:ID!) {
  roKPIAnalysisData(
    organizationId: $organizationId
    declarationId: $declarationId
    processId: $processId
  ) {
    month
    profitability { CA EAT EBT EBIT EBITDA MB MPN RCT VE CT }
    liquidity { CR DAT CL }
    activity { NFC NFF VMF NPC RRC RAC RRF }
    tax { TVAC TVAD TVAN }
  }
}

{
  "organizationId": "YOUR_ORGANIZATION_ID",
  "declarationId": "YOUR_DECLARATION_ID",
  "processId": "YOUR_PROCESS_ID"
}

supplierProductMappings

Lists, per organization, the latest (supplier, product) → ERP product code mappings accrued from that organization’s prior Romanian D406 declarations. Each time a RO D406 declaration is computed, its supplier e-factura invoice lines are matched against the SAF-T (ERP) data, and every confirmed match contributes a mapping from the supplier’s product to the ERP product code. This query surfaces those accrued mappings so you can, for example, suggest the ERP product code for an incoming supplier invoice line.

The following apply:

• Recency. When the same product from the same supplier was matched in several periods, the query returns the value from the most recent declaration period.
• Only confirmed matches are returned. Only lines with matchStatus MATCHED produce a mapping. Lines that are SAFT_ONLY or EFACTURA_ONLY appear in the supplier invoice matches artifact but never as a mapping.
• Scope. Mappings are accrued from Romanian D406 monthly (Header Comment L) and quarterly (Header Comment T) declarations.
• Service plan. If your tenant is on the LIMITED plan, the declarations you compute add no mappings. You still get the mappings accrued before your tenant moved to that plan. See Service plans.

Arguments

Continuous scroll

The query returns results in batches suitable for continuous (infinite) scroll, not page-numbered pagination. Each call returns a SupplierProductMappingList of { items, nextToken }:

• items is the current batch (at most limit items).
• nextToken is an opaque continuation cursor. To load the next batch, call the query again with the same organizationId and this nextToken passed back unchanged. Do not parse the cursor.
• nextToken is null once the last batch has been returned.

There are no page numbers, offsets, or total count. An organization with no mappings returns an empty items list and a null nextToken (an empty result, not an error).

Result

Returns a SupplierProductMappingList.

Example

query supplierProductMappings($organizationId:ID!, $limit:Int, $nextToken:String) {
  supplierProductMappings(
    organizationId: $organizationId
    limit: $limit
    nextToken: $nextToken
  ) {
    items {
      supplierTin
      normalizedProductKey
      productKeyBasis
      saftProductCode
      saftProductDescription
    }
    nextToken
  }
}

{
  "organizationId": "YOUR_ORGANIZATION_ID",
  "limit": 50,
  "nextToken": null
}

version

Returns the API version.

Mutations

createRepresentative

Creates a record identifying the person that submits the tax declaration. Once a representative is created, it can be referenced multiple times by different declarations.

Arguments

CreateRepresentativeInput input

Result

See the Representative type.

Example

mutation createRepresentative($input:CreateRepresentativeInput!) {
  createRepresentative(input:$input) {
    id
    firstName
    lastName
    email
    phone
    otherTitles
  }
}

{
  "input": {
    "firstName": "Miroslav",
    "lastName": "Radomirov",
    "phone": "999-999-999",
    "email": "miroslav@example.org",
    "otherTitles": "Chief Finance Officer"
  }
}

deleteDeclaration

Deletes a declaration, including all its input files and related processes.

Arguments

Result

See the Declaration type.

Example

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

{
  "id": "YOUR_DECLARATION_ID"
}

deleteFile

Deletes a previously uploaded CSV file.

Arguments

DeleteFileInput input

Result

See the File type.

Example

mutation deleteFile ($input:DeleteFileInput!) {
  deleteFile(input: $input) {
    id
    declarationId
    fileType
    name
    createdAt
  }
}

{
    "input": {
        "declarationId": "YOUR_DECLARATION_ID",
        "id": "YOUR_FILE_ID"
    }
}

deleteProcess

Deletes a declaration computation process and the result XML files.

Arguments

Result

See the Process type.

Example

mutation deleteProcess($declarationId:ID!, $processId:ID!) {
  deleteProcess(declarationId:$declarationId, processId:$processId) {
    id
    status
    errorMessages
    result {
        id
        # downloadUrl
        createdAt
    }
    createdAt
  }
}

{
    "declarationId": "YOUR_DECLARATION_ID",
    "processId": "YOUR_PROCESS_ID"
}

deleteRepresentative

Deletes a previously created representative.

Arguments

Result

See the Representative type.

Example

mutation deleteRepresentative($id:ID!) {
  deleteRepresentative(id:$id) {
    id
    firstName
    lastName
    phone
    email
  }
}

{
    "id": "REPRESENTATIVE_ID"
}

generateDeclaration

Starts a declaration computation process.

Arguments

Result

See the Process type.

Preconditions

For a Romanian declaration whose declarationType is not KPI, two rules apply to the uploaded input files: every mandatory file type must be present, and every present file type must be one the declaration type accepts. See Appendix 10: Input file types by declaration type (Romania).

If either rule is broken, the mutation creates no process and fails with the error code INVALID_FILE_TYPES_FOR_DECLARATION_TYPE (see Error codes).

When both rules are satisfied, the mutation starts a new process with status NEW.

KPI declarations are not available on the LIMITED plan. If your tenant is on that plan and you pass a declaration whose declarationType is KPI, the mutation fails with the error code PLAN_FEATURE_NOT_AVAILABLE and starts no process. This applies also to KPI declarations you created before your tenant moved to that plan. See Service plans.

Example

mutation generateDeclaration($declarationId:ID!) {
  generateDeclaration(declarationId:$declarationId) {
    id
    status
    errorMessages
  }
}

{
    "declarationId": "YOUR_DECLARATION_ID"
}

initiateDeclaration

Creates a new tax declaration, without triggering any computation processes. After this mutation, run prepareFile for each CSV file that must be supplied as input to the declaration and obtain the file’s upload URL. After uploading the CSV files, run generateDeclaration mutation to trigger the computation process.

Arguments

InitiateDeclarationInput input

Result

See the Declaration type.

KPI declarations are not available on the LIMITED plan. If your tenant is on that plan and you set declarationType to KPI, the mutation fails with the error code PLAN_FEATURE_NOT_AVAILABLE, whatever else the input contains, and creates no declaration. See Service plans.

Example

The following mutation initiates a tax declaration, where:

• The declaration type is SAFT
• The declaration is for a monthly period (M)
• The declaration’s reporting period is 2025-01-01 through 2025-01-31.
• The audit file country is BG (Bulgaria)
• The region code is BG01 (Благоевград)
• The company’s tax accounting basis is A.

mutation initDecl($input: InitiateDeclarationInput) {
  initiateDeclaration(input:$input) {
    id
    organization { id, tin, name }
    representative { id, firstName, lastName }
    declarationType
    headerComment
    taxAccountingBasis
    from
    to
    files { id, fileType }
    processes { id, status }
    createdAt
  }
}

{
  "input": {
    "declarationType": "SAFT",
    "from": "2025-01-01",
    "to": "2025-01-31",
    "organizationId": "YOUR_ORGANIZATION_ID",
    "representativeId": "YOUR_REPRESENTATIVE_ID",
    "regionCode": "BG01",
    "headerComment": "M",
    "taxAccountingBasis": "A",
    "auditFileCountry": "BG"
  }
}

killProcess

Stops a declaration computation process if it is running.

Arguments

Result

See the Process type.

Example

The following mutation stops a running process.

mutation killProcess($declarationId:ID!, $processId:ID!) {
  killProcess(declarationId:$declarationId, processId:$processId) {
    id
    status
    errorMessages
    result {
        id
        downloadUrl
        createdAt
    }
    createdAt
  }
}

{
    "declarationId": "YOUR_DECLARATION_ID",
    "processId": "YOUR_PROCESS_ID"
}

prepareFile

Generates a URL at which you can upload a CSV file to be used as input to the tax declaration. Run this mutation for each CSV file that is to be supplied as input for a declaration. For Romanian D406 declarations, upload every mandatory file type, and only file types that the declaration’s headerComment permits; see Appendix 10: Input file types by declaration type (Romania).

Arguments

PrepareFileInput input

Result

See the File type.

Example

The following mutation generates the upload URL for a file of type “BusinessPartners”. The upload URL is set to expire after 300 seconds.

mutation prepareFile($input:PrepareFileInput!) {
  prepareFile(input:$input) {
    id
    declarationId
    fileType
    name
    uploadUrl(expiresIn:300)
    createdAt
  }
}

{
  "input": {
    "declarationId": "YOUR_DECLARATION_ID",
    "fileType": "BusinessPartners"
  }
}

updateDeclaration

Update certain declaration parameters.

Arguments

UpdateDeclarationInput input

Result

See the Declaration type.

Example

The following mutation updates the tax accounting basis of an existing declaration to A.

mutation updateDecl($id:ID!,$input:UpdateDeclarationInput) {
        updateDeclaration(id:$id,input:$input) {
          id
          organization { id name tin }
          representative { id firstName lastName phone email }
          headerComment
          declarationType
          taxAccountingBasis
          auditFileCountry
          from
          to
          regionCode
          files { id fileType }
          processes { id status }
          createdAt
        }
      }

{
    "id": "YOUR_DECLARATION_ID",
    "input": {
        "taxAccountingBasis": "A"
    }
}

updateRepresentative

Updates a previously created representative.

Arguments

UpdateRepresentativeInput input

Result

See the Representative type.

Example

The following mutation updates a representative’s details.

mutation updateRepresentative($id:ID!, $input:UpdateRepresentativeInput!) {
        updateRepresentative(id:$id, input: $input) {
          id
          firstName
          lastName
          email
          phone
          otherTitles
        }
      }

{
    "id": "REPRESENTATIVE_ID",
    "input": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "999-999-999",
        "email": "john.doe@example.org",
        "otherTitles": "Accounting Manager"
    }
}

Error codes

See Conventions for the error format and the codes shared across all services. This service can also return the codes listed below, grouped by the object they concern. The Returned by column names the operations and fields that report each code.

Declarations

roD406AnalysisData, roKPIAnalysisData, and updateDeclaration also return DECLARATION_NOT_FOUND when the declaration belongs to a different application.

Declaration parameters

Representatives

Organizations

Processes

roD406AnalysisData and roKPIAnalysisData also return PROCESS_NOT_FOUND when the process belongs to a different application.

Files

Access

Webhooks

The Tax Declarations Service supports webhooks. This means you can optionally configure SBS to send an HTTP POST request to an external server or application whenever any of the following events occur:

• COMPUTATION_SUCCESS - fires whenever a tax declaration was generated successfully.
• COMPUTATION_ERROR - fires whenever a tax declaration was generated with errors.

The POST request of the COMPUTATION_SUCCESS event has the following payload:

{
  "service": "tax-declarations-api",
  "event": "COMPUTATION_SUCCESS",
  "tenantId": "<your-tenant-id>",
  "payload": {
    "declarationId": "<your-declaration-id>",
    "processId": "<your-process-id>"
  },
  "customKey1": "Custom value 1",
  "customKey2": "Custom value 2"
}

The POST request of the COMPUTATION_ERROR event has the following payload:

{
  "service": "tax-declarations-api",
  "event": "COMPUTATION_ERROR",
  "tenantId": "<your-tenant-id>",
  "payload": {
    "declarationId": "<your-declaration-id>",
    "processId": "<your-process-id>"
  },
  "customKey1": "Custom value 1",
  "customKey2": "Custom value 2"
}