pa_client.exe – Python-Skripte & API-Client Referenz

Übersicht

Mit der pa_client.exe können Sie selbstgeschriebene Python-Skripte ausführen. Das Tool stellt dem Skript automatisch einen HTTP-Client zur Kommunikation mit der API bereit.

Skript ausführen

Verwenden Sie das Kommando exec und geben Sie Ihre Skript-Datei an:

bash

pa_client.exe exec myscript.py

Konfiguration

Sie haben zwei Möglichkeiten, die Verbindungsdaten zu konfigurieren:

Option 1: client.ini

Legen Sie eine client.ini Datei mit folgendem Inhalt an:

ini

[DEFAULT]
url = https://www.phoenixdocuments.de/test_org/
token = bvWgGa9a5OvFLAtawshxlQ1QfNor4s26

Option 2: Kommandozeile

bash

pa_client.exe --url <application_url> --token <generated_token> exec myscript.py

Wichtig: Die Parameter --url und --token müssen vor exec angegeben werden.

Struktur des Python-Skripts

Ihr Skript muss eine main-Funktion mit folgenden Parametern enthalten:

python

def main(client, args):
    pass

Parameter	Beschreibung
`client`	Ein API-Client-Objekt, mit dem Sie alle API-Endpunkte abfragen können
`args`	Eine Liste zusätzlicher Kommandozeilen-Argumente, die nach dem Skriptnamen angegeben werden

Parameter-Kategorien

Für die API-Methoden gibt es zwei Kategorien von ID-Parametern:

Kategorie id – akzeptiert:

Ein UUID-Objekt
Einen String im UUID-Format
Ein Dictionary mit dem Schlüssel id, dessen Wert ein UUID-String ist

Kategorie identifier – akzeptiert zusätzlich:

Einen String mit einem Kurznamen (z. B. eines Archivs oder einer Datentabelle)

API-Client Methoden – Referenz

Historie

`client.add_history(message, record_id, timestamp=None)`

Erstellt einen Eintrag in der Historie eines Vorgangs.

Parameter	Typ	Pflicht	Beschreibung
`message`	String	✅	Text des Historieneintrags
`record_id`	Kategorie `id`	✅	ID des Vorgangs
`timestamp`	String (ISO-Format)	❌	Datum und Uhrzeit; Standard: aktueller Zeitpunkt mit lokaler Zeitzone

Rückgabe: Dictionary mit Informationen des angelegten Historieneintrags.

Datentabellen

`client.create_datatable_entry(datatable, data={})`

Erstellt einen neuen Eintrag in einer Datentabelle.

Parameter	Typ	Pflicht	Beschreibung
`datatable`	Kategorie `identifier`	✅	ID oder Kürzel der Datentabelle
`data`	Dictionary	❌	Daten des neuen Eintrags

Rückgabe: Dictionary mit Informationen des erstellten Eintrags.

`client.delete_datatable_entry(entry_id)`

Löscht einen Eintrag aus einer Datentabelle.

Parameter	Typ	Pflicht	Beschreibung
`entry_id`	Kategorie `id`	✅	ID des zu löschenden Eintrags

Rückgabe: Keiner.

`client.find_datatables(query=None, limit=None, **kwargs)`

Sucht eine oder mehrere Datentabellen anhand von Filterkriterien.

Parameter	Typ	Pflicht	Beschreibung
`query`	String	❌	Filter; unterstützte Spalten: `identifier`, `name`, `description` (ohne `_` vorangestellt)
`limit`	Integer	❌	Maximale Anzahl der Ergebnisse
`**kwargs`	–	❌	Zusätzliche Spaltenfilter, AND-verknüpft mit `query`

Rückgabe: Liste von Datentabellen als Dictionaries.

python

# Alle Datentabellen abrufen
datatables = client.find_datatables()

# Filter auf Datentabellen-Kürzel
datatables = client.find_datatables(query='identifier = "iq_lieferanten"')

# Filter auf Datentabellen-Name
datatables = client.find_datatables(name="Invoice: Lieferanten")

`client.find_datatable_entries(datatable, query=None, limit=None, **kwargs)`

Sucht Einträge in einer Datentabelle.

Parameter	Typ	Pflicht	Beschreibung
`datatable`	Kategorie `identifier`	✅	ID oder Kürzel der Datentabelle
`query`	String	❌	Filterausdruck
`limit`	Integer	❌	Maximale Anzahl der Ergebnisse
`**kwargs`	–	❌	Zusätzliche Filter, AND-verknüpft mit `query`

Rückgabe: Liste von Datentabellen-Einträgen als Dictionaries.

python

