Änderungsprotokoll

Alle Änderungen an der Klantly-API, die neuesten zuerst.

Innerhalb von Version 1 kommen nur Dinge hinzu. Eine Änderung, die bestehende Anbindungen beeinträchtigen kann, kommt erst in einer neuen Version und wird mit den Headern Deprecation und Sunset frühzeitig angekündigt.

14. Oktober 2026#

Neues Event: message.not_delivered. WhatsApp hat eine von dir oder vom Unternehmen gesendete Nachricht nicht zugestellt. Meta meldet das über seinen Status-Webhook, manchmal erst Minuten nach dem Senden — message.sent allein bedeutet also nicht, dass sie angekommen ist.

• Scope messages.read, wie message.received und message.sent. Die Payload ist die Nachricht selbst.
• Häufigste Gründe: Die Nummer kann kein WhatsApp empfangen, oder die letzte Nachricht des Kunden ist mehr als 24 Stunden her (dann kommt nur noch eine genehmigte Vorlage an).
• Endpunkte mit ["*"] erhalten das Event automatisch; bei einer festen Liste trägst du message.not_delivered selbst nach.

13. Oktober 2026#

Termine aus dem Google-Kalender. Ein Unternehmen kann seinen Google-Kalender jetzt in die andere Richtung laufen lassen: die Einträge der gewählten Google-Kalender erscheinen dann als Termin in Klantly.

• Jeder Termin trägt source: klantly (der Normalfall) oder google (aus dem Google-Kalender des Unternehmens abgerufen). Dieses Feld kommt in jeder Antwort mit einem Termin hinzu, daher ändert sich der ETag eines Termins einmalig — ein If-Match mit einem alten Wert gibt dann 412; rufen Sie den Termin erneut ab.
• Ein Termin mit source: "google" ist nur lesbar. PATCH, DELETE und die Aktionen confirm, cancel, complete und notify geben 409 mit dem Code conflict: daran wird in Google gearbeitet, dort gehört die Änderung hin. Lesen geht wie gewohnt, und für die Belegung des Kalenders zählt er mit.
• Solche Termine lösen keine Webhook-Events aus. Ein Unternehmenskalender kann hunderte Einträge enthalten; diese als appointment.created zu senden würde Ihren Endpunkt mit Arbeit überschwemmen, die nicht aus Klantly kommt.
• GET /availability zählt sie mit, denn es sind gewöhnliche Termine. War das Abrufen aus, ändert sich nichts.
• Verfügbarkeit: ein ganztägiger Termin blockiert jetzt den ganzen Tag. GET /v1/availability las die rohe Start- und Endzeit, und bei einem ganztägigen Termin stehen beide auf 00:00 des letzten Tages — das Zeitfenster war also leer und der Tag kam als völlig frei zurück. Dasselbe gilt jetzt für einen Termin über Mitternacht hinaus: er zählt an jedem Tag, den er berührt. Ihr Google-Kalender zählt hier weiterhin nicht mit; das bleibt die bewusste Ausnahme.

27. September 2026#

Servicemeldungen. Eine neue Ressource: die MELDUNG, die der Arbeit vorausgeht — eine Störung, ein Garantiefall, eine Reklamation oder eine Frage eines Kunden. Die ausgeführte Arbeit mit Stunden und Beträgen bleibt der Arbeitsauftrag; eine Meldung hat keine Positionen und landet nie auf einer Rechnung.

• GET|POST /v1/services, GET|PATCH|DELETE /v1/services/{id} und POST /v1/services/{id}/status (Entwurf → geplant → in Bearbeitung → abgeschlossen, dazu storniert).
• Fotos unter /v1/services/{id}/photos: GET, POST (multipart) und DELETE. Jedes Foto trägt eine kind: issue (die Meldung), progress, completion (das Ergebnis) oder other. Dieselben Grenzen wie bei den Arbeitsauftragsfotos: 10 MB pro Foto, 30 pro Meldung, und ein Downloadlink, der eine Viertelstunde gültig ist.
• Scopes services.read, services.write und services.delete; sie gehören zur Funktion Arbeitsaufträge, ein Schlüssel mit Arbeitsauftragsrechten kann sie also vergeben.
• Events service.created, service.updated, service.status_changed, service.completed, service.signed und service.deleted.
• Unterschreiben, das Planen des Termins und das Umwandeln in einen Arbeitsauftrag laufen bewusst nicht über die API: das sind Handlungen eines Menschen vor Ort. Einen Termin verknüpfen Sie selbst mit appointment_id.

