API-Integrationsbeispiele

Das sind Rezepte für dieselbe Handvoll Probleme, auf die die meisten Integrationen stoßen, gebaut auf den echten Request- und Response-Formen aus der API-Einführung. Passe Endpunkt, Felder und Scopes an die Ressource an, mit der du arbeitest – die Muster selbst (nicht die exakten Payloads) sind es, was sich wiederzuverwenden lohnt.

Den API-Key vom Client fernhalten

Rufe die API niemals direkt aus Browser- oder Mobile-Code auf – das legt deinen Key gegenüber jedem offen, der die Entwicklertools öffnet. Setze stattdessen einen schlanken Proxy davor: Dein Frontend ruft dein eigenes Backend auf, und nur dein Backend kennt den Famulor-Key.

// server.js — Express route the frontend can safely call
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/trigger-call", async (req, res) => {
  const { to_number, assistant_id, lead } = req.body;
  if (!to_number || !assistant_id) {
    return res.status(400).json({ error: "to_number and assistant_id are required" });
  }

  const famulorRes = await fetch("https://app.famulor.io/api/v1/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FAMULOR_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to_number, assistant_id, lead }),
  });

  const body = await famulorRes.json();
  res.status(famulorRes.status).json(body);
});

Das Frontend bekommt FAMULOR_API_KEY nie zu Gesicht – es spricht nur mit /api/trigger-call auf deiner eigenen Domain.

Mit Backoff wiederholen

Ein 429 oder ein 5xx lohnt sich meist zu wiederholen, statt sofort aufzugeben. Warte zwischen den Versuchen, statt die API im Dauerfeuer zu belasten:

async function famulorRequest(path, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(`https://app.famulor.io/api/v1${path}`, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.FAMULOR_API_KEY}`,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    if (res.ok) return res.json();
    if (![429, 500, 502, 503].includes(res.status) || attempt === maxRetries) {
      const body = await res.json().catch(() => ({}));
      throw new Error(body?.error?.message ?? `Request failed with ${res.status}`);
    }

    const delayMs = 2 ** attempt * 500 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, delayMs));
  }
}

Jeder fehlgeschlagene Versuch verdoppelt ungefähr die Wartezeit (500 ms, 1 s, 2 s …) mit ein wenig zufälligem Jitter, damit nicht alle parallelen Aufrufer im Gleichschritt erneut versuchen.

Webhooks empfangen

Buchungs-Webhooks sind signiert: Setze eine URL auf einem Buchungs-Event-Typ, und jede Zustellung trägt X-Famulor-Signature: sha256=<hex digest> – ein HMAC-SHA256 des rohen Request-Bodys mit dem Secret, das dir beim Speichern der URL einmalig angezeigt wird. Der Variablen-Webhook verwendet dasselbe Schema mit einem eigenen Secret, während Webhooks nach dem Anruf auf Assistentenebene unsigniert sind. Prüfe die Signatur, bevor du der Payload vertraust:

import express from "express";
import crypto from "node:crypto";

const app = express();

// express.raw() keeps the exact bytes — required for signature verification
app.post(
  "/webhooks/famulor-booking",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", process.env.FAMULOR_BOOKING_WEBHOOK_SECRET).update(req.body).digest("hex");
    const signature = req.header("X-Famulor-Signature") ?? "";
    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("invalid signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));
    if (event.event === "booking.created") {
      // event.data.booking_id, .invitee, .start_time, .end_time, ...
    }
    res.status(200).send("ok");
  }
);

Prüfe gegen die rohen Bytes, vor jedem JSON-Parsing. Wird der Body vorher neu serialisiert, können sich Whitespace oder Feldreihenfolge ändern und die Signaturprüfung stillschweigend brechen.

Eine CSV im Batch anrufen

Um eine Liste statt einer einzelnen Nummer anzurufen, begrenze, wie viele Anrufe du gleichzeitig auslöst – die API lehnt Anfragen ab, sobald dein Credit-Hold oder dein Concurrency-Limit erreicht ist, sodass eine unbegrenzte Schleife nur einen Berg von Fehlern statt eines schnelleren Ergebnisses produziert.

import { parse } from "csv-parse/sync";
import { readFileSync } from "node:fs";

const rows = parse(readFileSync("leads.csv"), { columns: true });
const CONCURRENCY = 5;

async function processBatch(rows) {
  const results = [];
  for (let i = 0; i < rows.length; i += CONCURRENCY) {
    const batch = rows.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.allSettled(
      batch.map((row) =>
        famulorRequest("/calls", {
          method: "POST",
          body: JSON.stringify({
            assistant_id: process.env.ASSISTANT_ID,
            to_number: row.phone,
            lead: { name: row.name, company: row.company },
          }),
        })
      )
    );
    results.push(...batchResults);
  }
  return results;
}

famulorRequest ist hier der Retry-with-Backoff-Helfer von oben – das Batching gibt dir kontrollierte Nebenläufigkeit, und der Helfer fängt den gelegentlichen 429 ab, ohne den ganzen Lauf scheitern zu lassen. Für mehr Volumen als ein einmaliges Skript braucht eine Kampagne oder eine durch CRM-Daten ausgelöste Automatisierung meist weniger eigenen Code, um sie am Laufen zu halten, als ein Batch-Skript, das du selbst am Leben halten musst.

​Den API-Key vom Client fernhalten

​Mit Backoff wiederholen

​Webhooks empfangen

​Eine CSV im Batch anrufen

Den API-Key vom Client fernhalten

Mit Backoff wiederholen

Webhooks empfangen

Eine CSV im Batch anrufen