# Mit Datentabellen-ID und mehreren Filtern
datatable = "FFFFFFFF-0000-0000-0000-000000000001"
entries = client.find_datatable_entries(datatable, query="_name != <empty>", _rechtyp="Rechnung")

# Mit Datentabellen-Kürzel
datatable = "iq_lieferanten"
entries = client.find_datatable_entries(datatable, query='_ustid = "R6011-1000-1"')

`client.get_datatable(datatable)`

Ruft eine einzelne Datentabelle ab.

Parameter	Typ	Pflicht	Beschreibung
`datatable`	Kategorie `identifier`	✅	ID oder Kürzel der Datentabelle

Rückgabe: Dictionary mit Informationen der Datentabelle.

`client.get_datatable_entry(entry_id)`

Ruft einen einzelnen Datentabellen-Eintrag anhand seiner ID ab.

Parameter	Typ	Pflicht	Beschreibung
`entry_id`	Kategorie `id`	✅	ID des Eintrags

Rückgabe: Dictionary mit Informationen des Eintrags.

`client.update_datatable_entry(entry_id, data={})`

Aktualisiert einen Datentabellen-Eintrag.

Parameter	Typ	Pflicht	Beschreibung
`entry_id`	Kategorie `id`	✅	ID des Eintrags
`data`	Dictionary	❌	Zu ändernde Daten

Rückgabe: Dictionary mit Informationen des aktualisierten Eintrags.

`client.delete_datatable_entry(entry_id)`

Löscht einen Datentabellen-Eintrag.

Parameter	Typ	Pflicht	Beschreibung
`entry_id`	Kategorie `id`	✅	ID des zu löschenden Eintrags

Rückgabe: Keiner.

`client.get_archive(identifier, include_virtual=False)`

Ruft ein Archiv anhand einer ID oder eines Kurznamens ab.

Parameter	Typ	Pflicht	Beschreibung
`identifier`	Kategorie `identifier`	✅	ID oder Kurzname des Archivs
`include_virtual`	Boolean	❌	Bei `True` werden auch gefilterte und zusammengefasste Archive zurückgegeben; Standard: `False`

Rückgabe: Dictionary mit Informationen des Archivs.

Vorgänge

`client.find_records(archive, query=None, limit=None, **kwargs)`

Sucht Vorgänge in einem Archiv.

Parameter	Typ	Pflicht	Beschreibung
`archive`	Kategorie `identifier`	✅	ID oder Kurzname des Archivs
`query`	String	❌	Filterausdruck
`limit`	Integer	❌	Maximale Anzahl der Ergebnisse
`**kwargs`	–	❌	Zusätzliche Filter, AND-verknüpft mit `query`

Rückgabe: Liste von Vorgängen als Dictionaries.

python

# Mit Archiv-ID und mehreren Filtern
archive = "FFFFFFFF-0000-0000-0000-000000000002"
records = client.find_records(archive, query="_krednr != <empty>", _ustid="R6011-1000-1")

# Mit Archiv-Kürzel
archive = "iq_invoice"
entries = client.find_records(archive, query="_saldo < 1000")

`client.get_record(record_id)`

Ruft einen einzelnen Vorgang anhand seiner ID ab.

Parameter	Typ	Pflicht	Beschreibung
`record_id`	Kategorie `id`	✅	ID des Vorgangs

Rückgabe: Dictionary mit Informationen des Vorgangs.

`client.iterate_records(archive, query=None)`

Lädt Vorgänge effizient und speicherschonend durch Iteration.

Parameter	Typ	Pflicht	Beschreibung
`archive`	Kategorie `identifier`	✅	ID oder Kurzname des Archivs
`query`	String	❌	Filterausdruck

Rückgabe: Iterierbares Objekt mit Vorgängen als Dictionaries.

ython

record_ids = set()
archive = "invoices"
for record in client.iterate_records(archive, query="_priority > 1"):
    record_ids.add(record["id"])

`client.update_record(record_id, data={}, tags=[])`

Aktualisiert einen Vorgang anhand seiner ID.

Parameter	Typ	Pflicht	Beschreibung
`record_id`	Kategorie `id`	✅	ID des Vorgangs
`data`	Dictionary	❌	Zu ändernde Daten
`tags`	Liste von Strings	❌	Tags, die im `on_save`-Event über STAR-Code verfügbar sind

Rückgabe: Dictionary mit Informationen des aktualisierten Vorgangs.

`client.delete_record(record_id)`

Löscht einen Vorgang.

Parameter	Typ	Pflicht	Beschreibung
`record_id`	Kategorie `id`	✅	ID des Vorgangs

Rückgabe: Keiner.

`client.execute_transition(record, id=None, name=None)`

