KEPLIN Docs

Das SDK der Skripte

Die zehn Module des SDK api_manager — Datenquellen, HTTP, Logs, hochgeladene Dateien, Secrets, Benachrichtigungen, Workflows, Konten, Berichte und KI — mit Python-Beispielen.

Innerhalb eines Skripts ist die ganze App nur einen import entfernt. Das SDK heißt api_manager und wird Modul für Modul importiert:

from api_manager import db, http, log, files, secrets, notify, workflow, users, reports, ai

Diese zehn Namen sind die gesamte öffentliche Oberfläche des SDK — was hier nicht steht, existiert zur Laufzeit nicht:

Modul Wofür
db Die Datenquellen der App abfragen (Oracle, PostgreSQL, MySQL/MariaDB, SQL Server, …).
http HTTP-Anfragen an externe Dienste, mit automatischem JSON.
log Zeilen in die Logs der Ausführung schreiben.
files Über eine API hochgeladene Dateien lesen.
secrets Geheimnisse der App lesen, auf dem Server entschlüsselt.
notify In-App-Benachrichtigungen und E-Mails an die Benutzer der App.
workflow Prozesse starten, Wartezustände aufwecken und menschliche Aufgaben entscheiden.
users Die Konten der App anlegen und ändern und ihnen Rollen zuweisen.
reports Die Berichte der App als PDF oder Excel erzeugen.
ai Die KI-Modelle der App nutzen: Text, JSON, Werkzeuge, Embeddings, Bilder, Audio und Batches.

Der Editor vervollständigt all das automatisch — die Namen, die Parameter und die Dokumentation jeder Funktion erscheinen, während Sie schreiben.

Tipp

Die Schaltfläche Prompt für LLM in der Leiste des Editors öffnet den vollständigen Leitfaden zum SDK, fertig zum Kopieren mit Alles kopieren. Fügen Sie ihn in Claude, ChatGPT oder einen anderen Assistenten ein, zusammen mit dem, was das Skript tun soll — der Assistent kennt dann den genauen Vertrag und erfindet keine Funktionen, die es nicht gibt.

Der Prompt für LLM — der gesamte Vertrag des SDK als Text, fertig zum Einfügen in einen KI-Assistenten.
Der Prompt für LLM — der gesamte Vertrag des SDK als Text, fertig zum Einfügen in einen KI-Assistenten.

db — die Datenquellen der App

Die in der App konfigurierten Datenquellen werden über ihren Namen referenziert. Zwei Funktionen:

from api_manager import db

crm = db("Dados CRM")

linhas = crm.query(          # Liste von Dicts (Spalte -> Wert)
    "select id, nome from contas where cidade = ?", ["Lisboa"]
)
conta = crm.query_one(       # die erste Zeile, oder None
    "select * from contas where id = ?", [42]
)

params ist eine positionelle Liste. Die Platzhalter sind die der Engine der Datenquelle:

Engine Platzhalter Beispiel
PostgreSQL $1, $2, … where id = $1
MySQL / MariaDB ? where id = ?
Oracle :1, :2, … where id = :1

Existiert die Datenquelle nicht, wirft der Aufruf einen Fehler (und die Ausführung endet mit Fehler, wenn Sie ihn nicht abfangen).

Achtung

Datumsangaben in Oracle: Übergeben Sie sie besser nicht als Parameter — der Transport per JSON macht den Typ mehrdeutig. Bevorzugen Sie das Literal im SQL: TO_DATE('2026-06-25','YYYY-MM-DD').

Eine binäre Spalte (bytea, blob, varbinary) kommt als bytes an, und ein Parameter in bytes wird binär gespeichert:

foto = crm.query_one("select foto from contas where id = ?", [42])["foto"]
crm.query("update contas set foto = ? where id = ?", [novos_bytes, 42])

Verbindung und Transaktionen

Alle Abfragen einer Ausführung an dieselbe Datenquelle laufen über dieselbe Verbindung, die nur dieser Ausführung gehört. Deshalb können Sie Transaktionen verwenden:

