Documentación para Desarrolladores

Conecta ObraOS con tu contabilidad, tu ERP o tu asistente de IA. Crea llaves y webhooks en Panel → Integraciones. Todo funciona con los datos demo de Casas del Valle (Costa Rica, CRC).

1. API REST v1

Dirección base: https://tu-dominio/api/v1 (también /api/public/v1). Envía tu llave en Authorization: Bearer. Solo el dueño o un administrador crean llaves; cada llave es Solo Lectura o Lectura y Escritura, y nunca tiene más permisos que el rol de su dueño. La llave se muestra una sola vez; una llave revocada deja de funcionar al instante.

curl "https://tu-dominio/api/v1/proyectos?pagina=1&limite=20" \
  -H "Authorization: Bearer obra_TU_LLAVE"

curl -X POST https://tu-dominio/api/v1/proyectos/ID/movimientos \
  -H "Authorization: Bearer obra_TU_LLAVE" -H "Content-Type: application/json" \
  -d '{"tipo":"pago","concepto":"Cemento 40 sacos","monto":312000}'

Método	Ruta	Qué hace
GET	`/metricas`	Resumen de la constructora: obras, avance, m², gastos e ingresos
GET	`/proyectos?pagina=1&limite=50&buscar=casa`	Lista tus obras (paginado, con búsqueda por nombre)
POST	`/proyectos`	Crea una obra: nombre, m2, tipo, ubicacion, cliente_nombre, fecha_inicio, fecha_fin
GET	`/proyectos/{id}`	Detalle de una obra
PATCH	`/proyectos/{id}`	Cambia nombre, estado, avance o fecha_fin
GET	`/proyectos/{id}/partidas`	Partidas del presupuesto (paginado)
POST	`/proyectos/{id}/partidas`	Agrega partida: capitulo, descripcion, unidad, cantidad, material_unit, mo_unit, equipo_unit, desperdicio_pct
PATCH	`/proyectos/{id}/partidas/{partida}`	Actualiza avance o costo_real
GET	`/proyectos/{id}/avances`	Reportes de avance (paginado)
POST	`/proyectos/{id}/avances`	Registra avance: texto, avance_estimado, autor
GET	`/proyectos/{id}/movimientos`	Gastos y cobros (paginado)
POST	`/proyectos/{id}/movimientos`	Agrega gasto o cobro: tipo (pago\|cobro\|anticipo\|retencion\|liberacion), concepto, monto, fecha, estado

Las listas responden así (máximo 200 por página):

{"datos":[…],"pagina":1,"limite":20,"total":3,"hay_mas":false}

Errores: {"error": "mensaje"} con código 400 (datos inválidos), 401 (llave inválida o revocada), 403 (sin permiso o llave de solo lectura), 404 (no existe) o 405 (método no permitido).

2. Webhooks Salientes

Registra una URL https y elige eventos: obra.creada, avance.registrado, gasto.agregado y cobro.registrado. Te enviamos un POST con este cuerpo:

{"id":"5c1…","evento":"gasto.agregado","empresa_id":"9a2…","creado":"2026-10-05T10:00:00Z",
 "datos":{"proyecto_id":"b71…","concepto":"Cemento 40 sacos","monto":312000,"tipo":"pago"}}

Firma: cada envío trae X-Signature: sha256=… (igual a X-ObraOS-Firma) y X-ObraOS-Timestamp. La firma es HMAC-SHA256 en hexadecimal de timestamp + "." + cuerpo con el secreto del webhook. Verifícala con el cuerpo tal como llegó y rechaza timestamps de más de 5 minutos.

import crypto from "node:crypto";
const ts = req.headers["x-obraos-timestamp"];
const esperada = "sha256=" + crypto.createHmac("sha256", SECRETO)
  .update(ts + "." + cuerpoCrudo).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(req.headers["x-signature"] ?? ""));
if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();

Reintentos: si tu servidor no responde con 2xx, reintentamos a los 2, 4, 8 y 16 minutos (5 intentos). Cada entrega queda registrada con estado, respuesta y fecha en Integraciones.

3. Webhooks Entrantes

Actívalo en Integraciones para obtener tu URL y secreto. Firma el cuerpo con HMAC-SHA256 (hexadecimal) y envíalo en X-Signature. Si el JSON trae "evento", se registra con ese nombre.

CUERPO='{"evento":"factura.pagada","monto":150000}'
FIRMA=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -hmac "TU_SECRETO" | cut -d' ' -f2)
curl -X POST https://tu-dominio/api/v1/webhooks/in/ID_EMPRESA \
  -H "Content-Type: application/json" -H "X-Signature: sha256=$FIRMA" -d "$CUERPO"

Respuestas: 202 recibido, 401 firma inválida, 404 no activado.

4. Asistentes de IA (MCP)

Habla con tus obras desde Claude, ChatGPT o Cursor: "¿cómo va la casa de 120 m²?", "registra un gasto de cemento de 312 000".

En Claude: Ajustes → Conectores → Agregar Conector Personalizado.
Pega la dirección: https://tu-dominio/mcp
Inicia sesión con tu cuenta de ObraOS y pulsa Autorizar.

Para Claude Desktop, Cursor u otros clientes, usa esta configuración:

{
  "mcpServers": {
    "obraos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tu-dominio/mcp"]
    }
  }
}

El MCP usa inicio de sesión seguro (OAuth) en lugar de la llave de API: así el asistente actúa con tus permisos, solo ve tus empresas y puedes desconectarlo cuando quieras.

Herramientas: listar_proyectos, buscar_proyectos, ver_proyecto, resumir_metricas (lectura) y crear_proyecto, registrar_avance, agregar_gasto, actualizar_partida (escritura).