Generischer API-Client

Über die pa_client.exe können selbstgeschriebene Python-Skripte ausgeführt werden, denen ein HTTP-Client zur Kommunikation mit der API bereitgestellt wird.

Dazu wird das Kommando exec verwendet und eine Skript-Datei angegeben:

pa_client.exe exec myscript.py

Dafür benötigte Informationen werden für das exec-Kommando in einer client.ini oder auf der Kommandozeile konfiguriert. Eine beispielhafte client.ini sieht folgendermaßen aus:

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

Ein Aufruf via Kommandozeile erfolgt in der Syntax:

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

Die Optionen token und url müssen dabei vor exec angegeben werden. Das bereitgestellte Skript muss eine main Funktion mit folgenden Parametern haben.

def main(client, args):
    pass
client

Ist ein API-Client, der dem Skript zur Verfügung gestellt wird und mit dem man die API-Endpunkte abfragen kann.

args

Sind eine weitere Liste von Kommandozeilen-Argumenten, die nach dem Skript Namen angegeben werden und für das Skript selbst gedacht sind.

Methoden des API-Clients

Zum Unterscheiden zweier Parameter-Typen gibt es für die unten beschriebenen Methoden eine Unterscheidung einer ID- oder ID/Kurznamen-Eigenschaft:

Kategorie id

  • Ein UUID-Objekt

  • Ein String im UUID-Format

  • Ein Dictionary, mit einem Schlüssel id, das den Wert als String im UUID-Format enthält

Kategorie identifier

  • Eigenschaften der Kategorie id

  • Ein String, der einen Kurznamen enthält. Zum Beispiel vom Archiv oder einer Datentabelle.

client.delete_datatable_entry(entry_id)

Löscht einen Eintrag einer Datentabelle.

  • Ein Pflicht-Parameter der Kategorie id.

Kein Rückgabewert.

client.delete_record(record_id)

Löscht einen Vorgang.

  • Ein Pflicht-Parameter der Kategorie id.

Kein Rückgabewert.

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

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

  • Pflicht-Parameter record ist ein Dictionary mit Vorgangs-Informationen, wie es von client.get_record zurückgegeben wird.

  • Parameter id und name sind optional, solange es exakt einen Übergang gibt.

Kein Rückgabewert.

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

Findet eine oder mehrere Datentabellen anhand der gegebenen Optionen.

  • Optionaler Parameter query vom Typ String gibt einen Filter an. Unterstützt werden die Spalten-Kürzel identifier, name und description, welche nicht „_“ vorangestellt sind.

  • Optionaler Parameter limit bestimmt die maximale Anzahl der zurückgegebenen Tabellen.

  • In den kwargs werden die zuvor benannten Spalten optional AND-verknüpft an query verknüpft.

Rückgabewert ist eine Liste von Datentabellen als Dictionaries.

Beispiele:

# Gibt alle Datentabellen zurück
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)

Findet eine oder mehrerer Datentabellen-Einträge anhand der gegebenen Optionen.

  • Pflicht-Parameter datatable der Kategorie identifier.

  • Optionaler Parameter query vom Typ String gibt einen Filter an.

  • Optionaler Parameter limit bestimmt die maximale Anzahl der zurückgegebenen Tabellen-Einträge.

  • In den kwargs können weitere Filter-Kriterien angegeben werden, welche an die query mittels des AND-Operators optional angeknüpft werden.

Rückgabewert ist eine Liste von Datentabellen-Einträgen als Dictionaries.

Beispiele:

# Datentabellen-ID, query mit Feld-Kürzel und Wert, zusätzlich wird der Rechnungs-Typ angegeben
datatable = "FFFFFFFF-0000-0000-0000-000000000001"
entries = client.find_datatable_entries(datatable, query="_name != <empty>", _rechtyp="Rechnung")

# Datentabellen-Kürzel, query mit Feld-Kürzel und Wert
datatable = "iq_lieferanten"
entries = client.find_datatable_entries(datatable, query='_ustid = "R6011-1000-1"')
client.find_records(archive, query=None, limit=None, **kwargs)

Findet eine oder mehrerer Vorgänge anhand der gegebenen Optionen.

  • Pflicht-Parameter archive der Kategorie identifier.

  • Optionaler Parameter query vom Typ String gibt einen Filter an.

  • Optionaler Parameter limit bestimmt die maximale Anzahl der zurückgegebenen Vorgänge.

  • In den kwargs können weitere Filter-Kriterien angegeben werden, welche an die query mittels des AND-Operators optional angeknüpft werden.

Rückgabewert ist eine Liste von Vorgängen als Dictionaries.

Beispiele:

# Archiv-ID, query mit Feld-Kürzel und Wert, zusätzlich auf eine USTID reduziert
archive = "FFFFFFFF-0000-0000-0000-000000000002"
records = client.find_records(archive, query="_krednr != <empty>", _ustid="R6011-1000-1")