crm.query("begin")
crm.query("update contas set saldo = saldo - ? where id = ?", [100, 1])
crm.query("update contas set saldo = saldo + ? where id = ?", [100, 2])
crm.query("commit")

Was beim Ende der Ausführung (mit Fehler, beim Zeitlimit oder abgebrochen) noch nicht bestätigt ist, wird zurückgerollt. Eine fehlgeschlagene Abfrage schließt die Verbindung, und die nächste öffnet eine neue, bereits außerhalb der Transaktion. In SQL Server beginnt eine Transaktion mit begin transaction. Oracle hat kein begin: Änderungen werden erst mit einem commit gespeichert.

http — Anfragen an externe Dienste

Fünf Verben, alle mit automatischem JSON — ein body als Dict oder Liste geht als JSON hinaus, und eine JSON-Antwort kommt bereits dekodiert an:

from api_manager import http, log

r = http.get("https://api.exemplo.com/clientes")
# r = {"status": int, "ok": bool, "body": <dekodiertes JSON oder Text>}
if r["ok"]:
    log("empfangen", len(r["body"]), "Kunden")

r = http.post(
    "https://api.exemplo.com/leads",
    body={"nome": "Vininha & Filhos", "origem": "keplin"},
    headers={"Authorization": "Bearer abc123"},
)

Es gibt auch http.put(url, body, headers), http.patch(url, body, headers) und http.delete(url, headers). r["ok"] ist wahr für 2xx-Antworten — ein 404 oder 500 wirft keine Ausnahme, prüfen Sie den Status selbst.

log — die Logs der Ausführung

from api_manager import log

log("wird verarbeitet", 42, {"fase": "inicial"})

Es nimmt mehrere Argumente entgegen, wie print — und jeder Aufruf ist eine Zeile in den Logs der Ausführung, sichtbar im Panel Ergebnis der Ausführung und in der Historie Ausführungen. Das klassische print wird ebenfalls erfasst, aber log ist die kanonische Form des SDK.

Das Detail einer Ausführung — das zurückgegebene Ergebnis und die vom Skript geschriebenen Log-Zeilen.
Das Detail einer Ausführung — das zurückgegebene Ergebnis und die vom Skript geschriebenen Log-Zeilen.

files — hochgeladene Dateien

Wenn eine API der App ein Argument vom Typ Upload hat, schickt der Client eine Datei und das Skript erhält sie in input["args"] als Handle — die Bytes liegen auf der Festplatte, nicht im Speicher. Das Modul files arbeitet auf diesem Handle:

from api_manager import files


def main(input):
    f = input["args"]["ficheiro"]      # das Handle des Uploads
    texto = files.read_text(f)         # str (utf-8)
    dados = files.read(f)              # bytes
    caminho = files.path(f)            # absoluter Pfad auf der Festplatte
    files.save(f, "ultimo-recebido.csv")   # kopiert in den Ordner des Skripts
    return {"nome": f["filename"], "tamanho": f["size"]}

Das Handle bringt filename, mimeType und size mit — nützlich, um vor der Verarbeitung zu prüfen.

secrets — Geheimnisse der App

Tokens und Schlüssel liegen verschlüsselt auf der Seite Secrets der App (seitlicher Baum, Gruppe App). Das Skript liest sie über den Schlüssel:

from api_manager import secrets

token = secrets.get("STRIPE_KEY")   # -> str | None
if token is None:
    raise RuntimeError("Secret STRIPE_KEY in dieser App nicht konfiguriert.")

Der Wert wird auf dem Server entschlüsselt, im Moment der Ausführung — er erscheint nie im Browser und bleibt nicht im Code.

Die Seite Secrets der App — die Schlüssel, die die Skripte mit secrets.get lesen.
Die Seite Secrets der App — die Schlüssel, die die Skripte mit secrets.get lesen.

Achtung

Machen Sie kein log(token). Die Logs bleiben in der Ausführungshistorie — ein Geheimnis, das in ein Log geschrieben wurde, ist kein Geheimnis mehr.

notify — Benachrichtigungen und E-Mails

