STRUO API Documentation

Integrate STRUO into your application using our REST API. This documentation provides an overview of available capabilities and endpoints.

Plan Enterprise Requerido

El acceso a la API está disponible exclusivamente para clientes en el plan Enterprise. Contacta a nuestro equipo de ventas para más información.

Visión General

La API de STRUO es una interfaz REST que permite integrar la plataforma de CRM con tu software existente. Proporciona acceso a funcionalidades de gestión de proyectos, CRM, materiales, equipo, documentos y finanzas.

Base URL

https://api.struo.studio/v1

Formato de Respuesta

Todas las respuestas están en JSON. Cada respuesta incluye un status (success/error) y datos asociados.

Límite de Tasa

Plan Enterprise: 10,000 requests por hora por API key. Si excedes este límite, recibirás respuestas HTTP 429.

Autenticación

Todos los requests a la API requieren autenticación mediante Bearer token. Obtén tu clave API desde la configuración de tu cuenta en STRUO (disponible solo para plan Enterprise).

Estructura del Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Seguridad

Nunca compartas tus claves API públicamente
Regenera claves regularmente desde tu panel de control
Usa solo HTTPS en producción
Implementa rotación de claves cada 90 días

Módulos Disponibles

Proyectos

Gestión de proyectos de construcción e inmobiliarios

GET/api/v1/projects

Obtiene lista de proyectos del usuario autenticado

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "projects": [
      {
        "id": "proj_123abc",
        "name": "Edificio Comercial Centro",
        "client": "Inmobiliaria XYZ",
        "status": "active",
        "budget": 500000,
        "created_at": "2026-02-15T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 1
  }
}

POST/api/v1/projects

Crea un nuevo proyecto

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "proj_456def",
    "name": "Nuevo Proyecto",
    "status": "draft",
    "created_at": "2026-03-17T14:20:00Z"
  }
}

GET/api/v1/projects/:id

Obtiene detalles de un proyecto específico

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "proj_123abc",
    "name": "Edificio Comercial Centro",
    "description": "Proyecto de oficinas de 15 pisos",
    "status": "active",
    "budget": 500000,
    "spent": 275000,
    "client_id": "cust_789xyz",
    "location": "Ciudad de México",
    "phases": [
      {
        "id": "phase_1",
        "name": "Cimentación",
        "status": "in_progress",
        "progress": 85
      }
    ]
  }
}

PUT/api/v1/projects/:id

Actualiza un proyecto existente

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "proj_123abc",
    "updated_at": "2026-03-17T15:45:00Z",
    "message": "Proyecto actualizado correctamente"
  }
}

CRM y Contactos

Gestión de clientes, contactos y oportunidades de venta

GET/api/v1/contacts

Lista todos los contactos del usuario

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "id": "cont_234lmn",
        "name": "Juan García",
        "email": "juan@example.com",
        "phone": "+52 55 1234 5678",
        "company": "Constructora ABC",
        "category": "cliente"
      }
    ],
    "total": 45,
    "page": 1
  }
}

POST/api/v1/contacts

Crea un nuevo contacto

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "cont_567opq",
    "name": "María López",
    "created_at": "2026-03-17T16:10:00Z"
  }
}

GET/api/v1/opportunities

Obtiene oportunidades de venta del usuario

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "opportunities": [
      {
        "id": "opp_890rst",
        "title": "Remodelación Oficina Centro",
        "contact_id": "cont_234lmn",
        "value": 75000,
        "stage": "negotiation",
        "expected_close": "2026-04-30",
        "probability": 70
      }
    ],
    "total": 12,
    "pipeline_value": 450000
  }
}

PUT/api/v1/opportunities/:id

Actualiza el estado de una oportunidad

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "opp_890rst",
    "stage": "won",
    "updated_at": "2026-03-17T17:30:00Z"
  }
}

Materiales

Gestión de catálogo de materiales e inventario

GET/api/v1/materials

Lista materiales del catálogo

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "materials": [
      {
        "id": "mat_012uvw",
        "name": "Cemento Portland 50kg",
        "unit": "bolsa",
        "cost": 185.50,
        "stock": 250,
        "supplier": "Cemex",
        "category": "materiales"
      }
    ],
    "total": 156,
    "categories": ["materiales", "herramientas", "acabados"]
  }
}

