Annual report year to date (050_1)

Browse code 050_1 (BrowseCode::AnnualReportYearToDate, “Annual Report YTD”): the balance per general ledger account from the start of the year up to a period, summed by Twinfield. Use 040_1 for totals with more fields, such as the account groups.

Twinfield documentation: Browse data.

• between('fin.trs.head.yearperiod', '2026/00', $to): from the opening balance (period 00) up to and including $to.
• equal('fin.trs.head.balanceregimeprompt', $regime): the regime is required; Twinfield uses Generic when you leave it out.
• Twinfield groups the lines by the columns you ask for, so ask only for the columns you want totals by. The rows are totals: $row->transactionLine is null.

Criteria: period, status, general ledger account and regime. See browse-definitions/050_1.xml and the browse data guide.

Fields

All fields of the browse definition (browse-definitions/050_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.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.valuesigned	Bedrag	value	yes
fin.trs.line.basevaluesigned	Basisbedrag	value	yes
fin.trs.line.repvaluesigned	Rapportagebedrag	value	yes
fin.trs.head.balanceregimeprompt	Regime	special: Generic, Commercial, Economic, Fiscal	no	equal (proposed Generic)

Code

$twinfield = Example::twinfield();

$to = Period::fromString($argv[1] ?? Example::lastYear($twinfield) . '/12');
$regime = Regime::from($argv[2] ?? 'Generic');

$query = $twinfield->browse(BrowseCode::AnnualReportYearToDate)
    ->columns(
        'fin.trs.line.dim1',
        'fin.trs.line.dim1name',
        'fin.trs.line.dim1type',
        'fin.trs.line.basevaluesigned',
    )
    ->between('fin.trs.head.yearperiod', sprintf('%d/00', $to->year), $to)
    ->equal('fin.trs.head.status', 'normal')
    ->equal('fin.trs.head.balanceregimeprompt', $regime);

$result = $query->get();

echo count($result), ' general ledger account(s) up to ', $to, ', regime ', $regime->value, PHP_EOL;

$totals = [];

foreach ($result as $index => $row) {
    $type = $row->string('fin.trs.line.dim1type');
    $balance = $row->amount('fin.trs.line.basevaluesigned');
    $totals[$type] = ($totals[$type] ?? Amount::zero())->plus($balance);

    echo sprintf(
        '[%d/%d] %s %s %s: %s',
        $index + 1,
        count($result),
        $type,
        $row->string('fin.trs.line.dim1'),
        $row->nullableString('fin.trs.line.dim1name') ?? '',
        $balance,
    ), PHP_EOL;
}

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

Run

php examples/browse-data/050_1-annual-report-ytd/example.php                  # up to period 12 of the last year
php examples/browse-data/050_1-annual-report-ytd/example.php 2026/06 Fiscal   # up to June 2026, fiscal regime

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

3 general ledger account(s) up to 2026/12, regime Generic
[1/3] BAS 1100 Bank: 1250.00
[2/3] BAS 1300 Debiteuren: 242.00
[3/3] PNL 8000 Omzet: -1492.00
Total BAS: 1492.00
Total PNL: -1492.00

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::AnnualReportYearToDate)
    ->columns(
        'fin.trs.line.dim1',
        'fin.trs.line.dim1name',
        'fin.trs.line.dim1type',
        'fin.trs.line.basevaluesigned',
    )
    ->between('fin.trs.head.yearperiod', '2026/00', '2026/06')
    ->equal('fin.trs.head.status', 'normal')
    ->equal('fin.trs.head.balanceregimeprompt', Regime::Generic)
    ->get();

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

<columns code="050_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.basevaluesigned</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.trs.head.yearperiod</field>
    <operator>between</operator>
    <from>2026/00</from>
    <to>2026/06</to>
  </column>
  <column>
    <field>fin.trs.head.status</field>
    <operator>equal</operator>
    <from>normal</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="Value">fin.trs.line.basevaluesigned</td>
  </th>
  <tr>
    <td>1100</td>
    <td>Bank</td>
    <td>BAS</td>
    <td>1250.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
  <tr>
    <td>1300</td>
    <td>Debiteuren</td>
    <td>BAS</td>
    <td>242.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
  <tr>
    <td>8000</td>
    <td>Omzet</td>
    <td>PNL</td>
    <td>-1492.00</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
</browse>

Source

View examples/browse-data/050_1-annual-report-ytd/example.php on GitHub.