Die App hat zwei feste Kanäle — einen In-App-Kanal und einen für E-Mail —, aktivierbar in den Einstellungen für Benachrichtigungen der App (dort wohnen die SMTP-Konfiguration und der Absender). users sind Benutzernamen von Benutzern der App; roles weiten sich auf alle Mitglieder der Rolle aus.

In-App, in Echtzeit:

from api_manager import notify

r = notify.send(
    "Bericht fertig",
    subtitle="Monatsberichte",
    body="Der Monatsbericht ist verfügbar.",
    users=["joao"],
    roles=None,
    data={"url": "/relatorios/42"},
)
# r = {"recipients": int, "delivered": int}

delivered zählt die in Echtzeit Zugestellten, an alle, die verbunden sind; die übrigen bleiben im Posteingang und erhalten sie beim Anmelden.

E-Mail:

r = notify.email(
    "Bestandswarnung",
    to=["chefe@empresa.pt"],      # freie Adressen
    users=None,
    roles=["admin"],              # und/oder Benutzer und Rollen der App
    text="Bestand unter dem Minimum.",
    html=None,
)
# r = {"accepted": [emails], "skipped": [usernames ohne E-Mail]}

Der SMTP-Versand geschieht asynchron auf dem Server — das Skript wartet nicht. attachments nimmt Anhänge mit dem Inhalt in base64 entgegen (siehe reports weiter unten für den typischen Fall).

workflow — die Prozesse der App

Ein Skript kann einen Prozess starten, jene aufwecken, die auf ein Ereignis warten, und menschliche Aufgaben entscheiden. Der Prozess wird über seinen Namen referenziert (oder über seine stabile Kennung); key ist der Schlüssel des Datensatzes, auf dem er läuft:

from api_manager import workflow

r = workflow.start("Aprovação de despesa", 42, data={"valor": 1200})
# r = {"instanceId": int}

r = workflow.signal("visto", key=42)
# r = {"woken": int}

abertas = workflow.tasks("joao")
# offene Aufgaben dieses Benutzers der App, mit den möglichen Entscheidungen

r = workflow.complete(task=17, outcome="aprovar", as_user="joao",
                      data={"nota": "ok"})
# r = {"ok": bool}

Regeln, die zählen:

  • workflow.start gibt zurück, sobald die Maschine die erste Wartestelle erreicht — es wartet nie darauf, dass der Prozess endet.
  • workflow.signal ohne key weckt alle Prozesse auf, die bei diesem Ereignis stehen; {"woken": 0} ist kein Fehler — es kann sein, dass niemand wartet.
  • Bei workflow.complete ist as_user verpflichtend (wer entscheidet, bleibt in der Historie) und die Aufgabe muss diesem Benutzer zugewiesen sein. Die Werte von outcome sind die Ausgänge des Aufgabenknotens — dieselben, die die Person als Schaltflächen sieht. Erfinden Sie keine Namen.

users — die Konten der App

Ein Skript legt die Konten der App an, ändert sie und weist ihnen Rollen zu, die es bereits gibt. Rollen und Berechtigungen werden im Builder angelegt; das Modul legt sie weder an noch ändert es sie. user ist die ID (Zahl) oder der Benutzername (Text) des Kontos:

from api_manager import users

users.roles()                      # ["gestor", "vendedor"]
u = users.create("ana", password=input["args"]["password"],
                 email="ana@empresa.pt", name="Ana Silva", roles=["vendedor"])
# u = {"id", "username", "email", "name", "disabled", "roles",
#      "createdAt", "lastLoginAt"}

users.get("ana")                   # das Konto oder None
users.list(role="vendedor")        # ohne die deaktivierten Konten
users.update("ana", name="Ana M. Silva", disabled=True)
users.set_password("ana", nova)
users.set_roles("ana", ["vendedor", "gestor"])
users.add_role("ana", "gestor")
users.remove_role("ana", "vendedor")

