Examples

Small, self-contained examples. Each folder shows one thing, with an example.php you can run and a README.md that explains it.

Setup

1. Register http://localhost:8765/callback as redirect URI for your client in the Twinfield developer portal.

2. Run any example, for instance:

   php examples/offices/list-offices/example.php

The first time, the example asks for your client ID, client secret and redirect URI, opens the Twinfield login in your browser and asks for a default company. Everything is saved in ~/.config/twinfield/, so after that examples start right away. Run composer twinfield:setup to change these values.

Every example starts the same way:

require __DIR__ . '/../../../vendor/autoload.php';

$twinfield = Example::twinfield();

In your own application you create the client yourself: see Authentication.

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

Getting started

• Login: let a user log in and get the refresh token.
• Authentication: create a client in your own application.
• Token info: organisation, user and cluster of an access token.
• Error handling: catch errors and act on their code.
• REST API request: call an endpoint of the REST API directly, with the company GUID.

Offices

• List offices: all offices the user has access to.
• Search offices: search by code or name, or only offices without tax group.
• Read office: all settings of one office.
• Switch company: the same call for several companies.

Activities

• List activities: code and name of all activities.
• Search activities: search by name, change date or group.
• Read activity: all settings of one activity.
• Create activity: create an activity (changes data).
• Update activity: change an existing activity (changes data).
• Delete activity: delete or hide an activity (changes data).

Asset methods (classic)

• List asset methods: code and name of all asset methods, or those matching a pattern.
• Read asset method: calculation, accounts and free text fields of one asset method.
• Create asset method: create an asset method (changes data).
• Update asset method: change an existing asset method (changes data).
• Delete asset method: delete or hide an asset method (changes data).

Bank books

• List bank books: code and name of all bank books, or those matching a pattern.
• Read bank book: bank account, ledger account and automatic bank processing of one bank book.
• Create bank book: create a bank book with a bank account (changes data; cannot be deleted).
• Update bank book: change a bank book; only changed values are sent (changes data).

Bank transactions

• Read bank transaction: header, lines and matches of one bank transaction.
• Create bank transaction: a bank statement with calculated total line and closing balance (changes data).
• Update bank transaction: change a provisional transaction with edit() (changes data).
• Delete bank transaction: delete a provisional transaction (changes data).
• Post bank transaction: make a provisional transaction final (changes data; cannot be undone).
• Import bank statement: a CSV statement to one transaction, with rules per line and a balance check.
• Bank costs with VAT: split an amount including VAT, exactly.
• Split payment over invoices: one payment for several open invoices.
• Bulk import with errors: save several transactions at once and handle the ones that fail (changes data).

Cash books

• List cash books: code and name of all cash books, or those matching a pattern.
• Read cash book: name, short name and ledger account of one cash book.
• Create cash book: create a cash book (changes data; cannot be deleted).
• Update cash book: change a cash book; only changed values are sent (changes data).

Cash transactions

• Read cash transaction: header and lines of one cash transaction.
• Daily cash register: sales per VAT rate, expenses and the cash difference of one day.

Sales transactions

• Read sales transaction: invoice number, customer, revenue and VAT lines, payment status and payments of one sales transaction.
• Create sales transaction: book an invoice from your own software, with the VAT calculated from the VAT code (changes data with --save).
• Credit note: book a credit note: the same positive amounts, the sides turned around (changes data with --save).
• Open invoices: unpaid invoices of a customer, with Finder IVT.

Purchase transactions

• Read purchase transaction: invoice number, supplier, cost and VAT lines, payment status and payments of one purchase transaction.
• Create purchase transaction: book a received invoice, with the VAT calculated from the VAT code (changes data with --save).
• Credit note: book a credit note of a supplier: the same positive amounts, the sides turned around (changes data with --save).
• Open invoices: unpaid invoices of a supplier, with Finder IVT.

Journal transactions

• Read journal transaction: header, regime, and detail and VAT lines of one journal transaction.
• Create journal transaction: book a correction; the lines balance by themselves, without total line (changes data with --save).
• Opening balance: book an opening balance in period 0 (changes data with --save).

Reversal transactions

• Read reversal: the reversed transaction and reversal settings of a journal transaction.
• Reverse journal transaction: reverse a final journal transaction (changes data).

Sales invoices

• List invoice types: the invoice types of the company, with Finder INV.
• Read sales invoice: header, lines, VAT and totals of one sales invoice, and the sales transaction Twinfield booked for it.
• Create sales invoice: let Twinfield make a concept invoice, or only calculate it (changes data with --save).
• Finalize sales invoice: make a concept invoice final, so Twinfield books the sales transaction (changes data with --save).

Deleted transactions

• List deleted transactions: what was deleted in the last days, by whom and why, of all day books.

Electronic bank statements

• Import electronic bank statement: a CSV statement as the bank reports it; Twinfield allocates the lines (changes data with --save).
• List electronic bank statements: the statements of the last days with their lines, and how Twinfield allocated and matched them.

Transaction blocked values