# Archiv-Kürzel, query mit Feld-Kürzel und Wert
archive = "iq_invoice"
entries = client.find_records(archive, query="_saldo < 1000")
client.get_archive(identifier, include_virtual=False)

Findet eine Archiv anhand einer ID oder eines Archiv-Kurznamens.

  • Pflicht-Parameter identifier der Kategorie identifier.

  • Optionaler Parameter include_virtual vom Typ Boolean. Standardmäßig False, bei True werden auch gefilterte und zusammengefasste Archive zurückgegeben.

Rückgabewert ist ein Dictionary mit Informationen des Archives.

client.get_counter_value(counter)

Führt den nächsten Zähler-Schritt anhand der ID oder eines Zähler-Kurznamens aus.

  • Pflicht-Parameter counter der Kategorie identifier.

Rückgabewert ist der nächste Zähler-Wert des angegebenen Zählers.

client.get_datatable(datatable)

Findet eine Datentabelle anhand einer ID oder eines Datentabellen-Kurznamens.

  • Pflicht-Parameter datatable der Kategorie identifier.

Rückgabewert ist ein Dictionary mit Informationen der Datentabelle.

client.get_datatable_entry(entry_id)

Findet einen Datentabellen-Eintrag anhand einer ID.

  • Pflicht-Parameter entry_id der Kategorie id.

Rückgabewert ist ein Dictionary mit Informationen des Datentabellen-Eintrags.

client.get_record(record_id)

Findet einen Vorgang anhand einer ID.

  • Pflicht-Parameter record_id der Kategorie id.

Rückgabewert ist ein Dictionary mit Informationen des Vorgangs.

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

Findet einen Benutzer oder eine Gruppe anhand der gegebenen Optionen.

  • Optionaler Parameter username gibt als Such-Kriterium den Benutzernamen an.

  • Optionaler Parameter group gibt als Such-Kriterium den Gruppennamen an.

Rückgabewert ist ein Dictionary mit Informationen eines Benutzers oder einer Gruppe.

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

Findet einen Benutzer oder eine Gruppe anhand der gegebenen Optionen.

  • Optionaler Parameter username gibt als Such-Kriterium den Benutzernamen an.

  • Optionaler Parameter group gibt als Such-Kriterium den Gruppennamen an.

Rückgabewert ist ein Dictionary mit Informationen eines Benutzers oder einer Gruppe oder None, falls es kein Ergebnis gibt.

client.iterate_records(archive, query=None)

Lädt Vorgänge effizient anhand eines optionalen Suchkriteriums.

  • Pflicht-Parameter archive der Kategorie identifier.

  • Optionaler Parameter query vom Typ String gibt einen Filter an.

Rückgabewert ist eine Sammlung von Vorgängen (Dictionaries), durch die iteriert werden kann.

Beispiel:

record_ids = set()
archive = "invoices"
for record in client.iterate_records(archive, query="_priority > 1"):
    record_ids.add(record["id"])
self.run_export(archive, records, export_type, path, export_options=None, on_duplicate=OnDuplicate.Enumerate)

Export“-markierte Dateien werden im angegebenen Format exportiert.

  • Pflicht-Parameter archive der Kategorie identifier.

  • Pflicht-Parameter records. Gibt eine einzelne Vorgangs-ID oder eine Liste von Vorgangs-IDs an.

  • Pflicht-Parameter export_type. Hier muss einer der folgenden Werte übergeben werden, um das gewünschte Export-Format auszuwählen:

    • attachments für „Dokumente zusammenfassen“

    • csv für CSV

    • csv_with_attachments für CSV mit Dokumenten

    • accounting_records für Buchungssätze

    • pdf für PDF

    • pdf_with_attachments für PDF mit Dokumenten

    • xlsx für Excel

  • Pflicht-Parameter path. Wahlweise ein Verzeichnis oder ein vollständiger Dateipfad. Dieser Pfad muss absolut sein. Wenn als Pfad ein Verzeichnis angegeben wird, wird das Dokument unter einem vom Export erzeugten Dateinamen in diesem Verzeichnis abgespeichert.

  • Optionaler Parameter export_options. Ein dict, mit dem sich Optionen beim Export steuern lassen. Aktuell werden folgende Optionen unterstützt:

    • attachments_first für die Reihenfolge der PDF-Inhalte beim Export-Type

    • pdf_with_attachments. Bei True werden die Dokumente vor den Vorgangsinformationen in die PDF-Datei geschrieben. Vorgabe ist False.

    • with_history für das Exportieren der Historie. Standardmäßig wird sie exportiert.

  • Optionaler Parameter on_duplicate. Gibt an, was passieren soll, wenn die in path übergebene Datei bereits existiert. Mögliche Werte sind enumerate (es wird ein Zähler an die Datei angehängt, z.B. datei_01.pdf), overwrite (die Datei wird überschrieben) und skip (die Datei wird übersprungen und nicht exportiert). Standard ist enumerate.