GET/api/v1/materials/:id/inventory

Obtiene historial de inventario de un material

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "material_id": "mat_012uvw",
    "current_stock": 250,
    "movements": [
      {
        "date": "2026-03-15",
        "type": "entrada",
        "quantity": 100,
        "reference": "Orden #ORD-2026-001"
      }
    ]
  }
}

POST/api/v1/materials/stock-movement

Registra movimiento de inventario

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "movement_id": "mov_345xyz",
    "material_id": "mat_012uvw",
    "new_stock": 240,
    "created_at": "2026-03-17T18:00:00Z"
  }
}

Equipo y Nómina

Gestión de empleados y registros de nómina

GET/api/v1/employees

Lista todos los empleados

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "employees": [
      {
        "id": "emp_678cde",
        "name": "Carlos Rodríguez",
        "position": "Maestro de Obra",
        "department": "Construcción",
        "salary": 25000,
        "status": "active"
      }
    ],
    "total": 23,
    "departments": ["Construcción", "Administrativo", "Diseño"]
  }
}

GET/api/v1/payroll/periods/:period_id

Obtiene nómina de un período

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "period_id": "pay_901fgh",
    "period": "2026-03",
    "employees": [
      {
        "id": "emp_678cde",
        "name": "Carlos Rodríguez",
        "gross_salary": 25000,
        "deductions": 3750,
        "net_salary": 21250
      }
    ],
    "total_payroll": 457500
  }
}

Documentos

Generación y gestión de documentos

POST/api/v1/documents/generate

Genera un documento usando IA (ARIA)

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "document_id": "doc_ijk234",
    "type": "proposal",
    "content": "Propuesta generada automáticamente...",
    "format": "pdf",
    "created_at": "2026-03-17T18:30:00Z",
    "download_url": "/api/v1/documents/doc_ijk234/download"
  }
}

GET/api/v1/documents/:id

Obtiene detalles de un documento

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "doc_ijk234",
    "title": "Propuesta Proyecto ABC",
    "type": "proposal",
    "created_at": "2026-03-17T18:30:00Z",
    "modified_at": "2026-03-17T19:00:00Z",
    "status": "completed"
  }
}

Finanzas

Facturación, pagos y reportes financieros

GET/api/v1/invoices

Lista facturas del usuario

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "invoices": [
      {
        "id": "inv_lmn567",
        "number": "FAC-2026-001",
        "customer": "Constructora XYZ",
        "amount": 125000,
        "status": "paid",
        "issued_date": "2026-03-01",
        "due_date": "2026-03-15"
      }
    ],
    "total": 28,
    "total_revenue": 3500000
  }
}

POST/api/v1/invoices

Crea una nueva factura

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "id": "inv_opq890",
    "number": "FAC-2026-029",
    "created_at": "2026-03-17T19:30:00Z",
    "download_url": "/api/v1/invoices/inv_opq890/download"
  }
}

GET/api/v1/financial-reports/:type

Genera reportes financieros (cashflow, margin, etc)

Ejemplo de Respuesta:

{
  "status": "success",
  "data": {
    "report_type": "cashflow",
    "period": "2026-03",
    "beginning_balance": 150000,
    "inflows": 350000,
    "outflows": 285000,
    "ending_balance": 215000
  }
}

Códigos de Estado HTTP

200

Request exitoso

201

Created

Recurso creado exitosamente

400

Bad Request

Parámetros inválidos o malformados

401

Unauthorized

API key inválida o ausente

403

Forbidden

Sin permisos para acceder a este recurso

429

Too Many Requests

Límite de tasa excedido

500

Server Error

Error interno del servidor

Mejores Prácticas

Implementa reintentos exponenciales para fallos de red temporales
Cachea respuestas cuando sea apropiado para reducir latencia
Usa webhooks para eventos en tiempo real en lugar de polling constante
Valida datos antes de enviar requests para evitar errores 400
Monitorea tus límites de tasa y planifica incrementalmente
Usa IDs de idempotencia para operaciones críticas
Implementa logging detallado para debugging

¿Necesitas Ayuda?

Nuestro equipo de soporte técnico está disponible para ayudarte con la integración. Para clientes Enterprise, cuenta con soporte prioritario.

Contactar Soporte API Centro de Ayuda

Email de Soporte

api@struo.studio

Plan Requerido

Enterprise