Zum Hauptinhalt springen
Du kannst HocDoc heute schon mit Zapier verbinden, ohne eigene App. Es gibt zwei Richtungen:
  • HocDoc → Zapier: Ein Webhook von HocDoc startet einen Zap, zum Beispiel wenn ein Angebot angenommen wird.
  • Zapier → HocDoc: Ein Zap ruft die API von HocDoc mit einem API-Key auf, um Angebote zu lesen, anzulegen, zu versenden oder zurückzuziehen.
Beide Wege nutzen die App Webhooks by Zapier. Die Namen in Zapier sind englisch.
Nur Inhaber und Admins legen Webhooks und API-Keys an. Mehr dazu unter Einstellungen und Team und Rollen. Brauchst du nur Nachrichten in Slack oder Teams, geht das ohne Zapier: Benachrichtigungen und Verbindungen.

HocDoc → Zapier: ein Zap startet bei einem Ereignis

1

Trigger in Zapier anlegen

Lege einen neuen Zap an. Wähle als Trigger die App Webhooks by Zapier und als Event Catch Hook. Wähle Continue. Pick Off A Child Key lässt du leer.
2

Webhook-Adresse kopieren

Im Tab Test zeigt Zapier die Webhook-Adresse. Kopiere sie.
3

Endpunkt in HocDoc anlegen

Öffne in HocDoc Einstellungen, dann den Reiter Integrationen. In der Karte Webhooks wählst du Endpunkt hinzufügen. Füge die Zapier-Adresse ein und wähle die Ereignisse, zum Beispiel offer.accepted. Die Ereignisse stehen in der Webhook-Doku.
4

Testereignis senden

Wähle in der Zeile des Endpunkts Test senden. HocDoc schickt ein Ereignis vom Typ ping. Gehe in Zapier zurück in den Tab Test und wähle Test trigger. Zapier zeigt die Felder des Ereignisses.
5

Mit echten Daten testen

Ein ping hat keine Angebotsdaten (data ist leer). Löse darum ein echtes Ereignis aus, zum Beispiel indem du ein Testangebot annimmst, und wähle in Zapier noch einmal Test trigger. Dann findest du Felder wie data.offer.title oder data.offer.recipient.email für die nächsten Schritte.
Der Webhook hat ein festes Format: id, type, created_at, api_version und data mit offer und event. Alle Felder stehen in der Webhook-Doku. Beträge sind ganze Zahlen in der kleinsten Währungseinheit: 1250000 mit EUR sind 12.500,00 Euro.

Beispiel: Angebot angenommen

Der Zap hat zwei Schritte: Webhooks by Zapier (Catch Hook) als Trigger, danach eine Aktion. Filtere im Zap auf type gleich offer.accepted, wenn der Endpunkt mehrere Ereignisse bekommt. Die genauen Namen der Events und Felder in diesen Apps legt Zapier fest. Wenn dein CRM eine eigene Verbindung in HocDoc hat, brauchst du Zapier dafür nicht (Reiter Integrationen, Karte Verbindungen).
Zapier nimmt den Betrag als Zahl. value.amount ist in der kleinsten Einheit (Cent). Teile ihn in einem Schritt Formatter by Zapier durch 100, wenn du Euro brauchst.

Sicherheit: Signatur und Adresse

HocDoc signiert jede Anfrage nach Standard Webhooks mit den Headern webhook-id, webhook-timestamp und webhook-signature. Der Trigger Catch Hook von Zapier ist dafür nicht gedacht. Er prüft die Signatur nicht. Zapier bietet daneben Catch Raw Hook an, das unverarbeitete Daten und Header liefert. Eine Prüfung der Signatur in einem eigenen Code-Schritt beschreibt diese Anleitung nicht. Das Prüfverfahren steht in der Webhook-Doku. Ohne Prüfung ist die Adresse dein Schutz: Sie ist lang und nicht zu erraten. Behandle sie wie ein Passwort. Gib sie nicht weiter, poste sie nicht in Tickets oder Chats und lege bei Verdacht einen neuen Trigger an, trage dessen Adresse im Endpunkt ein und lösche den alten Zap.