Die Funktion liefert den absoluten Pfad zurück, unter dem die Datei abgespeichert wurde oder None, wenn der Export nicht erfolgreich war und eine Warnung geloggt wurde.

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

Versendet über den Webserver eine E-Mail.

  • Pflicht-Parameter recipients. Eine Liste mit mindestens einer Empfänger-E-Mail-Adresse.

  • Pflicht-Parameter subject. Gibt den Betreff der E-Mail an.

  • Optionaler Parameter attachments_ids. Liste von Dokumenten-IDs, die man optional an die E-Mail anhängen möchte.

  • Optionaler Parameter files. Liste von Dokumenten-Pfaden, die man optional an die E-Mail anhängen möchte.

  • Optionaler Parameter markdown, html oder text. Es kann eines dieser drei Formate für den E-Mail-Text angegeben werden.

Kein Rückgabewert.

client.update_datatable_entry(entry_id, data={})

Aktualisiert einen Datentabellen-Eintrag anhand einer ID.

  • Pflicht-Parameter entry_id der Kategorie id.

  • Optionaler Parameter data. Ist ein Dictionary mit den im Datentabellen-Eintrag zu ändernden Daten.

Rückgabewert ist ein Dictionary mit Informationen des aktualisierten Datentabellen-Eintrags.

client.upload_file(filename)

Lädt eine Datei hoch, die später z.B. archiviert werden kann.

  • Pflicht-Parameter filename. Gibt einen Dateipfad an.

Rückgabewert ist ein Tupel, welches checksum und chunk enthält.

client.upload_fileobj(fileobj)

Lädt eine Datei hoch, die später z.B. archiviert werden kann.

  • Pflicht-Parameter fileobj. Gibt einen Binär-Stream an.

Rückgabewert ist ein Tupel, welches checksum und chunk enthält.

client.update_record(record_id, data={})

Aktualisiert einen Vorgang anhand einer ID.

  • Pflicht-Parameter record_id der Kategorie id.

  • Optionaler Parameter data. Ist ein Dictionary mit den im Vorgang zu ändernden Daten.

Rückgabewert ist ein Dictionary mit Informationen des aktualisierten Vorgangs.

client.write_attachment(attachment, path, on_duplicate=OnDuplicate.Enumerate)

Exportiert ein Dokument in einen angegebenen Verzeichnis-Pfad.

  • Pflicht-Parameter attachment. Das Dokument, das exportiert werden soll, übergeben als Dictionary z.B. aus einem geladenen Vorgang über client.get_record. Anhand record['attachments'][n], wobei n in Listen-Index ist, kann die Information zum Anhang extrahiert werden.

  • Pflicht-Parameter path. Wahlweise ein Verzeichnis oder ein vollständiger Dateipfad. Dieser Pfad muss absolut sein. Wenn als Pfad ein Verzeichnis angegeben wird, wird das Dokument unter dem im Archiv hinterlegten Dateinamen in diesem Verzeichnis abgespeichert.

  • Optionaler Parameter on_duplicate. Gibt an, was passieren soll, wenn die in path übergebene Datei bereits existiert. Mögliche Werte sind enumerate (es wird ein Zähler an die Datei angehängt, z.B. datei_01.pdf), overwrite (die Datei wird überschrieben) und skip (die Datei wird übersprungen und nicht exportiert). Standard ist enumerate.

Rückgabewert ist ein absoluter Pfad, unter dem die Datei abgespeichert wurde.

client.write_viewable(attachment, path, on_duplicate=OnDuplicate.Enumerate)

Exportiert eine Vorschau-Datei eines Dokuments in einen angegebenen Verzeichnis-Pfad.

  • Pflicht-Parameter attachment. Das Dokument, das exportiert werden soll, übergeben als Dictionary z.B. aus einem geladenen Vorgang über client.get_record. Anhand record['attachments'][n], wobei n in Listen-Index ist, kann die Information zum Anhang extrahiert werden.

  • Pflicht-Parameter path. Wahlweise ein Verzeichnis oder ein vollständiger Dateipfad. Dieser Pfad muss absolut sein. Wenn als Pfad ein Verzeichnis angegeben wird, wird das Dokument unter dem im Archiv hinterlegten Dateinamen in diesem Verzeichnis abgespeichert.

  • Optionaler Parameter on_duplicate. Gibt an, was passieren soll, wenn die in path übergebene Datei bereits existiert. Mögliche Werte sind enumerate (es wird ein Zähler an die Datei angehängt, z.B. datei_01.pdf), overwrite (die Datei wird überschrieben) und skip (die Datei wird übersprungen und nicht exportiert). Standard ist enumerate.

Rückgabewert ist ein absoluter Pfad, unter dem die Vorschau-Datei abgespeichert wurde. Sollte keine Vorschau-Datei zum Dokument existieren, wird ein None zurückgegeben.