Führt den nächsten Status-Übergang eines Vorgangs aus.

Parameter	Typ	Pflicht	Beschreibung
`record`	Dictionary	✅	Vorgangs-Dictionary, wie es von `client.get_record` zurückgegeben wird
`id`	–	❌	ID des Übergangs; optional, wenn es genau einen Übergang gibt
`name`	–	❌	Name des Übergangs; optional, wenn es genau einen Übergang gibt

Rückgabe: Keiner.

Zähler

`client.get_counter_value(counter)`

Führt den nächsten Zählerschritt aus und gibt den neuen Wert zurück.

Parameter	Typ	Pflicht	Beschreibung
`counter`	Kategorie `identifier`	✅	ID oder Kurzname des Zählers

Rückgabe: Nächster Zählerwert.

Benutzer & Gruppen

`client.get_viewer_user(username=None, group=None)`

Sucht einen Benutzer oder eine Gruppe.

Parameter	Typ	Pflicht	Beschreibung
`username`	String	❌	Benutzername als Suchkriterium
`group`	String	❌	Gruppenname als Suchkriterium

Rückgabe: Dictionary mit Informationen des Benutzers oder der Gruppe, oder None wenn kein Ergebnis gefunden wurde.

Export

`client.run_export(archive, records, export_type, path, export_options=None, on_duplicate="enumerate", columns=None)`

Exportiert Vorgänge im gewünschten Format.

Parameter	Typ	Pflicht	Beschreibung
`archive`	Kategorie `identifier`	✅	ID oder Kurzname des Archivs
`records`	ID oder Liste von IDs	✅	Ein oder mehrere Vorgangs-IDs
`export_type`	String	✅	Exportformat (siehe Tabelle unten)
`path`	String (absoluter Pfad)	✅	Zielverzeichnis oder vollständiger Dateipfad (muss absolut sein)
`export_options`	Dictionary	❌	Optionale Export-Steuerung (siehe unten)
`on_duplicate`	String	❌	Verhalten bei bestehender Datei: `enumerate` (Standard), `overwrite`, `skip`
`columns`	Liste von Strings	❌	Spaltenkürzel (mit `_` vorangestellt); Standard: alle zugänglichen Spalten

Zulässige Werte für export_type:

Wert	Beschreibung
`attachments`	Dokumente zusammenfassen
`csv`	CSV
`csv_with_attachments`	CSV mit Dokumenten
`accounting_records`	Buchungssätze
`pdf`	PDF
`pdf_with_attachments`	PDF mit Dokumenten
`xlsx`	Excel

Zulässige Werte für export_options:

Option	Beschreibung
`attachments_first`	Bei `pdf_with_attachments`: Bei `True` werden Dokumente vor den Vorgangsinformationen in die PDF geschrieben. Standard: `False`
`with_history`	Gibt an, ob die Historie exportiert wird. Standard: `True`

Rückgabe: Absoluter Pfad der gespeicherten Datei, oder None bei fehlgeschlagenem Export (mit geloggter Warnung).

Dateien hochladen

`client.upload_file(filename)`

Lädt eine Datei über einen Dateipfad hoch.

Parameter	Typ	Pflicht	Beschreibung
`filename`	String (Dateipfad)	✅	Pfad zur hochzuladenden Datei

Rückgabe: Tupel mit checksum und chunk.

`client.upload_fileobj(fileobj)`

Lädt eine Datei über einen Binär-Stream hoch.

Parameter	Typ	Pflicht	Beschreibung
`fileobj`	Binär-Stream	✅	Stream der hochzuladenden Datei

Rückgabe: Tupel mit checksum und chunk.

Dokumente exportieren

`client.write_attachment(attachment, path, on_duplicate="enumerate")`

Exportiert ein Dokument in ein Verzeichnis.

Parameter	Typ	Pflicht	Beschreibung
`attachment`	Dictionary	✅	Dokument-Dictionary aus `record['attachments'][n]` (via `client.get_record`)
`path`	String (absoluter Pfad)	✅	Zielverzeichnis oder vollständiger Dateipfad (muss absolut sein)
`on_duplicate`	String	❌	Verhalten bei bestehender Datei: `enumerate` (Standard), `overwrite`, `skip`

Rückgabe: Absoluter Pfad der gespeicherten Datei.

`client.write_viewable(attachment, path, on_duplicate="enumerate")`

Exportiert die Vorschau-Datei eines Dokuments in ein Verzeichnis.