20. September 2026#

Sortieren.

• sort akzeptiert bei Deals, Terminen, Unterhaltungen und Bewertungen nur noch created_at und updated_at (mit oder ohne Minuszeichen). stage_changed_at, starts_at, last_message_at und reviewed_at sind entfallen: Diese Spalten können leer sein, und dann übersprang der Cursor den Rest der Liste — Zeilen ohne Wert waren nicht erreichbar. Ein entfallener Wert ergibt jetzt 422.
• Die Standardsortierung von Unterhaltungen und Bewertungen ist dadurch -created_at geworden (war -last_message_at beziehungsweise -reviewed_at).
• Für die Reihenfolge des Kalenders verwenden Sie filter[starts_from] und filter[starts_until] und sortieren selbst.

Idempotenz.

• Ein Idempotency-Key gilt ab jetzt pro Unternehmen statt pro Schlüssel. So behält ein erneuter Versuch seine Garantie, wenn Ihre Integration während der Schlüsselerneuerung auf das neue Token wechselt. Verwenden zwei Integrationen desselben Unternehmens denselben Wert für eine andere Anfrage, erhält die zweite 422 idempotency_key_reused; geben Sie jeder Integration ein eigenes Präfix.
• Eine 404 oder 422 wird nicht mehr 24 Stunden gespeichert: Derselbe Schlüssel mit einem korrigierten Body führt die Anfrage einfach aus.

18. September 2026#

Sicherheit.

• Ein Webhook-Endpunkt kann nicht mehr auf eine interne Adresse zeigen, die als IPv4-in-IPv6 verpackt ist (etwa [::ffff:7f00:1] für 127.0.0.1). Solche Adressen werden nun genauso abgelehnt wie ihre normale Form.

Gutschriften.

• Eine versendete oder bezahlte Rechnung mit POST /invoices/{id}/credit gutschreiben: vollständig, eine Menge pro Position oder einen freien Betrag inklusive MwSt. Die Antwort ist die Gutschrift.
• Gutschriften stehen in GET /invoices neben den Rechnungen, mit dem neuen Feld type (invoice oder credit_note) und negativen Beträgen. Ohne Filter kommen beide; mit filter[type] wählen Sie eine Art.
• Neue Felder an einer Rechnung: type, credited_amount, credit_note_ids, credited_invoice_id, credited_invoice_number, credit_reason, refund_amount, refunded_at und credit_note_state; an einer Position credited_item_id. Neuer Status credited (vollständig gutgeschrieben).
• Die Erstattung einer Gutschrift mit POST /invoices/{id}/refunded erfassen.
• Erstattung über Mollie mit via: mollie bei POST /invoices/{id}/refunded, wenn die Rechnung über Mollie bezahlt wurde.
• Neues Event invoice.credited. Die Gutschrift selbst kommt als invoice.created mit type credit_note.
• Eine (teilweise) gutgeschriebene Rechnung kann nicht mehr storniert werden, und an einer Gutschrift können Sie keine Zahlung erfassen (409). Das Senden ändert den Status einer Gutschrift oder gutgeschriebenen Rechnung nicht.
• Die Anleitung Rechnungen in Ihre Buchhaltung erklärt, wie Sie Gutschriften buchen.

17. September 2026#

Posteingang, Bewertungen und Anhänge.

