Ejemplos de integración de API

Estas son recetas para el puñado de problemas con los que se topa la mayoría de las integraciones, construidas sobre las formas reales de solicitud y respuesta de la introducción a la API. Adapta el endpoint, los campos y los alcances al recurso con el que estés trabajando — lo que vale la pena reutilizar son los patrones en sí, no los payloads exactos.

Mantén la clave de API fuera del cliente

Nunca llames a la API directamente desde código de navegador o de una app móvil — eso expone tu clave a cualquiera que abra las herramientas de desarrollo. En su lugar, pon un proxy ligero delante: tu frontend llama a tu propio backend, y solo tu backend guarda la clave de Famulor.

// server.js — ruta de Express que el frontend puede llamar de forma segura
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);
});

El frontend nunca ve FAMULOR_API_KEY — solo habla con /api/trigger-call en tu propio dominio.

Reintentos con espera progresiva

Un 429 o un 5xx normalmente vale la pena reintentarlo, no fallar de inmediato. Espera cada vez más entre intentos en lugar de machacar la API:

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));
  }
}

Cada intento fallido aproximadamente duplica la espera (500 ms, 1 s, 2 s…) con un poco de aleatoriedad (jitter) para que las llamadas en paralelo no reintenten todas al mismo tiempo.

Recibir webhooks

Los webhooks de reserva van firmados: define una URL en un tipo de evento de reserva, y cada envío incluye X-Famulor-Signature: sha256=<hex digest> — un HMAC-SHA256 del cuerpo sin procesar de la solicitud, con el secreto que se muestra una sola vez al guardar la URL. Los webhooks de variables usan el mismo esquema con su propio secreto, mientras que los webhooks posteriores a la llamada a nivel de asistente no van firmados. Verifica la firma antes de confiar en el payload:

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

const app = express();

// express.raw() conserva los bytes exactos — necesario para verificar la firma
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");
  }
);

Verifica contra los bytes sin procesar, antes de cualquier análisis JSON. Volver a serializar el cuerpo primero puede cambiar los espacios en blanco o el orden de las claves y romper la verificación de la firma sin previo aviso.

Llamar en lote desde un CSV

Para marcar una lista en lugar de un único número, limita cuántas llamadas lanzas a la vez — la API rechaza las solicitudes en cuanto se alcanza tu retención de crédito o el límite de concurrencia, así que un bucle sin límite solo produce un muro de errores en lugar de terminar antes.

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 aquí es el ayudante de reintentos con espera progresiva de arriba — el procesamiento por lotes te da concurrencia controlada, y el ayudante absorbe el 429 ocasional sin que falle toda la ejecución. Para un volumen que supere un script puntual, una campaña o una automatización activada por datos del CRM suele necesitar menos código propio que mantener que un script por lotes que tienes que seguir ejecutando.

​Mantén la clave de API fuera del cliente

​Reintentos con espera progresiva

​Recibir webhooks

​Llamar en lote desde un CSV

Mantén la clave de API fuera del cliente

Reintentos con espera progresiva

Recibir webhooks

Llamar en lote desde un CSV