Regeln, die zählen:

  • Es gelten die Regeln des Builders und der öffentlichen Registrierung: Benutzernamen mit 3 bis 120 Zeichen (Buchstaben, Ziffern, Punkt, Bindestrich, _ und @), eine gültige E-Mail-Adresse, Passwörter mit 8 bis 200 Zeichen, und freie Benutzernamen und E-Mail-Adressen, auch gegeneinander.
  • Die Konten kommen ohne das Passwort im Skript an. Ohne password kann sich das Konto erst anmelden, nachdem jemand eines gesetzt hat.
  • users.update ändert nur die angegebenen Felder, und email=None löscht die E-Mail-Adresse. users.list nimmt deaktivierte Konten mit include_disabled=True auf.
  • Änderungen gelten sofort: Ein deaktiviertes Konto verliert den Zugang bei der nächsten Anfrage, und set_password beendet die offenen Sitzungen des Kontos.
  • Jede Änderung landet im Audit, mit dem, der das Skript ausgelöst hat, und dem Namen des Skripts.
  • Nenne das Argument für das Passwort password: Die Historie Ausführungen verbirgt Argumente mit diesem Namen.

Ein Fehler löst users.Error mit einem stabilen code aus: invalid_username, invalid_email, invalid_name, weak_password, username_taken, email_taken, unknown_role, not_found oder invalid_request.

def main(input):
    a = input["args"]
    try:
        u = users.create(a["username"], password=a["password"], roles=["vendedor"])
    except users.Error as e:
        if e.code == "username_taken":
            return {"ok": False, "fehler": "Diesen Benutzernamen gibt es bereits."}
        raise
    return {"ok": True, "id": u["id"]}

reports — Berichte der App erzeugen

Das Dokument wird auf dem Server erzeugt, mit den Daten der App, ausgehend von einem bestehenden Bericht:

from api_manager import notify, reports

r = reports.render("Facturas do mês", {"mes": "2026-03"})
# r = {"filename", "pages", "format", "mime", "bytes", "base64"}

notify.email(
    "Rechnungen für März",
    to=["financeiro@empresa.pt"],
    text="Anbei das Dokument.",
    attachments=[{"filename": r["filename"], "content": r["base64"]}],
)

Das dritte, optionale Argument ist das Format: "pdf" (Standard) oder "xlsx". Die Parameter sind die, die der Bericht deklariert. Im Ergebnis kommt bytes fertig zum Schreiben auf die Festplatte und base64 fertig zum Anhängen an eine E-Mail.

Ein Skript läuft, ohne dass jemand angemeldet ist: reports.render und die workflow-Verben lesen und schreiben Daten als die App selbst, mit allen aktiven APIs, sowohl in einem Zeitplan als auch bei Jetzt ausführen.

ai — die KI-Modelle der App

Skripte fragen die KI-Modelle an, die die App unter KI-Modelle konfiguriert hat, über den Namen des Alias. Die Schlüssel der Anbieter bleiben auf dem Server, und das Skript sieht sie nie:

from api_manager import ai


def main(input):
    resumo = ai.chat("Resume este pedido numa frase: " + input["args"]["pedido"])
    dados = ai.json(
        "Extrai o nome e o email do cliente: " + input["args"]["pedido"],
        schema={
            "type": "object",
            "properties": {"nome": {"type": "string"}, "email": {"type": "string"}},
            "required": ["nome", "email"],
        },
    )
    vector = ai.embed(resumo["text"])
    return {"resumo": resumo["text"], "cliente": dados, "dimensoes": len(vector)}
Funktion Gibt zurück
ai.chat(prompt, ...) Ein Dict mit text, stop_reason, usage, model, provider und alias.
ai.json(prompt, schema=..., ...) Das JSON der Antwort, bereits gegen das Schema validiert.
ai.embed(texte) Einen Vektor pro Text (eine Liste von Zahlen).
ai.models() Die Aliase der App, jeweils mit Verwendung und Modell.
ai.run(prompt, tools=[...], ...) Die endgültige Antwort einer Aufgabe, bei der das Modell Funktionen des Skripts nutzt, mit den Schritten.
ai.image(prompt, ...) Die erzeugten Bilder, bereits in der App gespeichert.
ai.transcribe(datei, ...) Den Text einer Aufnahme.
ai.speak(text, ...) Das Audio der Sprache, bereits in der App gespeichert.
ai.batch.submit(anfragen, ...) Die ID eines im Hintergrund verarbeiteten Batches; ai.batch.get, ai.batch.results und ai.batch.cancel verfolgen ihn.

