> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zapier

> HocDoc mit Zapier verbinden: Ereignisse per Webhook empfangen und Angebote per API-Key lesen, anlegen, versenden und zurückziehen.

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.

> [!NOTE]
>
> Nur Inhaber und Admins legen Webhooks und API-Keys an. Mehr dazu unter [Einstellungen](https://docs.hocdoc.com/guides/einstellungen.md) und [Team und Rollen](https://docs.hocdoc.com/guides/team-und-rollen.md). Brauchst du nur Nachrichten in Slack oder Teams, geht das ohne Zapier: [Benachrichtigungen und Verbindungen](https://docs.hocdoc.com/guides/benachrichtigungen.md).

## 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](https://docs.hocdoc.com/api/webhooks.md#events).

**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](https://docs.hocdoc.com/api/webhooks.md#body). 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.

| Ziel | Aktion in Zapier | Felder zuordnen |
| - | - | - |
| Zeile in Google Sheets | **Google Sheets**, Event **Create Spreadsheet Row** | `data.offer.title`, `data.offer.recipient.company`, `data.offer.recipient.email`, `data.offer.accepted_at`, `data.offer.value.amount` |
| Slack-Nachricht | **Slack**, Event **Send Channel Message** | Text mit `data.offer.title` und `data.offer.accepted_by.name` |
| Deal im CRM | Aktion deines CRM, zum Beispiel **HubSpot** oder **Pipedrive** | Name aus `data.offer.title`, Kontakt aus `data.offer.recipient` |

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**).

> [!WARNING]
>
> 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](https://www.standardwebhooks.com/) 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](https://docs.hocdoc.com/api/webhooks.md#verify-the-signature).

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](https://docs.hocdoc.com/api/webhooks.md#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](https://docs.hocdoc.com/api/authentication.md).

**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

| Ziel | Aufruf |
| - | - |
| Key prüfen | `GET https://app.hocdoc.com/api/v1/workspace` |
| Liste der Angebote | `GET https://app.hocdoc.com/api/v1/offers` (optional `status` und `limit`, bis 100) |
| Ein Angebot | `GET https://app.hocdoc.com/api/v1/offers/{id}` |
| Zeitleiste eines Angebots | `GET https://app.hocdoc.com/api/v1/offers/{id}/events` |

Antworten kommen als `{ "data": ... }`. Bei Listen zeigt `next_cursor` auf die nächste Seite ([Pagination](https://docs.hocdoc.com/api/pagination.md)).

### 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:

```json theme={null}
{
  "template_id": "<ID einer Vorlage deines Workspace>",
  "recipient": {
    "name": "Vera Kundin",
    "email": "vera@kunde.example",
    "company": "Kunde GmbH"
  },
  "title": "Website-Relaunch",
  "language": "de",
  "variables": { "company": "Kunde GmbH" }
}
```

`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`.

> [!NOTE]
>
> 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](https://docs.hocdoc.com/api/rate-limits.md)). Der Header `Idempotency-Key` verhindert, dass ein wiederholter Aufruf ein Angebot doppelt anlegt.

Alle Felder, Antworten und Fehler stehen in der [API-Referenz](https://docs.hocdoc.com/api/introduction.md).

## Quellen für die Menünamen

Die Namen in Zapier stammen aus der Hilfe von Zapier: [Trigger Zap workflows from webhooks](https://help.zapier.com/hc/en-us/articles/8496288690317-Trigger-Zaps-from-webhooks) und [Send webhooks in Zap workflows](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows). Zapier ändert seine Oberfläche gelegentlich. Weichen Namen ab, gilt die Hilfe von Zapier.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.