Parameter	Typ	Pflicht	Beschreibung
`attachment`	Dictionary	✅	Dokument-Dictionary aus `record['attachments'][n]` (via `client.get_record`)
`path`	String (absoluter Pfad)	✅	Zielverzeichnis oder vollständiger Dateipfad (muss absolut sein)
`on_duplicate`	String	❌	Verhalten bei bestehender Datei: `enumerate` (Standard), `overwrite`, `skip`

Rückgabe: Absoluter Pfad der gespeicherten Vorschau-Datei, oder None wenn keine Vorschau-Datei vorhanden ist.

E-Mail versenden

`client.send_email(recipients, subject, attachments_ids=tuple(), files=tuple(), markdown=None, html=None, text=None)`

Versendet eine E-Mail über den Webserver.

Parameter	Typ	Pflicht	Beschreibung
`recipients`	Liste von Strings	✅	Mindestens eine Empfänger-E-Mail-Adresse
`subject`	String	✅	Betreff der E-Mail
`attachments_ids`	Liste von IDs	❌	Dokument-IDs als E-Mail-Anhänge
`files`	Liste von Strings	❌	Dateipfade als E-Mail-Anhänge
`markdown`	String	❌	E-Mail-Text im Markdown-Format
`html`	String	❌	E-Mail-Text im HTML-Format
`text`	String	❌	E-Mail-Text im Plaintext-Format

Hinweis: Für den E-Mail-Text können Sie eines der drei Formate (markdown, html oder text) verwenden.

Rückgabe: Keiner.

Verwandte Artikel

Konfiguration - Datenfelder in Archiven

Hotfolder-Ausführung mit pa_hotfolder.exe

SmartSafe

API - Übersicht

Indexing-Services

Generischer API-Client

pa_client.exe – Python-Skripte & API-Client Referenz

Übersicht

Skript ausführen

Konfiguration

Option 1: client.ini

Option 2: Kommandozeile

Struktur des Python-Skripts

Parameter-Kategorien

API-Client Methoden – Referenz

Historie

client.add_history(message, record_id, timestamp=None)

Datentabellen

client.create_datatable_entry(datatable, data={})

client.delete_datatable_entry(entry_id)

client.find_datatables(query=None, limit=None, **kwargs)

client.find_datatable_entries(datatable, query=None, limit=None, **kwargs)

client.get_datatable(datatable)

client.get_datatable_entry(entry_id)

client.update_datatable_entry(entry_id, data={})

client.delete_datatable_entry(entry_id)

Archive

client.get_archive(identifier, include_virtual=False)

Vorgänge

client.find_records(archive, query=None, limit=None, **kwargs)

client.get_record(record_id)

client.iterate_records(archive, query=None)

client.update_record(record_id, data={}, tags=[])

client.delete_record(record_id)

client.execute_transition(record, id=None, name=None)

Zähler

client.get_counter_value(counter)

Benutzer & Gruppen

client.get_viewer_user(username=None, group=None)

Export

client.run_export(archive, records, export_type, path, export_options=None, on_duplicate="enumerate", columns=None)

Dateien hochladen

client.upload_file(filename)

client.upload_fileobj(fileobj)

Dokumente exportieren

client.write_attachment(attachment, path, on_duplicate="enumerate")

client.write_viewable(attachment, path, on_duplicate="enumerate")

E-Mail versenden

client.send_email(recipients, subject, attachments_ids=tuple(), files=tuple(), markdown=None, html=None, text=None)

`client.add_history(message, record_id, timestamp=None)`

`client.create_datatable_entry(datatable, data={})`

`client.delete_datatable_entry(entry_id)`

`client.find_datatables(query=None, limit=None, **kwargs)`

`client.find_datatable_entries(datatable, query=None, limit=None, **kwargs)`

`client.get_datatable(datatable)`

`client.get_datatable_entry(entry_id)`

`client.update_datatable_entry(entry_id, data={})`

`client.delete_datatable_entry(entry_id)`

`client.get_archive(identifier, include_virtual=False)`

`client.find_records(archive, query=None, limit=None, **kwargs)`

`client.get_record(record_id)`

`client.iterate_records(archive, query=None)`

`client.update_record(record_id, data={}, tags=[])`

`client.delete_record(record_id)`

`client.execute_transition(record, id=None, name=None)`

`client.get_counter_value(counter)`

`client.get_viewer_user(username=None, group=None)`

`client.run_export(archive, records, export_type, path, export_options=None, on_duplicate="enumerate", columns=None)`

`client.upload_file(filename)`

`client.upload_fileobj(fileobj)`

`client.write_attachment(attachment, path, on_duplicate="enumerate")`

`client.write_viewable(attachment, path, on_duplicate="enumerate")`

`client.send_email(recipients, subject, attachments_ids=tuple(), files=tuple(), markdown=None, html=None, text=None)`