Free Texts (Freitexte)

API wrapper for free text snippets at /free-texts. Free texts are predefined texts for the title, label, intro and note fields of documents (invoices, offers, delivery notes, letters, etc.). They support Billomat placeholders such as [Invoice.invoice_number] or [Invoice.due_date].

Access

$billomat->freeTexts

Justpilot\Billomat\Api\FreeTextsApi.

Endpoints

Method	HTTP	Path
list($filters?)	GET	/free-texts
listPage($filters?)	GET	/free-texts
iterateAll($filters?, $pageSize?)	GET	/free-texts (all pages)
get($id)	GET	/free-texts/{id}
getOrFail($id)	GET	/free-texts/{id}

Read-only in the SDK. Billomat supports create/update/delete, but the SDK doesn't expose them as methods.

Methods

list(array $filters = []): list<FreeText>

foreach ($billomat->freeTexts->list() as $ft) {
    printf("#%d %s — %s\n",
        $ft->id,
        $ft->title ?? '(no title)',
        $ft->label ?? '',
    );
}

Pagination via page/per_page; see Pagination and filtering.

listPage(array $filters = []): Page<FreeText>

One page plus PageInfo.

iterateAll(array $filters = [], int $pageSize = 100): Generator<FreeText>

Lazy iteration over all pages.

get(int $id): ?FreeText

Returns null on 404.

getOrFail(int $id): FreeText

Like get(), but throws NotFoundException instead of returning null.

Read model: FreeText

final readonly class FreeText.

Property	Billomat field	Type	Purpose
id	id	int
title	title	?string	Document title or subject
label	label	?string	Subtitle/label
intro	intro	?string	Introduction / letter body
note	note	?string	Notes at the end of the document
created, updated	created, updated	?\DateTimeImmutable
type	type	?FreeTextType	Document type (see below)
name	name	?string	Internal name of the snippet
isDefault	is_default	?bool
extra	—	array<string,mixed>	Fields the SDK doesn't map yet, raw (see Read models)

Document types (FreeTextType)

Value	Used for
INVOICE	Invoice
CORRECTION	Corrective invoice (Korrekturrechnung)
OFFER	Offer
CONFIRMATION	Order confirmation
CREDIT_NOTE	Credit note
DELIVERY_NOTE	Delivery note
LETTER	Letter

FreeTextType::label() returns the German label (e.g. "Rechnung"). Unknown values become null.

Placeholders

All text fields accept Billomat placeholders, e.g.:

• [Invoice.invoice_number] — invoice number
• [Invoice.date] — invoice date
• [Invoice.due_date] — due date
• [Client.name] — client name

The full list depends on the document type and is documented in the Billomat UI under Einstellungen → Vorlagen (Settings → Templates).

Pitfalls

• is_default is exclusive per type. Each document type has exactly one default free text; setting a new default replaces the old one on the server.
• Single-item list quirk. With only one free text in the account Billomat returns an object instead of a list; listResource() normalizes this.

End-to-end example

<?php

declare(strict_types=1);

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

use Justpilot\Billomat\BillomatClient;
use Justpilot\Billomat\Model\Enum\FreeTextType;

$billomat = BillomatClient::create(
    billomatId: 'mycompany',
    apiKey: getenv('BILLOMAT_API_KEY'),
);

foreach ($billomat->freeTexts->iterateAll() as $ft) {
    if ($ft->type !== FreeTextType::INVOICE) {
        continue;
    }
    if ($ft->intro !== null && str_contains($ft->intro, '[Invoice')) {
        printf("Free text #%d contains invoice placeholders\n", $ft->id);
    }
}