API
API Zugriff
Sticky bietet dir einen JSON API-Zugriff, sodass du auf deine Firma bzw. dein Nutzerprofil zugreifen kannst, um Aufrufe oder Abläufe zu automatisieren.
API Domain
Deine Anfragen richtest du gegen folgende Domain via HTTPS.
- Live Umgebung: https://app.sticky.de
- Sandbox Umgebung: https://dvl.sticky.de
Authentifizierung
Die Authentifizierung an der Sticky-API besteht immer aus drei verschiedenen „Tokens“. Diese drei Tokens werden bei jedem Aufruf als HTTP-Header angegeben. Im Standard ist der API-Zugriff für einen Benutzer deaktiviert. Du kannst in deinem Profil im Menüpunkt „API-Zugriff“ die API für deinen Account aktivieren und findest dort die drei Tokens.
Gebe deinen API-Zugangstoken bitte NIEMALS an andere Personen weiter!
- Sticky-Token
- Dieser Token ist dein persönliches Geheimnis.
- 36-stelliger Token
- Sticky-User
- Dieser Token identifiziert deinen Benutzerkontext
- 24-stelliger Token
- Sticky-Company
- Dieser Token identifiziert deinen Firmenkontext
- 24-stelliger Token
Ein Benutzer mit Zugriff auf mehrere Firmen:
In Sticky ist es natürlich möglich, dass du als Benutzer mit einem einzigen Account Zugriff auf multiple Firmen hast. Aus diesem Grund gibst du in einem API-Aufruf sowohl deinen Benutzerkontext (in welchen Benutzerrechten möchtest du agieren) sowie einen Firmenkontext (in welcher Firma möchtest du agieren) an.
Welche Endpunkte du ansprechen kannst, sind entweder im Hilfetext des jeweiligen Moduls hinterlegt oder wir stimmen das gerne im Detail mit dir ab, sofern nicht bekannt. Öffne dazu bitte einfach ein Support-Ticket.
Parameter
Um dich bei einer einfachen Implementierung zu unterstützen, kannst du die benötigten Parameter entweder als GET (URL-Parameter), POST (Formulardaten) oder als POST (JSON Payload) senden. Dies ist zwar technisch eher ungewöhnlich, jedoch ist so eine Implementierung auf deiner Seite wesentlich einfacher, da wir dir keine festen Vorgaben in Bezug auf HTTP-Methode und Format der Parameter machen. Je nach Umgebung, die du vorfindest, ist die eine oder andere Version zielführender.
Es gibt grundlegend immer folgende Parameter:
m // pflicht, das angesprochene Modul method // pflicht, der angesproche Endpunkt
c // optional, abhängig von Endpunkt msg // optional, abhängig von Endpunkt id // optional, abhängig von Endpunkt
Was genau bedeutet dies nun?
Das heißt, dass du die oben beschrieben Parameter bei einem API-Aufruf auf einer der drei gängigen Arten senden darfst. Wenn wir eine Empfehlung aussprechen sollten, würden wir die „JSON Payload“ Variante bevorzugen.
Verdeutlichen wir es an einem Beispiel des Endpunkt „vouchers / send_voucher„.
Beispiel - GET (URL-Parameter)
Bei der GET Variante werden die Parameter als URL-Parameter angehangen
URL: https://app.sticky.de/?m=vouchers&method=send_voucher&id=RE0265
Payload: leer
Beispiel - POST (Formulardaten)
Bei der POST Variante werden die Parameter als Payload mitgesendet
URL: https://app.sticky.de/
Payload: m=vouchers&method=send_voucher&id=RE0265
Beispiel - POST (JSON Payload)
URL: https://app.sticky.de/
Payload:
{
"m":"vouchers",
"method":"send_voucher",
"id":"RE0265"
}
Wie du siehst, kannst du 3 verschiedene Varianten nutzen, um die Parameter zu übertragen. Das Ergebnis ist jedoch bei allen dasselbe.
Bitte beachte: API Aufrufe funktionieren nur, wenn du via HTTP-Header authentifiziert bist. Du kannst solche Aufrufe aber auch jederzeit in einer Browsernutzung simulieren und testen. Dafür brauchst du nur den Parameter „&json“ an die URL anzuhängen. Durch diesen Zusatz wirst du nicht mehr anhand deiner HTTP-Header authentifiziert, sondern auf Basis deiner aktuellen Browser Sitzung.
Beispiel: https://app.sticky.de/?m=vouchers&method=send_voucher&id=RE0265&json
Protokollierung
Alle API-Aufrufe (inklusive der jeweils übertragenen Parameter) werden in deinem Firmenprotokoll protokolliert.
Beispielaufrufe
CURL
curl -X POST \ --location "https://app.sticky.de/?m=my_module" \ # Endpoint -H "Content-Type: application/json" \ -H "Sticky-Token: 2a3b301d-73c9-e31b-eab4-xxxxxxxxxxxx" \ # The API-Token from the given User-ID -H "Sticky-User: 5ef5d753a91766xxxxxxxxxx" \ # The Sticky User-ID -H "Sticky-Company: 2f8c1f2bcfa625xxxxxxxxxx" # The Company-ID
PHP
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://app.sticky.de/?m=my_module',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
"content-type: application/json",
"Sticky-Token: 2a3b301d-73c9-e31b-eab4-xxxxxxxxxxxx",
"Sticky-User: 5ef5d753a91766xxxxxxxxxx",
"Sticky-Company: 2f8c1f2bcfa625xxxxxxxxxx",
],
]);
$response = curl_exec($ch);
curl_close($ch);
$response_decoded = json_decode($response);
print_r($response_decoded);
JavaScript
"use strict";
let token = '2a3b301d-73c9-e31b-eab4-xxxxxxxxxxxx';
let company = '2f8c1f2bcfa625xxxxxxxxxx';
let user = '5ef5d753a91766xxxxxxxxxx';
let api_request = await fetch('https://app.sticky.de/?m=my_module', {
method: 'GET',
headers: {
"Content-Type": "application/json",
"Sticky-Token": token,
"Sticky-User": user,
"Sticky-Company": company
}
});
let response = await api_request.json();
console.log(json);
Rückgabewerte
Endpunkte geben ein JSON in folgendem Format zurück:
Beispielhafte OK-Rückgabe
{
"src":"server", // Bei Antworten ist die Quelle immer "Server"
"time":1656960905, // Serverseitiger Timestamp
"module":"vouchers", // Das angesprochene Modul
"method":"send_voucher", // Die angesprochene Methode
"msg":"ok", // Die Rückantwort bzw. Payload auf deine Anfrage
"id":"", // Sofern eine neue Ressource erzeugt wurde, wird deren ID zurückgegeben
}
Beispielhafte Rückgabe mit JSON Daten
{
"src":"server",
"time":1656960905,
"module":"articles",
"method":"get_all",
"msg": { // Die Rückantwort bzw. Payload auf deine Anfrage
[
{"id":1234, "title":"Datensatz Titel 1", ...},
{"id":1235, "title":"Datensatz Titel 2", ...},
]
},
"id":"",
}
Beispielhafte Fehler-Rückgabe
{
"src":"server",
"time":1656960905,
"module":"system",
"method":"access",
"msg":"ERROR_API_INVALID_USER", // Die Rückantwort bzw. Payload auf deine Anfrage
"id":"",
"error":1 // Existiert nur, sofern es sich um eine Fehler-Antwort handelt
}
Endpunkte Scope: Firma – Module
Hier findest du eine Aufstellung aller dokumentierten Endpunkte. Sollte dir etwas fehlen, gib uns einfach kurz bescheid oder sende uns eine E-Mail an support@sticky.de. Sicherlich existiert dein gesuchter Endpunkt bereits, jedoch hat er es bisher noch nicht in die Dokumentation geschafft ;-}
Artikel
Artikel erstellen
Parameter: m | string | articles
method | string | create_article
msg | object | Folgende Werte müssen enthalten sein:
- title | string | Artikelname
- description | string (optional) | Artikelbeschreibung
- type | string | Artikeltyp. Der Wert muss einer der folgenden sein: ['service', 'product']
- article_number | string (optional) | Artikelnummer. Muss eindeutig sein. Maximal 18 Zeichen.
- gtin | string (optional) | GTIN (Global Trade Item Number)
- note | string (optional) | Notiz
- unit_name | string | Name der Einheit. Wenn die Einheit noch nicht in Sticky vorhanden ist, wird sie automatisch erstellt.
- price_net | float | Nettopreis
- tax_rate | int | Steuersatz. Darf nur 0, 7 oder 19 sein
Beispiel Anfrage:
{
„m“:“articles“,
„method“:“create_article“,
„msg“: {
„title“:“Monitor“,
„description“: „1.920 x 1.080, 2 integrierte 5-W-Lautsprecher, 2 x HDMI“,
„type“: „product“,
„article_number“:“KV92347845″,
„note“: „neues Produkt“,
„unit_name“: „Stück“,
„price_net“: 634.34,
„tax_rate“: 19
}
}
Beispiel Antwort:
{
„src“:“server“,
„time“:1656968326,
„module“:“articles“,
„method“:“create_article“,
„msg“:“ok“,
„id“: „d04d8001-70bd-409e-aed9-00e87df4440f“
}
Mögliche Fehlercodes:
– „msg darf nicht leer sein“
– „Parameter title/type/unit_name/price_net/tax_rate muss existieren“
– „unknown article type“
– „unsupported tax rate“
– „gtin format is incorrect“
– „article_number maximum length is 18 chars“
– „Die Artikelnummer ******* existiert bereits in Lexware Office“
Belege
Rechnung per E-Mail versenden
Rechnungen (PDF-Dateien) werden (mit den in den Moduleinstellungen hinterlegten SMTP-Daten und Standardtexten) per E-Mail an die primäre E-Mail-Adresse des Kunden versendet.
Parameter:
m | string | vouchers
method | string | send_voucher
id | string | [Rechnungsnummer oder Sticky-Beleg-ID]
Beispiel Anfrage:
{
"m":"vouchers",
"method":"send_voucher",
"id":"RE0265"
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"vouchers",
"method":"send_voucher",
"msg":"ok",
"id":""
}Mögliche Fehlercodes:
– „Belegnummer darf nicht leer sein“
– „Beleg konnte nicht versendet werden. Beleg wurde nicht gefunden, oder wird noch synchronisiert“
– „<smtp error>“
Neue Rechnung anlegen
Neue Rechnung wird angelegt.
Parameter:
m | string | vouchers
method | string | create_invoice
msg | object | Folgende Werte müssen enthalten sein:
- date | string | Rechnungsdatum
- title | string | Belegtitel
- header | string | Einleitungstext
- footer | string | Fußzeile
- contact | string | [ID des Kontaktes]
- address | object (optional) | Adresse des Rechnungsempfängers. Wenn nicht ausgefüllt,
| wird die Kontaktadresse von Lexware Office verwendet
- supplement | string (optional) | Adresszusatz
- street | string | Straße (Straße und Hausnummer)
- zip | string | Postleitzahl
- city | string | Stadt
- delivery_type | string | Versandart. Der Wert muss einer der folgenden sein:
| ['service', 'delivery', 'serviceperiod', 'deliveryperiod', 'none']
- delivery_date | string | Versanddatum oder Beginn des Versandzeitraums.
| Erforderlich für Versandarten 'delivery', 'deliveryperiod', 'service' und 'serviceperiod'
- delivery_date_end | string | Ende des Versandzeitraums. Erforderlich für Versandarten 'deliveryperiod' und
| 'serviceperiod'. Muss später als delivery_date sein
- billing_label | string | Zahlungsbedingung
- billing_days | string | Fälligkeit in Tagen
- draft | bool (optional) | true, wenn die Rechnung als Entwurf gespeichert werden soll
| Default false
- language | string (optional) | Die Sprache der Rechnung, die sich auf das Druckdokument auswirkt.
| Der Wert muss einer der folgenden sein: ['en', 'de']. Default 'de'
- items | array of objects | Artikeldaten
- id | string (optional) | Sticky-Artikel-ID
- title | string | Name
- description | string (optional) | Beschreibung
- quantity | float | Betrag des gekauften Artikels
- unit | string | Name der Einheit
- price | float | Preis
- taxrate | float | Steuersatz des Preises je Maßeinheit
- discount | float | Angebotene Rabatt für den Artikel
oder Textposition
- title | string | Name des Artikels
- description | string | Beschreibung des Artikels
Beispiel Anfrage:
{
"m":"vouchers",
"method": "create_invoice",
"msg": {
"date":"31.01.2024",
"title":"Rechnung",
"header":"Unsere Lieferungen/Leistungen stellen wir Ihnen wie folgt in Rechnung.",
"footer":"Vielen Dank für die gute Zusammenarbeit",
"contact":"6560566ed737c363eb3ce4d2",
"address": {
"address_supplement":"2345",
"street":"Blumenstraße 43",
"zip":"77777",
"city":"Blumenstadt"
},
"delivery_type":"serviceperiod",
"delivery_date":"31.01.2024",
"delivery_date_end":"29.02.2024",
"billing_label":"SEPA Lastschrift",
"billing_days":"14",
"language":"en",
"items": [
{
"title":"Textposition",
"description":"Description"
},
{
"title":"Artikel 1",
"description":"Hochwertig",
"quantity":34,
"unit":"Stück",
"price":12,
"taxrate":19,
"discount":0
}
]
}
}
Beispiel Antwort:
{
"src":"server",
"time": 1706700087,
"module":"vouchers",
"method":"create_invoice",
"msg":"ok",
"id":"900365ec-25a7-467a-92a8-09d0ac57c0a5"
}Mögliche Fehlercodes:
– „id darf nicht leer sein“
– „id existiert nicht“
– „Rechnungsdatum (date) darf nicht leer sein“
– „Rechnungsdatum (date) hat ein ungültiges Format“
– „Zahlungsbedingung (billing_label) darf nicht leer sein“
– „Versandart (delivery_type) darf nicht leer sein“
– „Versandart (delivery_type) ist nicht korrekt“
– „Liefer- oder Leistungsdatum (delivery_date) darf nicht leer sein“
– „Liefer- oder Leistungsdatum (delivery_date) hat ein ungültiges Format“
– „Liefer- oder Leistungszeitraum (delivery_date oder delivery_date_end) hat ein ungültiges Format“
– „Ende des Leistungs- oder Lieferzeitraums (delivery_date_end) darf nicht leer sein“
– „Fälligkeit (billing_days) existiert nicht oder hat ein ungültiges Format“
– „Artikelliste (items) hat ein ungültiges Format“
– „Zeitraum (delivery_date_end < delivery_date) ist nicht korrekt“
– „Artikelpreis darf nicht leer sein“
– „Artikelname darf nicht leer sein“
– „Kontakt hat keine Adresse“
Neues Angebot anlegen
Neues Angebot wird erstellt.
Parameter:
m | string | vouchers
method | string | create_offer
msg | object | Folgende Werte müssen enthalten sein:
- title | string | Belegtitel
- header | string | Einleitungstext
- footer | string | Fußzeile
- contact | string | [ID des Kontaktes]
- address | object (optional) | Adresse des Angebotsempfängers. Wenn nicht ausgefüllt,
| wird die Kontaktadresse von Lexware Office verwendet
- supplement | string (optional) | Adresszusatz
- street | string | Die Straße (Straße und Hausnummer)
- zip | string | Postleitzahl
- city | string | Stadt
- billing_label | string | Zahlungsbedingungen
- billing_days | int | Fälligkeit in Tagen
- date | string | Angebotsdatum
- date_end | string | Datum, bis wann das Angebot gültig ist
- draft | bool (optional) | true, wenn das Angebot als Entwurf gespeichert werden soll
Default false
- items | array of objects | Artikeldaten
- id | string (optional)| Sticky-Artikel-ID
- title | string | Name
- description | string (optional)| Beschreibung
- quantity | float | Betrag
- unit | string | Name der Einheit
- price | float | Preis
- taxrate | float | Steuersatz des Preises je Maßeinheit
- discount | float | Angebotene Rabatt für den Artikel
oder Textposition
- title | string | Name des Artikels
- description | string | Beschreibung des Artikels
Beispiel Anfrage:
{
"m":"vouchers",
"method":"create_offer",
"msg": {
"title":"Angebot",
"header":"Gerne bieten wir Ihnen an:",
"footer":"Wir freuen uns auf Ihre Auftragserteilung und sichern eine einwandfreie Ausführung zu.",
"contact":"d5df1f7b-f0c6-4ee1-8f80-7c35ae901472",
"address": {
"address_supplement":"App. 56a",
"street":"Dorfstraße 12",
"zip":"11111",
"city":"Berlin"
},
"billing_label":"SEPA Lastschrift",
"billing_days":"14",
"date":"05.02.2024",
"date_end":"06.03.2024",
"items":[
{
"title":"Artikel 1",
"description":"Hochwertig",
"quantity":13,
"unit":"Stück",
"price":130.30,
"taxrate":19,
"discount":10
}
]
}
}
Beispiel Antwort:
{
"src":"server",
"time":1707123314,
"module":"vouchers",
"method":"create_offer",
"msg":"ok",
"id":"6c4f0bc6-0f04-462a-a6f1-ede6836461b4"
}Mögliche Fehlercodes:
– „id darf nicht leer sein“
– „id existiert nicht“
– „Startdatum des Angebotes (date) darf nicht leer sein“
– „Zahlungsbedingung (billing_label) darf nicht leer sein“
– „Enddatum des Angebotes (date_end) darf nicht leer sein“
– „Fälligkeit (billing_days) hat ein ungültiges Format“
– „Start- (date) oder Enddatum (date_end) des Angebotes hat ein ungültiges Format“
– „Artikelliste (items) hat ein ungültiges Format“
– „Artikelname darf nicht leer sein“
– „Artikelpreis darf nicht leer sein“
– „Kontakt hat keine Adresse“
Angebote annehmen/ablehnen
Der Status des Angebotes wird in „Angenommen“ bzw. „Abgelehnt“ geändert.
Parameter:
m | string | vouchers
method | string | update_offer_status
id | string | [ID des Angebotes]
msg | object | Folgender Wert muss enthalten sein:
- status | string | Neuer Status des Angebots. ('accepted', 'rejected')Beispiel Anfrage:
{
"m" : "vouchers",
"method" : "update_offer_status",
"id" : "729a135e-b3d1-44d6-84e9-0f823de927b6"
"msg" : {
"status" : "accepted"
}
}Beispiel Antwort:
{
"src": "server",
"time": 1718788070,
"module": "vouchers",
"method": "update_offer_status",
"msg": "ok",
"id": ""
}Mögliche Fehlercodes:
– „id darf nicht leer sein“
– „Das Feld ‚Status‘ muss ‚accepted‘ oder ‚rejected‘ enthalten“
– „Angebot konnte nicht gefunden werden“
– „Account in <Buchhaltungsmodul> Modul ist nicht verknüpft“
– „Status konnte nicht aktualisiert werden. (Login gescheitert)“
– „Angebotsstatus konnte nicht aktualisiert werden“
– „Modul <Buchhaltungsmodul> unterstützt kein update_offer_status“
ChatGPT Integration
Einfachen Promt absenden
In einem einfachen Promt kann man ein Frage/Aufgabe formulieren und erhält eine Antwort zurück.
So ein einfacher Prompt hat keinen Kontext. Wenn ein Kontext gesetzt werden soll, muss dieser als Payload im Promt mitgesendet werden.
m | string | chatGPT
method | string | promt
msg | string | Ein beliebiger String als Frage, Aufgabe, etc.
Beispiel Anfrage:
{
"m": "chatGPT",
"method": "promt",
"msg": "Wie groß ist der Umfang der Erde?"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"chatGPT",
"method":"promt",
"msg": "Der Umfang der Erde beträgt etwa 40.075 Kilometer.",
"id": "6805ea61b089972caa024800"
}
Dialog erzeugen und fortführen
Es können auch komplexere Dialoge, welche einen Kontext bekommen, erzeugt und auch weitergeführt werden.
m | string | chatGPT
method | string | dialog
msg | string | Ein beliebiger String als Frage, Aufgabe, etc.
id | string (optional) | Wenn vorhanden, eine ID eines Dialoges, welcher fortgeführt werden soll.
Wenn leer, wird ein neuer Dialog ohne Kontext erzeugt.
Beispiel Anfrage:
{
"m": "chatGPT",
"method": "dialog",
"msg": "Wie ist dein Name?",
"id": "" // Leere ID um neuen Kontext zu erzeugen
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"chatGPT",
"method":"dialog",
"msg": "Ich bin ein KI-gestützter virtueller Assistent und habe keinen eigenen Namen.",
"id": "680670cb182d5c36b7056be7" // Rücklieferung der neuen Dialog-ID
}
Beispiel Anfrage:
{
"m": "chatGPT",
"method": "dialog",
"msg": "Wie war meine vorige Frage?",
"id": "680670cb182d5c36b7056be7" // ID des Dialoges um Kontext zu nutzen
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"chatGPT",
"method":"dialog",
"msg": "Deine vorherige Frage an mich war: \"Wie ist dein Name?\"",
"id": "680670cb182d5c36b7056be7" // Rücklieferung der Dialog-ID
}
Dialog ausgeben
Einen Dialog mit allen Nachrichten laden
m | string | chatGPT
method | string | dialogLoadThread
id | string | ID des Dialoges
Beispiel Anfrage:
{
"m": "chatGPT",
"method": "dialogLoadThread",
"id": "680670cb182d5c36b7056be7"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"chatGPT",
"method":"dialogLoadThread",
"msg": {
"title": "Wie ist dein Name?",
"messages": [
{"role": "user", "content": "Wie ist dein Name?"},
{"role": "assistant", "content": "Ich bin ein KI-gestützter virtueller Assistent und habe keinen eigenen Namen."},
{"role": "user", "content": "Wie war meine vorige Frage"},
{"role": "assistant", "content": "Deine vorherige Frage an mich war: \"Wie ist dein Name?\""},
]
},
"id": "680670cb182d5c36b7056be7"
}
Dialog löschen
Einen Dialog allen Nachrichten löschen
m | string | chatGPT
method | string | dialogDeleteThread
id | string | ID des Dialoges
Beispiel Anfrage:
{
"m": "chatGPT",
"method": "dialogDeleteThread",
"id": "680670cb182d5c36b7056be7"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"chatGPT",
"method":"dialogDeleteThread",
"msg": "ok",
"id": "680670cb182d5c36b7056be7"
} Kontakte
Kontakt erstellen
Neue Firma wird erstellt.
m | string | contacts
method | string | create_contact
msg | object | Folgende Werte müssen enthalten sein:
- type | string | 'Kunde', 'Lieferant', 'Kunde & Lieferant'
- title | string | Firmenname
- tax_id | string (optional) | Steuernummer
- vat_id | string (optional) | Umsatzsteuer-ID
- street | string | Straße
- street_additional | string (optional) | Adresszusatz
- zip_code | string | Postleitzahl
- city | string | Stadt
- country | string | Land
- email | string (optional) | E-Mail-Adresse. Wenn dieses Feld fehlt oder leer ist, es aber eine Kontaktperson
| mit einer E-Mail-Adresse gibt, wird die E-Mail-Adresse der Kontaktperson als
| primäre Adresse festgelegt
- phone | string (optional) | Telefonnummer
- mobile | string (optional) | Handynummer
- note | string (optional) | Zusätzliche Information
- contact_person | object (optional) | Kann folgende Werte enthalten:
- salutation | string (optional) | Anrede
- firstname | string | Vorname
- lastname | string | Nachname
- email | string (optional) | E-Mail-Adresse
- phone | string (optional) | Telefonnummer
Beispiel Anfrage:
{
"m":"contacts",
"method":"create_contact",
"msg": {
"type":"Kunde & Lieferant",
"title":"First Firma GmBH",
"tax_id":"78549327754",
"vat_id":"DE999999999",
"street":"Blumenstraße 67",
"zip_code":"43584",
"city":"Blumenstadt",
"country":"Deutschland",
"email":"test@gmail.com",
"phone":"673434",
"mobile":"8735645",
"note":"Mitarbeiter",
"contact_person": {
"salutation":"Herr",
"firstname":"Dorian",
"lastname":"Gray",
"email":"dor@gmail.com",
"phone":"654788342"
},
}
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"contacts",
"method":"create_contact",
"msg":"ok",
"id": "ee7f5cb2-c5b1-4bcb-9985-c18bf66162b5"
}
Mögliche Fehlercodes:
– „Kontakt muss einer von 3 Typen sein: Kunde, Lieferant oder Kunde & Lieferant“
– „Adresse ist unvollständig“
– „Kontaktperson kann nicht ohne Vorname oder Nachname erstellt werden“
– „Firmenname kann nicht leer sein“
SEPA Mandat aktualisieren
Das SEPA Mandat eines Kunden wird hinterlegt/aktualisiert.
Parameter:
m | string | contacts
method | string | set_sepa_debit_data
id | string | [ID des Kontaktes]
msg | object | Folgende Werte müssen enthalten sein:
- source | string (optional) | Modulname der Kontaktquelle und Bezug von "id".
| Beispiel: Bei einem Lexware Office Kontakt wird der Modulname "lexoffice" als "source" verwendet.
| Wenn nicht angegeben, oder leer, wird die ID eines Sticky-Kontaktes erwartet.
- sepa_name | string | Name des Kontoinhabers
- sepa_iban | string | IBAN wird auf Gültigkeit geprüft
- sepa_bic | string (optional) | Wenn BIC nicht leer ist, wird sein Format geprüft
- sepa_id | string | Mandatsreferenz (Meist gleich der Kundenummer)
- sepa_date | string | Datum Unterschrift Kunde im Format dd.mm.yyy
- sepa_last_used | string | Datum letzte Nutzung für SEPA-Lastschrift dd.mm.yyy (leer, wenn noch nie benutzt)
- sepa_type | string | "SEPA Basis-Lastschrift", "SEPA Firmen-Lastschrift", "SEPA Mandat deaktiviert"
Beispiel Anfrage:
{
"m":"contacts",
"method":"set_sepa_debit_data",
"id":"40490b91-9016-45de-ba4a-a506285064a0",
"msg": {
"source":"lexoffice",
"sepa_name":"Baebeca Solutions GmbH",
"sepa_iban":"DE02120300000000202051",
"sepa_bic":"BYLADEM1001",
"sepa_id":"10005",
"sepa_date":"10.03.2021",
"sepa_last_used":"10.03.2021",
"sepa_type":"SEPA Basis-Lastschrift"
}
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"contacts",
"method":"set_sepa_debit_data",
"msg":"ok",
"id":""
}
Mögliche Fehlercodes:
- "<field> darf nicht leer sein"
- "<field> hat ein ungültiges Format"
- "<field> muss existieren"
- "Kontakt konnte nicht gefunden werden"Kundenummer aktualisieren
Die Kundenummer in der angeschlossenen Buchhaltungssoftware wird für einen Kontakt aktualisiert.
Einschränkungen, die beachtet werden müssen:
- Kundenummern müssen zu dem Nummernkreis im jeweiligen externen Buchhaltungstool passen
- Je nach Buchhaltungsmodul müssen gültige Login-Daten in den Moduleinstellungen hinterlegt sein
- Kundenummern können nur für unbebuchte Kontakte (also es darf keine Rechnung für den Kunden existieren) geändert werden
Parameter:
m | string | contacts
method | string | update_customer_number
id | string | [ID des Kontaktes]
msg | object | Folgende Werte müssen enthalten sein:
- source | string (optional) | Modulname der Kontaktquelle und Bezug von "id".
| Beispiel: Bei einem Lexware Office Kontakt wird der Modulname "lexoffice" als "source" verwendet.
| Wenn nicht angegeben, oder leer, wird die ID eines Sticky-Kontaktes erwartet.
- customer_number | string | Neue Kundenummer
Beispiel Anfrage:
{
"m":"contacts",
"method":"update_customer_number",
"id":"f8559d8b-52d1-4393-a101-f48f72a177a8",
"msg": {
"source":"lexoffice",
"customer_number":"30889"
}
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"contacts",
"method":"set_sepa_debit_data",
"msg":"ok",
"id":""
}Mögliche Fehlercodes:
– „<field> darf nicht leer sein“
– „<field> hat ein ungültiges Format“
– „Kontakt konnte nicht gefunden werden“
– „Account in <module> Modul ist nicht verknüpft“
– „Kundenummer konnte nicht aktualisiert werden. (<module> Login gescheitert)“
– „Kundenummer konnte nicht aktualisiert werden“
– „Modul <module> unterstützt kein update_customer_number“
Datenfeld(er) aktualisieren
Einzelne oder mehrere Datenfelder werden an einem Kontakt aktualisiert.
Es werden alle vordefinierten Felder eines Kontaktes unterstützt. Beispiele:
- Zahlungsbedingung | billing_time | string
- SEPA Lastschrift, Zahlbar / sofort, Zahlbar / 8 Tage, Zahlbar / 14 Tage, Zahlbar / 30 Tage, Vorkasse
- Beleg Postversand | postal_delivery | bool
Darüber hinaus werden auch alle via Datenstrukturen zusätzlich erzeugten Felder unterstützt. Selbst erzeugte Felder haben eine eindeutige ID als Feldname (Beispiel: 62cfbf6559d989666f237d72), welche in der UI am HTML Element ausgelesen werden kann.
Parameter:
m | string | contacts
method | string | set_fields
id | string | [ID des Kontaktes]
msg | object | Folgende Werte müssen enthalten sein:
- source | string (optional) | Modulname der Kontaktquelle und Bezug von "id".
| Beispiel: Bei einem Lexware Office Kontakt wird der Modulname "lexoffice" als "source" verwendet.
| Wenn nicht angegeben, oder leer, wird die ID eines Sticky-Kontaktes erwartet.
- fields | array | Array, bestehend aus Objekten der gewünschten Updates
- field | string | ID / Name des Feldes
- value | depending | Wert
Beispiel Anfrage (Zwei Standard Felder):
{
"m":"contacts",
"method":"set_fields",
"id":"f8559d8b-52d1-4393-a101-f48f72a177a8",
"msg": {
"source":"lexoffice",
"fields": [
{"field":"billing_time", "value":"Vorkasse"},
{"field":"postal_delivery", "value":true}
]
}
}
Beispiel Anfrage (Ein Custom Feld):
{
"m":"contacts",
"method":"set_fields",
"id":"f8559d8b-52d1-4393-a101-f48f72a177a8",
"msg": {
"source":"lexoffice",
"fields": [
{"field":"62cfbf6559d989666f237d72", "value":"Mein eigener Wert"}
]
}
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"contacts",
"method":"set_fields",
"msg":"ok",
"id":""
}Mögliche Fehlercodes:
– „<field> darf nicht leer sein“
– „<field> hat ein ungültiges Format“
– „Kontakt konnte nicht gefunden werden“
– „<field> existiert nicht in Datenstruktur“
– „<field> hat ein falsches Datenformat“
– „<field> unbekannter Feldtyp“
IONOS AI Integration
Einfachen Promt absenden
In einem einfachen Promt kann man ein Frage/Aufgabe formulieren und erhält eine Antwort zurück.
So ein einfacher Prompt hat keinen Kontext. Wenn ein Kontext gesetzt werden soll, muss dieser als Payload im Promt mitgesendet werden.
m | string | ionosAI
method | string | promt
msg | string | Ein beliebiger String als Frage, Aufgabe, etc.
Beispiel Anfrage:
{
"m": "ionosAI",
"method": "promt",
"msg": "Wie groß ist der Umfang der Erde?"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"ionosAI",
"method":"promt",
"msg": "Der Umfang der Erde beträgt etwa 40.075 Kilometer.",
"id": "6805ea61b089972caa024800"
}Dialog erzeugen und fortführen
Es können auch komplexere Dialoge, welche einen Kontext bekommen, erzeugt und auch weitergeführt werden.
m | string | ionosAI
method | string | dialog
msg | string | Ein beliebiger String als Frage, Aufgabe, etc.
id | string (optional) | Wenn vorhanden, eine ID eines Dialoges, welcher fortgeführt werden soll.
Wenn leer, wird ein neuer Dialog ohne Kontext erzeugt.
Beispiel Anfrage:
{
"m": "ionosAI",
"method": "dialog",
"msg": "Wie ist dein Name?",
"id": "" // Leere ID um neuen Kontext zu erzeugen
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"ionosAI",
"method":"dialog",
"msg": "Ich bin ein KI-gestützter virtueller Assistent und habe keinen eigenen Namen.",
"id": "680670cb182d5c36b7056be7" // Rücklieferung der neuen Dialog-ID
}
Beispiel Anfrage:
{
"m": "ionosAI",
"method": "dialog",
"msg": "Wie war meine vorige Frage?",
"id": "680670cb182d5c36b7056be7" // ID des Dialoges um Kontext zu nutzen
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"ionosAI",
"method":"dialog",
"msg": "Deine vorherige Frage an mich war: \"Wie ist dein Name?\"",
"id": "680670cb182d5c36b7056be7" // Rücklieferung der Dialog-ID
}
Dialog ausgeben
Einen Dialog mit allen Nachrichten laden
m | string | ionosAI
method | string | dialogLoadThread
id | string | ID des Dialoges
Beispiel Anfrage:
{
"m": "ionosAI",
"method": "dialogLoadThread",
"id": "680670cb182d5c36b7056be7"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"ionosAI",
"method":"dialogLoadThread",
"msg": {
"title": "Wie ist dein Name?",
"messages": [
{"role": "user", "content": "Wie ist dein Name?"},
{"role": "assistant", "content": "Ich bin ein KI-gestützter virtueller Assistent und habe keinen eigenen Namen."},
{"role": "user", "content": "Wie war meine vorige Frage"},
{"role": "assistant", "content": "Deine vorherige Frage an mich war: \"Wie ist dein Name?\""},
]
},
"id": "680670cb182d5c36b7056be7"
}Dialog löschen
Einen Dialog allen Nachrichten löschen
m | string | ionosAI
method | string | dialogDeleteThread
id | string | ID des Dialoges
Beispiel Anfrage:
{
"m": "ionosAI",
"method": "dialogDeleteThread",
"id": "680670cb182d5c36b7056be7"
}
Beispiel Antwort:
{
"src":"server",
"time":1709019163,
"module":"ionosAI",
"method":"dialogDeleteThread",
"msg": "ok",
"id": "680670cb182d5c36b7056be7"
} Datenstrukturen
Neuen Datensatz anlegen
Es wird ein neuer Datensatz in einer individuell angelegten Datenstruktur erzeugt.
Aktuelle Einschränkungen:
- Es können keine Multi-Tab-Einträge innerhalb eines Datensatzes erzeugt werden.
- Es werden die folgenden Feldtypen unterstützt: Text- Zahlenfeld, Textbox, Liste, Checkbox, Tags, Bild, Dateiupload .
Felder in Datenstrukturen haben jeweils eine eindeutige ID als Feldname (Beispiel: 62cfbf6559d989666f237d72), welche in der UI am HTML Element ausgelesen werden kann. Der nötige Parameter „c“ kann aus der URL entnommen werden, wenn man die Datenstruktur im UI öffnet.
Parameter: m | string | custom
c | string | [ID der Datenstruktur] method | string | add_item msg | object |
- title | string | [Anzeigename des Eintrages]
- Sticky-ID des Feldes | feldspezifisch: (optional) | Beliebige Werten aus der jeweiligen Datenstruktur
| Text-Zahlenfeld => string |
| Textbox => string |
| Liste => string | Elemente müssen durch ein Komma getrennt werden
| Tags => string | Elemente müssen durch ein Komma getrennt werden
| Checkbox => boolean |
| Dateiupload => array of objects | Jedes Objekt muss enthalten:
- file | string | Datei in einer im base64-Format kodierten string
- filename | string | Dateiname
- Sticky-ID/"image" | Bild => object | Muss folgende Werte enthalten:
- file | string | Datei in einer im base64-Format kodierten string
- filename | string | Dateiname
Beispiel Anfrage: {
"m":"custom",
"c":"64cf55bda39cd440a9663427",
"method":"add_item", "msg": { "title":"Mein Datensatz", // Textfeld "64cf5f2b5ccc66298129ef02":"20.10.2010", // Textfeld (Filter: Datum) "64cf5f5e986bd015d0528662":true, // Checkbox
"64cf5f5e986bd015d0528648":"Erdbeere,Apfel,Banane", // Tags
"6739bc79aec5290fd506c58e": "Morgen, Mittag, Abend" // Liste
"image": {
"file": "UEsDBBQABgAIAAAAIQDfpNJsWgEAACAFAAATAAgCW0NvbnRlbnRfVHlwZ....",
"filename": "test.png"
}, //Bild
"67ac4ff22f0e2c6fc707838b": [
{
"file": "UEsDBBQABgAIAAAAIQDfpNJsWgEAACAFAAATAAgCW0NvbnRlbnRfVHlwZ....",
"filename": "test.pdf"
}
] //Dateiupload
}
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"64cf55bda39cd440a9663427",
"method":"add_item",
"msg":"ok",
"id":"64cf69b8df3743757552ae83" // Die ID des erzeugten Datensatzes
}
Mögliche Fehlercodes:
- "id muss leer sein"
- "<field> darf nicht leer sein"
- "<field> existiert nicht in Datenstruktur"
- "<field> hat einen nicht unterstützen Feldtyp <typ>"
- "<field>: Datei kann nicht gespeichert werden"
- "<field>: nur 1 Datei ist erlaubt"
- "<field>:"file" und "filename" Keys sind nötig"
FP Sign
Signaturanfrage für Angebote absenden
Die Anfrage wird mit den Einstellungen aus der Modulkonfiguration generiert
Parameter:
m | string | fp_sign
method | string | form_sign_request
id | string | Sticky-Angebot-ID
Beispiel Anfrage:
{
"m":"fp_sign",
"method":"form_sign_request",
"id":"6752b49ac1df0c267c053e01"
}
Beispiel Antwort:
{
"src":"server",
"time":1733478143,
"module":"fp_sign",
"method":"form_sign_request",
"msg":"ok",
"id":"06.12.2024 10:44"
}
Mögliche Fehlercodes:
- "Authentifizierung fehlgeschlagen. Bitte prüfe deine FP Sign Zugangsdaten"
- "Autorisierung fehlgeschlagen. Bitte prüfe deine FP Sign Accounteinstellungen"
- "Anfrage fehlgeschlagen"
- "Anfrage fehlgeschlagen. Möglicherweise ist die Telefonnummer für SMSTan im Konto
des Empfängers nicht konfiguriert"
- "Invalid phone number: 01514398234735345. Erlaubte Formate: +491701234567, 00491701234567" Generische Endpunkte pro Modul
Diese Endpunkte stehen für alle Module zur Verfügung.
Konfiguration aktualisieren
Die Moduleinstellungen des jeweiligen Moduls können aktualisiert werden.
Eine Konfiguration in den Moduleinstellungen hat jeweils eine eindeutige ID als Feldname, welche in der UI am HTML Element ausgelesen werden kann.
Parameter: m | string | custom
method | string | set_config msg | object | [id => value]
Beispiel Anfrage: { "m":"vouchers",
"method":"set_config", "msg": { "CFG_AUTOSEND_INVOICE":true, "CFG_SEND_POSTAL_IF_NO_EMAIL":false, } } Beispiel Antwort: { "src":"server", "time":1656968326, "module":"vouchers", "method":"set_config", "msg":"ok", }
Mögliche Fehlercodes:
- "Fehlende Admin Berechtigungen"
- "msg darf nicht leer sein"
- "Unbekannte Konfiguration: <config-id>"
Benutzerkonfiguration aktualisieren
Die Moduleinstellungen des jeweiligen Benutzers (mit dem der API Login stattgefunden hat) können aktualisiert werden.
Eine Benutzerspezifische Moduleinstellungen hat jeweils eine eindeutige ID als Feldname, welche in der UI am HTML Element ausgelesen werden kann.
Parameter: m | string | custom
method | string | set_user_config msg | object | [id => value]
Beispiel Anfrage: { "m":"tasks",
"method":"set_user_config", "msg": { "CFG_USER_NOTIFY_TAGGING_SYSTEM":true, "CFG_USER_NOTIFY_TAGGING_EMAIL":false, } } Beispiel Antwort: { "src":"server", "time":1656968326, "module":"tasks", "method":"set_user_config", "msg":"ok", }
Mögliche Fehlercodes:
- "msg darf nicht leer sein"
- "Unbekannte Konfiguration: <config-id>"
Datensatz öffentlich Freigeben
Freigaben für Datensätze können erzeugt und widerrufen werden. Pro Datensatz kann eine eindeutige Sharing-URL generiert und abgerufen werden.
Parameter: m | string | [Slug des Moduls]
method | string | shareItem
id | string | [ID des Datensatzes]
msg | string | share, getURL, revoke
Beispiel Anfrage:
{
"m":"vouchers",
"method":"shareItem",
"msg": "share",
"id": "67aa50f520a4c96bb408b99c"
}
Beispiel Antwort:
{
"src":"server",
"time":1656968326,
"module":"vouchers",
"method":"shareItem",
"msg":"6739a4e1aec5290fd506c53d",
}
Mögliche Fehlercodes:
- invalid msg
- item is not shared Endpunkte Scope: Firma – Allgemein
Hier findest du eine Aufstellung aller dokumentierten Endpunkte. Sollte dir etwas fehlen, gib uns einfach kurz bescheid oder sende uns eine E-Mail an support@sticky.de. Sicherlich existiert dein gesuchter Endpunkt bereits, jedoch hat er es bisher noch nicht in die Dokumentation geschafft ;-}
Für diesen Scope muss der Benutzer immer über Administrationsrechte verfügen.
Logfiles
Logfiles auslesen
Parameter: m | string | system
method | string | get_logfiles msg | object |
- n | int | default 100 | max 1.000
- start | int | optional timestamp
- end | int | optional timestamp
Beispiel Anfrage: { "m":"system",
"method":"get_logfiles", "msg":{
"n":10,
"start":1692512495 } Beispiel Antwort: { "src":"server", "time":1656968326, "module":"system", "method":"get_logfiles", "msg":[
{
"id":"64e1b0f19950e038b711d8c3",
"pid":"0x3781a6",
"account_id":"5ef5d753a9f173334b767334",
"severity":"notice",
"created":1692512497,
"module":"vouchers",
"message:"Datei RE0001.jpg wird heruntergeladen"
},
{
"id":"64e1b0f146ed520b1f5b4c62",
"pid":"0xe01ec2",
"account_id":"5ef5d753a9f173334b767334",
"severity":"notice",
"created":1692512497,
"module":"vouchers",
"message":"Datei RE0004.jpg wird heruntergeladen"
}
] }
Endpunkte Scope: Benutzer
Hier findest du eine Aufstellung aller dokumentierten Endpunkte. Sollte dir etwas fehlen, gib uns einfach kurz bescheid oder sende uns eine E-Mail an support@sticky.de. Sicherlich existiert dein gesuchter Endpunkt bereits, jedoch hat er es bisher noch nicht in die Dokumentation geschafft ;-}
Zusätzliche Informationen
Namensänderung Lexware Office (ehemals lexoffice)
Das Produkt „lexoffice“ wurde zum 01.10.2024 zu „Lexware Office“ umbenannt. Sticky intern heißt die Anbindung weiterhin „lexoffice“. Das heißt in allen API Request ist als „source“ weiterhin der String „lexoffice“ zu verwenden, wenn als Quellangabe die Anbindung zu „Lexware Office“ genutzt werden soll.