Annual report totals (040_1)

Browse code 040_1 (BrowseCode::AnnualReportTotals, “Annual Report”): the balance per general ledger account, summed by Twinfield. Twinfield groups the lines by the columns you ask for, so ask only for the columns you want totals by. The validate balances example uses it to check a shadow database.

Twinfield documentation: Browse data.

• fin.trs.line.dim1type is BAS for balance sheet accounts and PNL for profit and loss accounts; fin.trs.line.dim1group1 is the first group of the account.
• equal('fin.trs.head.status', 'final'): only final transactions. Use normal to include provisional ones.
• equal('fin.trs.head.balanceregimeprompt', $regime): the regime is required in 040_1; Twinfield uses Generic when you leave it out. Fiscal, Commercial and Economic give the lines of that regime plus the generic lines.
• Twinfield can return more than one row per account, so the example adds them up.
• The rows are totals: $row->transactionLine is null.

Criteria: period, status, the three dimensions, regime and reporting structure. See browse-definitions/040_1.xml and the browse data guide. 050_1 gives year-to-date totals, 060 totals per currency.

Fields

All fields of the browse definition (browse-definitions/040_1.xml), with the label for a Dutch user, the data type and the values of a field with a fixed list (browsefields.xml). A field that is not visible is meant as criterion: asking for it as column can give a server error. Twinfield does not apply the proposed values: send every criterion you need.

Field	Label	Type	Visible	Criterion
fin.trs.head.office	Administratie	string	yes
fin.trs.head.officename	Adm.naam	string	yes
fin.trs.head.year	Jaar	long	yes
fin.trs.head.period	Periode	long	yes
fin.trs.head.yearperiod	Jaar/periode (JJJJ/PP)	string	no	between
fin.trs.head.status	Status	special: draft, temporary, final, inuse, normal	yes	equal (proposed normal)
fin.trs.line.dim1	Grootboekrek.	string	yes	between
fin.trs.line.dim1name	Grootboekrek.naam	string	yes
fin.trs.line.dim1type	Dimensietype 1	string	yes
fin.trs.line.dim2	Kpl./rel.	string	yes	between
fin.trs.line.dim2name	Kpl.-/rel.naam	string	yes
fin.trs.line.dim2type	Dimensietype 2	string	yes
fin.trs.line.dim3	Act./proj.	string	yes	between
fin.trs.line.dim3name	Act.-/proj.naam	string	yes
fin.trs.line.dim3type	Dimensietype 3	string	yes
fin.trs.line.basevaluesigned	Basisbedrag	value	yes
fin.trs.line.repvaluesigned	Rapportagebedrag	value	yes
fin.trs.line.debitcredit	D/C	special: credit, debit	yes
fin.trs.line.quantity	Aantal	decimal	yes
fin.trs.line.dim1group1	Groep 1	string	yes
fin.trs.line.dim1group1name	Groepnaam 1	string	yes
fin.trs.line.dim1group2	Groep 2	string	yes
fin.trs.line.dim1group2name	Groepnaam 2	string	yes
fin.trs.line.dim1group3	Groep 3	string	yes
fin.trs.line.dim1group3name	Groepnaam 3	string	yes
fin.trs.head.balanceregimeprompt	Regime	special: Generic, Commercial, Economic, Fiscal	no	equal (proposed Generic)
fin.trs.line.dim1group4	Groep 4	string	yes
fin.trs.line.dim1group4name	Groepnaam 4	string	yes
fin.trs.line.dim1group5	Groep 5	string	yes
fin.trs.line.dim1group5name	Groepnaam 5	string	yes
fin.trs.head.reportingstructure	Rapportagestructuur	string	no	equal

Code

$twinfield = Example::twinfield();

$year = (int) ($argv[1] ?? Example::lastYear($twinfield));
$regime = Regime::from($argv[2] ?? 'Generic');

$result = $twinfield->browse(BrowseCode::AnnualReportTotals)
    ->columns(
        'fin.trs.line.dim1',
        'fin.trs.line.dim1name',
        'fin.trs.line.dim1type',
        'fin.trs.line.dim1group1',
        'fin.trs.line.basevaluesigned',
    )
    ->between('fin.trs.head.yearperiod', sprintf('%d/00', $year), sprintf('%d/55', $year))
    ->equal('fin.trs.head.status', 'final')
    ->equal('fin.trs.head.balanceregimeprompt', $regime)
    ->get();

// Twinfield can give more than one row per account: add them up.
$accounts = [];