• Register blocked value: block part of a line of an existing transaction, e.g. the total line of a purchase invoice (changes data).
• Unregister blocked value: remove the blocked value from that line again (changes data).

Cost centers

• List cost centers: code and name of all cost centers, or those matching a pattern.
• Read cost center: name, status and use of one cost center.
• Create cost center: create a cost center (changes data).
• Update cost center: rename an existing cost center (changes data).
• Delete cost center: delete or hide a cost center, and activate it again (changes data).

Currencies

• List currencies: code and name of all currencies, or those matching a pattern.
• Read currency: short name, status and exchange rates of one currency, and the rate today.
• Create currency: create a currency with exchange rates (changes data).
• Update currency rates: add, change and remove exchange rates (changes data).
• Delete currency: delete a currency (changes data).

Customers

• List customers: code and name of all customers, or those matching a pattern.
• Read customer: payment term, direct debit, credit management, addresses and bank accounts of one customer.
• Create customer: create a customer with an address and a bank account (changes data).
• Update customer: change settings, an address, and add an address and a bank account (changes data).
• Delete customer: delete or hide a customer, and activate it again (changes data).
• List changed customers: customers changed since a date, also deleted and archived ones (REST API).

Dimension groups

• List dimension groups: code and name of all dimension groups, or those of one dimension type.
• Read dimension group: short name, status and the dimensions of one group.
• Create dimension group: create a group of customers (changes data).
• Update dimension group: rename a group, and add and remove dimensions (changes data).
• Delete dimension group: delete a group (changes data).

Dimension types

• List dimension types: code, name, mask and levels of all dimension types, or those of one financial level.
• Read dimension type: mask, levels and address labels of one type, and whether a code matches the mask.
• Update dimension type: change an address label (changes data).

Fixed assets

The new fixed assets module, on the REST API. For the classic module see Fixed assets (classic).

• List fixed assets: status, book value and last depreciated period of all assets.
• Read fixed asset: depreciation per regime, class and history of one asset.

Fixed assets (classic)

• List fixed assets: code and name of all fixed assets, or those matching a pattern or in a group.
• Read fixed asset: status, depreciation settings, free texts, transaction lines and locked settings of one asset.
• Create fixed asset: create a fixed asset with the next free code (changes data).
• Update fixed asset: change a fixed asset; locked settings are left out (changes data).
• Delete fixed asset: delete or hide a fixed asset, and activate it again (changes data).

General ledger accounts

• List general ledger accounts: balance sheet or profit and loss accounts, hidden ones included.
• Read general ledger account: sub-analysis, child validations, VAT code and groups of one account.
• Create general ledger account: create a profit and loss account that needs a cost center (changes data).
• Update general ledger account: make an account matchable and change its child validations (changes data).
• Delete general ledger account: delete or hide an account, and activate it again (changes data).

Ledger accounts

• List ledger accounts: balance sheet and profit and loss accounts with their GUID (REST API).

Posting rules

• List posting rules: how invoices of customers and suppliers are divided over accounts (REST API).

Projects

• List projects: code and name of all projects.
• Search projects: search by name, change date or group.
• Read project: all settings of one project.
• Create project: create a project (changes data).
• Update project: change an existing project (changes data).
• Delete project: delete or hide a project (changes data).

Rates

• List rates: code and name of all rates, or those matching a pattern.
• Search rates: rates for hours or quantities, by name.
• Read rate: type, unit, currency, all prices and the price today.
• Create rate: create a kilometre rate (changes data).
• Update rate price: new prices from a date with newPriceFrom() (changes data).
• Delete rate: delete or hide a rate (changes data).

Users

• List users: code and name of all users of the organisation.
• Search users: search by code, and the users that share a company with you.
• Read user: role, login status, companies and Time & Expenses settings of one user.
• Current user: the user of the access token, with userCode() and users()->current().
• Create user: create and invite a user (changes data, can cost money).
• Update user: change a user with edit(), and grant or revoke company access (changes data).
• Delete user: delete or hide a user with a reason (changes data).

Suppliers

• List suppliers: code and name of all suppliers, or those matching a pattern.
• Read supplier: payment term, how the supplier is paid, remittance advice, addresses, bank accounts and posting rules of one supplier.
• Create supplier: create a supplier paid by credit transfer, with an address and a bank account (changes data).
• Update supplier: change how the supplier is paid, a bank account, and add a bank account (changes data).
• Delete supplier: delete or hide a supplier, and activate it again (changes data).

VAT codes

• List VAT codes: code and name of all VAT codes, or those matching a pattern.
• Search VAT codes: VAT codes for sales or purchases, by name.
• Read VAT code: percentages over time, the accounts and VAT groups, and the VAT on an amount today.
• Create VAT code: create a sales VAT code of 21% (changes data).
• Update VAT percentage: a new rate from a date with newPercentageFrom() (changes data).
• Delete VAT code: delete or hide a VAT code (changes data).
• List VAT code rates: the rate on a date and the accounts of each VAT code (REST API).