Die Parameter, die Dateien, die Fehlercodes und die Limits stehen unter KI in Skripten verwenden, Werkzeuge und Batches und Bilder und Audio.

Ein vollständiges Beispiel

In der Art des Skripts atualizar_indicadores der App Kundenverwaltung — es liest die Pipeline, schreibt nützliche Logs und meldet sich, wenn Abschlüsse bevorstehen:

from datetime import date, timedelta

from api_manager import db, log, notify


def main(input):
    crm = db("Dados CRM")

    abertas = crm.query_one(
        "select count(*) as n, coalesce(sum(valor), 0) as total "
        "from oportunidades where fase not in ('fechada_ganha', 'fechada_perdida')"
    )

    limite = (date.today() + timedelta(days=7)).isoformat()
    fechos = crm.query(
        "select titulo, data_fecho from oportunidades "
        "where fase not in ('fechada_ganha', 'fechada_perdida') "
        "and data_fecho <= ? order by data_fecho",
        [limite],
    )

    log("Pipeline:", abertas["n"], "Verkaufschancen /", abertas["total"], "EUR")
    if fechos:
        notify.send(
            "Abschlüsse in dieser Woche",
            body=f"{len(fechos)} Verkaufschancen mit geplantem Abschluss bis {limite}.",
            roles=["comercial"],
        )

    return {
        "oportunidades_abertas": abertas["n"],
        "valor_pipeline": abertas["total"],
        "fechos_proximos_7_dias": len(fechos),
    }

Grenzen und gute Praxis

  • Das Ergebnis von main muss JSON-serialisierbar sein; maximal 32 MB.
  • Jede Ausführung achtet auf das Zeitlimit des Skripts (30 Sekunden bis 10 Minuten) — bei Überschreitung wird der Prozess beendet und bleibt auf Timeout.
  • Die Ausführungen sind isoliert: Verlassen Sie sich nicht auf Variablen einer vorherigen Ausführung. Speichern Sie dauerhaft in Dateien des Skript-Ordners oder in einer Datenquelle.
  • Setzen Sie in jeder relevanten Phase ein log(...) — das ist es, was Sie lesen werden, wenn etwas an einem Sonntag um 7:00 Uhr fehlschlägt.
  • Fangen Sie die behebbaren Fehler ab und protokollieren Sie sie; lassen Sie die fatalen durch — eine nicht abgefangene Ausnahme markiert die Ausführung als Fehler, und genau das wollen Sie in der Historie sehen, wenn wirklich etwas im Argen liegt.
  • Geben Sie keine Geheimnisse aus und lesen Sie sie immer über secrets — schreiben Sie sie nie in den Code.

Häufige Fragen

from api_manager import db schlägt auf meinem Rechner fehl. Das ist zu erwarten: Das Modul api_manager existiert nur bei der Ausführung auf der Plattform — dort wird es eingespeist. Im Editor haben Sie die vollständige Autovervollständigung des SDK; die Datei api_manager.py, die Sie im Ordner des Skripts sehen, existiert nur dafür.

db("nome") sagt, dass die Datenquelle nicht existiert. Der Name muss exakt dem der Datenquelle in der App entsprechen (z. B.: Dados CRM, mit Großbuchstaben und Leerzeichen). Die Liste sehen Sie im Abschnitt Datenquellen des Baums.

notify.email hat accepted zurückgegeben, aber die E-Mail kam nicht an. Der SMTP-Versand ist asynchron — accepted bedeutet, dass die E-Mail an den E-Mail-Kanal der App weitergereicht wurde. Prüfen Sie die SMTP-Konfiguration in den Einstellungen für Benachrichtigungen der App und den Spam-Ordner des Empfängers.

Kann ich das SDK in der Validierung eines Fensters verwenden? Ja — die Validierung läuft in derselben Umgebung wie das Hauptskript, mit demselben input und demselben SDK. Siehe Zeitpläne.