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/locations (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/locations?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

Rutas de catálogo disponibles:

Ruta	Retorna
`GET /api/v1/companies`	Empresas
`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.

Modelos de activo: el clasificador de los Activos es el modelo de activo, que por ahora no tiene endpoint de catálogo propio. Su id se obtiene del campo model.id de cualquier activo devuelto por GET /api/v1/assets, o desde la aplicación. Las antiguas categorías de Activos fueron retiradas del producto y de la API.

Escritura de Datos maestros

Los catálogos de Ubicaciones, Centros de costo, Libros de depreciación, Custodios y Empleados 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/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`.

¿Te resultó útil esta página?

Anterior Activos y empresas Siguiente Contabilidad