Sales articles

• List sales articles: prices, VAT code and translations of the articles (REST API).
• Create sales article: create, update and delete an article (REST API, changes data).

Budgets

• List budgets: code and name of all budgets, or those matching a pattern.
• Budget vs. actual: budget and actual amounts per general ledger account, with the difference.
• Budget by cost center: amounts per account, cost center and period.
• Budget by project: amounts per period, account, cost center and project.
• List budget lines: the budgets per year and their lines (REST API).
• Create budget: create a budget, spread an amount over the periods and delete it again (REST API, changes data).

Bank feeds

• List PSD2 feeds: the PSD2 feeds of all companies and when their consent expires (REST API).

Browse data

One example per browse code; see Browse codes for all codes and their fields.

• Read browse definition: the fields of a browse code and which can be a criterion.
• List browse fields: data types and the values of fields with a fixed list.
• General ledger transactions (000): the lines of a general ledger account.
• Transactions still to be matched (010): open lines on accounts with matching.
• Transaction list (020): the lines as entered, per day book, with input date and user.
• General ledger details (030_1): every transaction line, first version.
• General ledger details (030_2): every transaction line with the relation and regime.
• General ledger details (030_3): every transaction line with all details.
• General ledger intercompany (031): intercompany lines with the company on the other side.
• General ledger intercompany (031_2): intercompany lines, with a reporting structure as criterion.
• Annual report totals (040_1): the balance per general ledger account.
• Annual report year to date (050_1): the balance per account up to a period.
• Annual report multicurrency (060): totals per account and currency.
• Customer transactions (100): open items of customers.
• Customers (130_1): customer lines with payment status and credit limit.
• Customers (130_2): customer lines changed since a moment.
• Customers (130_3): open items per credit manager.
• Credit management (164): credit management actions on open invoices.
• Supplier transactions (200): open items of suppliers.
• Suppliers (230_1): supplier lines with payment status.
• Suppliers (230_2): open items with their payment run.
• Project transactions (300): the lines of a project.
• Asset transactions (301): the lines of a fixed asset.
• Fixed assets (302_1): asset lines with the depreciation settings.
• Cash transactions (400): the lines of a cash book per statement.
• Bank transactions (410): the lines of a bank book per statement.
• Time & Expenses totals (610_1): totals per project, activity, rate and user.
• Time & Expenses multicurrency (620): general ledger totals per project and currency.
• Time & Expenses details (650_1): every Time & Expenses entry.
• Time & Expenses totals per week (651_1): hours and expenses per week.
• Time & Expenses totals per period (652_1): hours and expenses per period.
• Time & Expenses billing details (660_1): entries with invoice proposal and invoice.
• Time & Expenses billing per week (661_1): value and proposed amount per week.
• Time & Expenses billing per period (662_1): value and proposed amount per period.
• Transaction summary (670): the number of transactions and lines per day book and period.
• Bank link details (680): the bank books with IBAN and bank link status.
• Bank link details (680_2): the bank books with the kind of link and consent.
• VAT return status (690): the VAT and ICT returns of a year with their status.
• Hierarchy access (700): who has access to which reporting structure.
• Cost centers (900): the lines per cost centre.

Shadow database

• Initial load: all transaction lines once, one year at a time.
• Incremental load: the changed and deleted transactions since the last sync.
• Validate balances: compare the balance per account with Twinfield.

Declarations

• List declarations: VAT, ICT and tax group returns of the company or the organisation.
• Download VAT return: a VAT return as XBRL, with its payment reference.

Hierarchies

• List hierarchies: code and name of the reporting structures of the organisation.
• Print hierarchy tree: nodes and accounts as an ASCII tree with RecursiveTreeIterator.
• Accounts of a node: the accounts of a node and of the nodes below it.
• Save hierarchy: create one with nodes, accounts and access rights, or change one (write).
• Bind accounts: bind an account to a node and unbind it again (write).
• Delete hierarchy: delete or hide one (write).

Matching

• Match transactions: match an invoice with its payment, partly or with a discount (write).
• List match sets: the matched lines of a customer with their match number (browse data).
• Undo match: undo a match set by its match number (write).
• Matching audit trail: the matches and undone matches since a date (REST API).

Pay & Collect

• List pay runs: the payment and direct debit runs of a company.
• Get pay run: a run with its summaries, bank accounts and invoices.
• Create pay run: select the open invoices for a payment or direct debit run (write).
• Finish pay run: delete a run that is not posted yet, or end it after the files (write).
• Pay run lifecycle: modify, authorise, post, create the SEPA files and finish (write, can’t be undone).

Finder

• Search dimensions: search with pattern, options and limit.
• Paginate: go through all results page by page.
• Search in all companies: one search over all companies, with Finder option company=*.

Periods

• List periods: years of the company and the periods of a year.
• Period of transaction: name of the period of each transaction, and whether it is open.
• Rename period: change a period with a command (changes data).

ProcessXml

• List companies: all companies, with a request without company.
• Read dimension: read a customer and handle errors.