Catálogos y datos maestros

API: Catálogos y Datos maestros

Esta página requiere el encabezado X-Api-Key y el parámetro ?companyId= descritos en el resumen de la API REST para desarrolladores.

Endpoints de catálogo

GET /api/v1/categories (y otros catálogos)

Todos los endpoints de catálogo siguen la misma estructura. Úselos para resolver ids antes de crear o actualizar Activos.

curl -s "https://acme.activohq.cloud/api/v1/categories?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

Rutas de catálogo disponibles:

Ruta	Retorna
`GET /api/v1/categories`	Categorías de activos
`GET /api/v1/locations`	Ubicaciones
`GET /api/v1/cost-centers`	Centros de costo
`GET /api/v1/depreciation-books`	Libros de depreciación
`GET /api/v1/custodians`	Custodios
`GET /api/v1/employees`	Empleados (incluye `email`)

Cada elemento en items[] tiene al menos id, code y name. Los Empleados también incluyen email.

Escritura de Datos maestros

Los seis recursos de catálogo también aceptan POST (crear) y PUT (actualizar). El mismo encabezado X-Api-Key y el parámetro ?companyId= son requeridos.

Regla	Detalle
Éxito en POST	`201 Created` -- el encabezado `Location` apunta al nuevo recurso; el cuerpo contiene `{id, code, name}` (los Empleados también incluyen `email`).
Éxito en PUT	`200 OK` -- el cuerpo contiene el `{id, code, name}` actualizado. La ruta PUT agrega `/{id}`, p. ej. `PUT /api/v1/locations/{id}`.
Código duplicado	`400 Bad Request` -- `{"error":"Code already in use."}`.
Id desconocido en PUT	`404 Not Found`.
Campos requeridos	`code` y `name` en todos los recursos.

Ejemplo curl -- POST /api/v1/locations

curl -s -X POST "https://acme.activohq.cloud/api/v1/locations?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HQ-01",
    "name": "Head Office",
    "city": "Panama City",
    "country": "PA",
    "isActive": true
  }'

Respuesta (201 Created):

{ "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890", "code": "HQ-01", "name": "Head Office" }

POST + PUT /api/v1/categories

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`description`	string	No	Descripción en texto libre.
`defaultUsefulLifeMonths`	integer	Sí	Vida útil predeterminada asignada al crear Activos en esta categoría.
`depreciationMethod`	string	No	`StraightLine`, `DecliningBalance` o `UnitsOfProduction`.
`decliningBalanceFactor`	decimal	No	Multiplicador para saldo decreciente (p. ej. `2.0` para doble saldo decreciente).
`assetAccountCode`	string	No	Cuenta contable para el costo del activo.
`accumulatedDepreciationAccountCode`	string	No	Cuenta contable para depreciación acumulada.
`depreciationExpenseAccountCode`	string	No	Cuenta contable para el gasto de depreciación.
`gainLossOnDisposalAccountCode`	string	No	Cuenta contable para ganancia/pérdida en disposición.
`disposalClearingAccountCode`	string	No	Cuenta de compensación contable en disposición.
`revaluationSurplusAccountCode`	string	No	Cuenta contable para superávit de revaluación.
`impairmentLossAccountCode`	string	No	Cuenta contable para pérdida por deterioro.
`isActive`	boolean	No	Por defecto es `true`.

POST + PUT /api/v1/locations

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`description`	string	No	Descripción en texto libre.
`address1`	string	No	Dirección.
`city`	string	No	Ciudad.
`stateProvince`	string	No	Estado o provincia.
`country`	string	No	País (se recomienda ISO 3166-1 alfa-2, p. ej. `"PA"`).
`isActive`	boolean	No	Por defecto es `true`.

POST + PUT /api/v1/cost-centers

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`description`	string	No	Descripción en texto libre.
`parentId`	guid	No	Id del centro de costo padre para estructuras jerárquicas.
`isActive`	boolean	No	Por defecto es `true`.

POST + PUT /api/v1/depreciation-books

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`description`	string	No	Descripción en texto libre.
`isDefault`	boolean	No	Marca este libro como predeterminado. Solo un libro puede ser el predeterminado a la vez.
`isActive`	boolean	No	Por defecto es `true`.

POST + PUT /api/v1/custodians

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`email`	string	No	Correo electrónico de contacto.
`phone`	string	No	Número de teléfono de contacto.
`department`	string	No	Nombre del departamento.
`isActive`	boolean	No	Por defecto es `true`.

POST + PUT /api/v1/employees

Campo	Tipo	Requerido	Notas
`code`	string	Sí	Único dentro de la empresa.
`name`	string	Sí	Nombre para mostrar.
`email`	string	No	Correo electrónico de contacto. Se incluye en la respuesta de POST/PUT.
`phone`	string	No	Número de teléfono de contacto.
`department`	string	No	Nombre del departamento.
`jobTitle`	string	No	Cargo o título profesional.
`isActive`	boolean	No	Por defecto es `true`.

Was this page helpful?

Previous Activos y empresas Next Contabilidad