Desarrolladores

Autenticación

Crea un token en Configuración → Conectores → “API y MCP”. Se muestra una sola vez. Envíalo en el encabezado de cada solicitud:

Authorization: Bearer frl_tu_token_aca

Cada token está limitado a su espacio y puedes revocarlo en cualquier momento. Por ahora, admite el permiso de solo lectura read.

API REST

curl https://frelanse.com/api/public/v1/projects \
  -H "Authorization: Bearer frl_tu_token"

# → { "projects": [ { "code": "PROJ-001", "name": "...", "stage": "...", ... } ] }

Servidor MCP

frelanse es un servidor MCP (Model Context Protocol). Agrégalo a Claude, Cursor o cualquier cliente MCP para que el asistente consulte tu espacio. URL del servidor:

https://frelanse.com/api/public/v1/mcp

Transporte HTTP (MCP 2025-11-25). Autenticación con el mismo token (Authorization: Bearer frl_…). Herramientas disponibles: get_workspace, list_projects, list_clients, list_quotes, list_tasks, además de recursos y el prompt de resumen del espacio.

// Ejemplo de configuración MCP (cliente genérico)
{
  "mcpServers": {
    "frelanse": {
      "url": "https://frelanse.com/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer frl_tu_token" }
    }
  }
}

Webhooks

Registra una URL en Configuración → Webhooks para recibir eventos en tiempo real. frelanse envía una solicitud POST con el evento y firma el cuerpo. Eventos disponibles:

Verifica la firma del encabezado frelanse-signature: t=…,v1=…. Es HMAC-SHA256 sobre `${t}.${rawBody}` con el secreto del endpoint:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

SDK de TypeScript

Cliente ligero y sin dependencias (Node, navegador y edge). El paquete npm @frelanse/sdk llega pronto; por ahora copia el cliente y úsalo así:

import { FrelanseClient } from "./frelanse-client";

const frelanse = new FrelanseClient({ token: "frl_tu_token" });

const { workspace } = await frelanse.me();
const { projects } = await frelanse.listProjects({ limit: 20 });
const { tasks } = await frelanse.listTasks({ status: "todo" });

El método verifyFrelanseWebhook del SDK valida la firma de los webhooks (inyectándole node:crypto).