foreach ($result as $row) {
    $code = $row->string('fin.trs.line.dim1');

    $accounts[$code] ??= [
        'type' => $row->string('fin.trs.line.dim1type'),
        'name' => $row->nullableString('fin.trs.line.dim1name') ?? '',
        'group' => $row->nullableString('fin.trs.line.dim1group1') ?? '-',
        'balance' => Amount::zero(),
    ];
    $balance = $row->amount('fin.trs.line.basevaluesigned');
    $accounts[$code]['balance'] = $accounts[$code]['balance']->plus($balance);
}

ksort($accounts, SORT_STRING);

echo count($accounts), ' general ledger account(s) in ', $year, ', final transactions, regime ', $regime->value,
    PHP_EOL;

$totals = [];
$index = 0;

foreach ($accounts as $code => $account) {
    $totals[$account['type']] = ($totals[$account['type']] ?? Amount::zero())->plus($account['balance']);

    echo sprintf(
        '[%d/%d] %s %s %s (group %s): %s',
        ++$index,
        count($accounts),
        $account['type'],
        $code,
        $account['name'],
        $account['group'],
        $account['balance'],
    ), PHP_EOL;
}

foreach ($totals as $type => $total) {
    echo 'Total ', $type, ': ', $total, PHP_EOL;
}

Run

php examples/browse-data/040_1-annual-report-totals/example.php              # the last year, generic
php examples/browse-data/040_1-annual-report-totals/example.php 2025 Fiscal   # fiscal regime

Add TWINFIELD_DEBUG=1 to see the SOAP requests and responses.

11 general ledger account(s) in 2025, final transactions, regime Generic
[1/11] BAS 10100 Kruisposten (group 1): 17.50
[2/11] BAS 10101 Kruisposten kas (group 1): -2503.00
[3/11] BAS 16000 Handelscrediteuren (group 2): -398.23
[4/11] BAS 16005 Nog te ontvangen facturen (group 2): -17.50
[5/11] BAS 16627 BTW Voorbelasting (group 2): -70.01
…
[11/11] PNL 86090 Bankkosten en provisie (group 3): 601.00
Total BAS: -2653.22
Total PNL: 2653.22

XML

What the SDK sends to Twinfield and what Twinfield sends back, for a call like the one in this example. The responses come from the tests, with example data.

Compose the browse request and send it

Twinfield documentation: Browse data: Compose the browse request and send it.

$twinfield->browse(BrowseCode::AnnualReportTotals)
    ->columns(
        'fin.trs.line.dim1',
        'fin.trs.line.dim1name',
        'fin.trs.line.dim1type',
        'fin.trs.line.dim1group1',
        'fin.trs.line.basevaluesigned',
    )
    ->between('fin.trs.head.yearperiod', '2026/00', '2026/55')
    ->equal('fin.trs.head.status', 'final')
    ->equal('fin.trs.head.balanceregimeprompt', Regime::Generic)
    ->get();

The SDK sends this XML as xmlRequest of ProcessXmlString to processxml.asmx:

<columns code="040_1" optimize="true">
  <column>
    <field>fin.trs.line.dim1</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.line.dim1name</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.line.dim1type</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.line.dim1group1</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.line.basevaluesigned</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.head.yearperiod</field>
    <operator>between</operator>
    <from>2026/00</from>
    <to>2026/55</to>
  </column>
  <column>
    <field>fin.trs.head.status</field>
    <operator>equal</operator>
    <from>final</from>
  </column>
  <column>
    <field>fin.trs.head.balanceregimeprompt</field>
    <operator>equal</operator>
    <from>Generic</from>
  </column>
</columns>

Twinfield answers with this XML in ProcessXmlStringResult:

<browse result="1" first="1" last="3" total="3">
  <th>
    <td label="" hideforuser="false" type="String">fin.trs.line.dim1</td>
    <td label="" hideforuser="false" type="String">fin.trs.line.dim1name</td>
    <td label="" hideforuser="false" type="String">fin.trs.line.dim1type</td>
    <td label="" hideforuser="false" type="String">fin.trs.line.dim1group1</td>
    <td label="" hideforuser="false" type="Value">fin.trs.line.basevaluesigned</td>
  </th>
  <tr>
    <td>1300</td>
    <td>Debiteuren</td>
    <td>BAS</td>
    <td>VLA</td>
    <td>242.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
  <tr>
    <td>1510</td>
    <td>Te betalen btw</td>
    <td>BAS</td>
    <td>KVS</td>
    <td>-42.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
  <tr>
    <td>8000</td>
    <td>Omzet</td>
    <td>PNL</td>
    <td>OMZ</td>
    <td>-200.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
</browse>

Source

View examples/browse-data/040_1-annual-report-totals/example.php on GitHub.