• Posteingang: Unterhaltungen und Nachrichten lesen, im Namen des Unternehmens über Chat-Widget, WhatsApp oder E-Mail antworten und eine Unterhaltung schließen. Antworten setzt die Funktion des jeweiligen Kanals voraus.
• Bewertungen: Bewertungen und Bewertungsanfragen abrufen und einen Kunden mit POST /review-requests um eine Bewertung bitten. Eine Bewertung selbst anzulegen ist bewusst nicht möglich — sie soll vom Kunden kommen.
• Anhänge zu einem Angebot und Fotos zu einem Arbeitsauftrag: abrufen, hochladen und löschen. Das Hochladen läuft als multipart/form-data im Feld file; der Download über einen signierten Link, der fünfzehn Minuten gültig ist und keinen API-Schlüssel braucht.
• Neue Scopes: messages.read, messages.send, reviews.read und reviews.write.
• Neue Events für Posteingang und Bewertungen, etwa message.received, conversation.closed und review.received.

Vertrieb und Finanzen.

• Angebote: abrufen, erstellen, bearbeiten (nur Entwürfe), versenden, annehmen, ablehnen und löschen, und das PDF mit GET /quotes/{id}/pdf abrufen.
• Rechnungen: abrufen, erstellen, bearbeiten (nur Entwürfe), versenden, stornieren, Zahlungen erfassen und löschen, und das PDF mit GET /invoices/{id}/pdf abrufen.
• Die Zahlungsseite für den Kunden mit GET /invoices/{id}/payment-link abrufen (Scope invoices.send, Funktion Online-Zahlungen).
• Ein angenommenes Angebot mit POST /quotes/{id}/invoice in einen Rechnungsentwurf umwandeln. Ein Angebot hat höchstens eine Rechnung: Eine zweite Anfrage, auch über POST /invoices mit quote_id, liefert 409 conflict mit der ID der vorhandenen Rechnung in invoice_id.
• Angebots- und Rechnungspositionen kennen unit_price_incl: einen Bruttopreis, der auf den Cent genau stimmt.
• Webshop-Bestellungen: abrufen, den Status ändern, die Sendungsverfolgung weitergeben und Notizen hinzufügen.
• Events für Angebote, Rechnungen und Bestellungen, zum Beispiel quote.accepted, invoice.paid und order.status_changed.
• Neue Scopes: quotes.read, quotes.write, quotes.delete, quotes.send, invoices.read, invoices.write, invoices.delete, invoices.send, orders.read und orders.write.
• Neue Anleitung: Rechnungen in Ihre Buchhaltung.

15. September 2026#

Sicherheit.

• Einen Webhook-Endpunkt ändern, ausschalten, löschen oder das Secret erneuern erfordert einen Schlüssel, der alles lesen kann, was der Endpunkt erhält (sonst 403 insufficient_scope).
• Webhooks können nicht mehr auf Klantly selbst zeigen, auch nicht über eine IP-Adresse oder einen eigenen Domainnamen, und nicht auf IPv6-Formen interner Adressen.
• Ein Body, der kein gültiges JSON-Objekt ist, ergibt 400 bad_request (er wurde als leerer Body gelesen).
• Zeiten außerhalb von 1970–2100 und Daten, die es nicht gibt, etwa der 31. Februar, ergeben 422.
• POST /webhook-endpoints/{id}/test und POST /appointments/{id}/notify fallen unter das Limit für aufwendige Aktionen.
• Antworten der API haben Cache-Control: no-store.
• Administratoren erhalten eine Sicherheits-E-Mail, wenn ein API-Schlüssel widerrufen wird, Berechtigungen hinzubekommt oder eine andere IP-Beschränkung, und wenn ein Webhook-Endpunkt erstellt wird, eine andere Adresse oder ein neues Secret erhält.
• Eine IP-Beschränkung muss mindestens /8 (IPv4) oder /32 (IPv6) sein.

Verbesserungen nach einem Review.

