API REST para desarrolladores (descripcion general)

ActivoHQ expone una API REST en /api/v1 para que puedas integrar los datos de Activos fijos con tus propios sistemas, automatizar actualizaciones masivas o construir paneles personalizados. Esta pagina cubre todos los endpoints disponibles en la Fase 1.

Referencia de la API

• Activos y Empresas - CRUD para Empresas y Activos, esquema de escritura y campos calculados de solo lectura.
• Catalogos y Datos Maestros - GET y POST/PUT para categorias, Ubicaciones, Centros de costo, libros de depreciacion, Custodios y Empleados.
• Contabilidad - Acceso de solo lectura a anos fiscales, corridas/asientos de depreciacion, Lotes de diario, bajas y revaluaciones.
• Auditoria y Ciclo de Vida - Conteos de sesiones de solo lectura, resultados de conteo, traslados, prestamos y reservas, mas POSTs de acciones del ciclo de vida.

URL base

https://{tenant}.activohq.cloud/api/v1

Reemplaza {tenant} con tu subdominio (p. ej. acme -> https://acme.activohq.cloud/api/v1). Todas las solicitudes estan limitadas al tenant identificado por el encabezado del host; no hay un segmento de tenant en la ruta.

Autenticacion

Cada solicitud a /api/v1 debe incluir una clave de API en el encabezado X-Api-Key.

X-Api-Key: ahq_your_key_here

Como obtener una clave: inicia sesion como Administrador, abre Perfil -> API para desarrolladores y haz clic en Generar. Copia la clave (se muestra una sola vez despues de generarla). Para rotar una clave comprometida usa Regenerar; para deshabilitar el acceso usa Revocar.

Una clave ausente o invalida devuelve:

HTTP 401 Unauthorized

Alcance por empresa

Todos los endpoints, excepto GET /api/v1/companies, requieren un parametro de consulta companyId. Obtén los IDs de tu empresa desde GET /api/v1/companies.

Paginacion

Los endpoints de listado aceptan skip (predeterminado 0) y take (predeterminado 50, maximo 200) y devuelven un sobre estandar:

{
  "items": [...],
  "total": 312,
  "skip": 0,
  "take": 50
}

Recorre el conjunto completo de resultados incrementando skip en el valor de take hasta que skip >= total.

Estructura de errores

Todos los errores devuelven un estado distinto de 2xx y un cuerpo JSON pequeno:

{ "error": "Human-readable message." }

Flujo de integracion tipico

1. Llama a GET /api/v1/companies para obtener tu companyId.
2. Llama a los endpoints de catalogos (/categories, /locations, etc.) para mapear codigos a IDs.
3. POST /api/v1/assets por cada activo nuevo.
4. PUT /api/v1/assets/{id} para actualizar los existentes.
5. GET /api/v1/assets?search=... para consultar el registro.

Preguntas y soporte

Contacta a support@activohq.cloud o al administrador de tu instancia de ActivoHQ. Incluye el ID de solicitud (que aparece en la respuesta) y el payload exacto que enviaste.