Gut zu wissen

  • Zapier muss innerhalb von 10 Sekunden mit einem 2xx antworten. Schlägt eine Zustellung fehl, versucht HocDoc es bis zu 8 Mal in etwa einem Tag (Retries).
  • Nach 5 endgültig gescheiterten Zustellungen in Folge pausiert HocDoc den Endpunkt. Setze ihn in der Karte Webhooks fort. Ereignisse während der Pause kommen nicht nach.
  • Ereignisse können doppelt oder in anderer Reihenfolge kommen. Nutze id des Ereignisses, um Doppelte zu erkennen.
  • Den Verlauf siehst du in der Karte Zustell-Log.

Zapier → HocDoc: Angebote per API

Hier ruft ein Zap die HocDoc-API auf. Du brauchst einen API-Key.
1

API-Key anlegen

Öffne Einstellungen, Reiter Integrationen, Karte API-Keys, Create API key. Vergib einen Namen wie „Zapier“. Wähle Read only, wenn der Zap nur liest, und Read and write, wenn er Angebote anlegt, versendet oder zurückzieht. Kopiere den Key. Er wird nur einmal angezeigt. Mehr dazu: Authentication.
2

Aktion in Zapier wählen

Füge als Aktion Webhooks by Zapier hinzu. Als Event wählst du GET zum Lesen oder Custom Request für Aufrufe mit JSON-Body.
3

URL und Header eintragen

Die Basis-URL ist https://app.hocdoc.com/api/v1. Trage in URL die vollständige Adresse ein, zum Beispiel https://app.hocdoc.com/api/v1/offers. Im Abschnitt Headers legst du den Header Authorization mit dem Wert Bearer hd_live_... an (dein Key).
4

Testen

Teste den Schritt. Bei Erfolg zeigt Zapier die Antwort. Bei 401 ist der Key falsch, widerrufen oder abgelaufen. Bei 403 hat der Key nur Leserecht.
Der Key gehört in den Header, nie in die Adresse oder den Body. Die API liest ihn nur aus dem Header Authorization.

Angebote lesen

Antworten kommen als { "data": ... }. Bei Listen zeigt next_cursor auf die nächste Seite (Pagination).

Angebot anlegen und versenden

Mit einem Key Read and write legt ein Zap ein Angebot aus einer Vorlage an. Wähle Custom Request, Methode POST, URL https://app.hocdoc.com/api/v1/offers, den Header Authorization wie oben und den Header Content-Type mit dem Wert application/json. Ins Feld Data kommt das JSON:
template_id und recipient mit name und email sind Pflicht. Alles andere ist optional. Mit variables beantwortest du die Fragen der Vorlage über den Variablennamen. Die Antwort enthält das Angebot als Entwurf mit seiner id. Zum Versenden ruft ein zweiter Schritt POST https://app.hocdoc.com/api/v1/offers/{id}/send auf, mit der id aus dem vorigen Schritt. Der Body darf leer sein, mit expires_on (YYYY-MM-DD) setzt du den letzten Annahmetag. Ohne Angabe sind es 14 Tage. Zurückziehen geht mit POST https://app.hocdoc.com/api/v1/offers/{id}/withdraw. Der Key handelt als die Person, die ihn angelegt hat. Rolle, Freigaben und Tarif gelten wie in der App. Verlangt der Workspace eine Freigabe, versendet die API nicht und antwortet mit 409 und approval_required.
Zapier gibt Felder aus früheren Schritten als Text in den Body. Ein Wert mit Anführungszeichen oder Zeilenumbruch macht das JSON ungültig. Die API antwortet dann mit einem Fehler. Die Schreibaufrufe sind auf 30 pro Minute je Key begrenzt (Rate limits). Der Header Idempotency-Key verhindert, dass ein wiederholter Aufruf ein Angebot doppelt anlegt.
Alle Felder, Antworten und Fehler stehen in der API-Referenz.

Quellen für die Menünamen

Die Namen in Zapier stammen aus der Hilfe von Zapier: Trigger Zap workflows from webhooks und Send webhooks in Zap workflows. Zapier ändert seine Oberfläche gelegentlich. Weichen Namen ab, gilt die Hilfe von Zapier.