• Ein über die API eingerichteter Webhook-Endpunkt folgt dem Schlüssel, der ihn eingerichtet hat: Widerrufen Sie ihn oder entfernen Sie einen Lese-Scope, erhält der Endpunkt diese Events nicht mehr. Eine andere URL oder ein neues Secret erfordert einen Schlüssel, der alles lesen kann, was der Endpunkt erhält (sonst 403 insufficient_scope).
• Eine wiederholte oder erneut gesendete Zustellung prüft erneut, ob das Event noch erlaubt ist.
• Eine Webhook-URL mit einem Punkt am Ende oder mit Zeichen außerhalb von ASCII wird abgelehnt; verwenden Sie die xn--Form.
• Cursor sind verschlüsselt: Verwenden Sie sie so, wie Sie sie erhalten.
• Eine wiederholte Antwort (derselbe Idempotency-Key) beim Erstellen oder Erneuern eines Webhook-Endpunkts enthält das Secret nicht mehr.
• Positionen von Arbeitsaufträgen haben das Feld discount_amount (ein fester Rabatt); ein zu hoher Betrag ergibt 422 statt eines Serverfehlers. PATCH /work-orders/{id} mit nur items ergibt jetzt auch work_order.updated.
• PATCH /tasks/{id} mit links behält Verknüpfungen, die die API nicht zeigt, und eine Änderung erscheint im Verlauf der Aufgabe.
• POST /appointments/{id}/notify ergibt 409, wenn das Unternehmen die Vorlage ausgeschaltet hat. Ein als bestätigt erstellter Termin hat confirmed_at.

Termine, Aufgaben und Arbeitsaufträge.

• Termine: auflisten, abrufen, planen, bearbeiten, bestätigen, absagen, abschließen und löschen sowie dem Kunden eine Bestätigung, Verschiebung, Absage oder Erinnerung per E-Mail senden.
• Bei POST /appointments ist title nicht mehr erforderlich, wenn Sie eine appointment_type_id mitgeben: Der Titel wird dann der Name der Terminart. Ohne beides folgt 422.
• Terminarten und freie Zeitfenster auflisten.
• Aufgaben: auflisten, abrufen, erstellen, mit Kunden und anderen Datensätzen verknüpfen, verschieben, abschließen, wieder öffnen, abbrechen und löschen, dazu Kommentare und Aufgabenboards.
• Arbeitsaufträge: auflisten, abrufen, mit Positionen und Checkliste erstellen, bearbeiten, den Status ändern und löschen.
• Events für Termine, Aufgaben und Arbeitsaufträge, etwa appointment.created, task.moved und work_order.completed.
• Neue Scopes: appointments.read, appointments.write, appointments.delete, appointments.send, tasks.read, tasks.write, tasks.delete, work_orders.read, work_orders.write und work_orders.delete.
• Neue Leitfäden: Termine aus Ihrer eigenen Planung und Arbeitsaufträge aus Ihrem ERP.

Webhooks, Deals und mehr.

• Webhooks nach Standard Webhooks: Endpunkte in Klantly und über die API verwalten, mit Signatur, neuen Versuchen, einem Zustellprotokoll und einer Testnachricht. Lesen Sie den Leitfaden Webhooks.
• Events: GET /events, um verpasste Webhooks nachzuholen.
• Deals: auflisten, abrufen, erstellen, bearbeiten, verschieben, gewinnen, verlieren und archivieren, und die Pipeline-Phasen auflisten.
• Notizen zu Kunden und Deals.
• Die Zeitleiste eines Kunden.
• Benutzer und Unternehmensdaten abrufen.
• Neue Scopes: deals.read, deals.write, users.read, company.read, webhooks.manage und events.read.
• Neue Leitfäden: Website-Formular zum Lead und Make und n8n.

14. September 2026#

Erste Version der Klantly-API.

• Authentifizierung mit API-Schlüsseln, mit Scopes, Ablaufdatum, IP-Allowlist und Erneuern.
• GET /me zum Testen Ihrer Verbindung.
• Kunden: auflisten, abrufen, erstellen, bearbeiten und einen Lead in einen Kunden umwandeln.
• Cursor-Paginierung, Filter, Idempotency-Key und If-Match.
• Fehlermeldungen nach RFC 9457, in vier Sprachen.
• OpenAPI-3.1-Spezifikation in vier Sprachen.

Zuletzt aktualisiert am 14. Oktober 2026