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

# Make

> HocDoc mit Make verbinden: Ereignisse per Custom webhook empfangen und Angebote per API-Key mit dem Modul „Make a request“ lesen, anlegen, versenden und zurückziehen.

Du kannst HocDoc heute schon mit Make verbinden, ohne eigene App. Es gibt zwei Richtungen:

* **HocDoc → Make:** Ein Webhook von HocDoc startet ein Szenario, zum Beispiel wenn ein Angebot angenommen wird.
* **Make → HocDoc:** Ein Szenario ruft die API von HocDoc mit einem API-Key auf.

Die Namen in Make 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).

## HocDoc → Make: ein Szenario startet bei einem Ereignis

**1. Webhook in Make anlegen**

Lege ein neues Szenario an und füge als erstes Modul die App **Webhooks** hinzu. Wähle den Trigger **Custom webhook**. Wähle **Add**, vergib einen Namen wie „HocDoc“ und speichere. Make zeigt die Webhook-Adresse. Kopiere sie.

**2. Szenario warten lassen**

Starte das Szenario mit **Run once**. Make wartet jetzt auf eine Anfrage und merkt sich ihren Aufbau.

**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 Make-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`. Make kennt nun die Datenstruktur des Ereignisses.

**5. Struktur mit einem echten Ereignis bestimmen**

Ein `ping` hat keine Angebotsdaten (`data` ist leer). Bestimme die Datenstruktur deshalb mit einem echten Ereignis: Setze das Modul zurück (in den Einstellungen des Moduls gibt es die Option, die Datenstruktur neu zu bestimmen), starte das Szenario wieder mit **Run once** und löse zum Beispiel durch die Annahme eines Testangebots ein Ereignis aus. Danach stehen Felder wie `data.offer.title` oder `data.offer.recipient.email` in den folgenden Modulen zur Verfügung.

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-Szenario: Angebot angenommen

1. **Webhooks > Custom webhook** als Trigger.
2. Ein **Filter** zwischen den Modulen: `type` gleich `offer.accepted`. Das brauchst du, wenn der Endpunkt mehrere Ereignisse bekommt.
3. Ein Modul als Ziel, zum Beispiel **Google Sheets** mit einer neuen Zeile (Titel, Firma, E-Mail, Annahmezeit, Betrag), **Slack** mit einer Nachricht oder dein CRM mit einem Deal.
4. Rechne den Betrag für Anzeigezwecke mit einer Formel durch 100, zum Beispiel `{{data.offer.value.amount}} / 100`.

Die Module und Felder in diesen Apps legt Make fest.

### 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`. Das Modul **Custom webhook** prüft diese Signatur nicht von selbst. Eine Prüfung im Szenario beschreibt diese Anleitung nicht. Das Verfahren 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 und poste sie nicht in Tickets oder Chats. Bei Verdacht legst du in Make einen neuen Webhook an, trägst dessen Adresse im Endpunkt ein und löschst den alten.

### Gut zu wissen

* Make antwortet standardmäßig mit `200`, wenn die Anfrage angenommen wurde. HocDoc braucht innerhalb von 10 Sekunden ein `2xx`. 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)).
* Ein Webhook, der länger als 5 Tage mit keinem Szenario verbunden ist, wird von Make deaktiviert und antwortet mit `410`. Nach 5 endgültig gescheiterten Zustellungen in Folge pausiert HocDoc den Endpunkt. Setze ihn in der Karte **Webhooks** fort.
* 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**.

## Make → HocDoc: Angebote per API

Hier ruft ein Szenario die HocDoc-API mit dem Modul **HTTP > Make a request** auf.

**1. API-Key anlegen**

Öffne **Einstellungen**, Reiter **Integrationen**, Karte **API-Keys**, **Create API key**. Vergib einen Namen wie „Make“. Wähle **Read only**, wenn das Szenario nur liest, und **Read and write**, wenn es 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. Modul hinzufügen**

Füge die App **HTTP** hinzu und wähle die Aktion **Make a request**.

**3. URL, Methode 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`, und wähle die **Method**. Unter **Headers** fügst du den Header `Authorization` mit dem Wert `Bearer hd_live_...` hinzu (dein Key).

**4. Antwort auslesen**

Schalte **Parse response** ein. Dann stehen die Felder der JSON-Antwort in den nächsten Modulen bereit. Die Daten der Antwort liegen unter `data`.

Der Key gehört in den Header, nie in die Adresse oder den Body. Bei `401` ist der Key falsch, widerrufen oder abgelaufen. Bei `403` hat der Key nur Leserecht. In den **Advanced settings** des Moduls steht **Return error if HTTP request fails**: Schalte es ein, wenn das Szenario bei einem Fehler der API stoppen oder in die Fehlerbehandlung laufen soll.

### 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 Szenario ein Angebot aus einer Vorlage an. Wähle die Methode `POST`, die URL `https://app.hocdoc.com/api/v1/offers`, den Header `Authorization` wie oben, als **Body content type** `application/json` und gib dieses JSON als Body:

```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 nutzt ein zweites Modul `POST https://app.hocdoc.com/api/v1/offers/{id}/send` mit der `id` aus dem vorigen Modul. 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]
>
> Setzt du Felder aus früheren Modulen in den JSON-Body, achte auf Anführungszeichen und Zeilenumbrüche in den Werten. Sie machen das JSON ungültig. 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 Make stammen aus der Hilfe von Make: [Webhooks](https://help.make.com/webhooks) und [HTTP](https://apps.make.com/http). Make ändert seine Oberfläche gelegentlich. Weichen Namen ab, gilt die Hilfe von Make.


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