Desarrolladores

Autenticación

Crea un token en Configuración → Conectores → “API y MCP”. Se muestra una sola vez. Pásalo como header en cada request:

Authorization: Bearer frl_tu_token_aca

Cada token está limitado a su workspace y es revocable en cualquier momento. Solo lectura (scope read) por ahora.

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 lea tu workspace. URL del servidor:

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

Transporte HTTP (JSON-RPC 2.0). Autenticación con el mismo token (Authorization: Bearer frl_…). Tools disponibles: get_workspace, list_projects, list_clients, list_quotes, list_tasks.

// Ejemplo de config 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 hace POST con el evento y firma el body. Eventos: project.createdquote.approvedquote.rejectedpayment.paid.

Verifica la firma del header 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 liviano y sin dependencias (Node, browser 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).