> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Centros de costo

> Consultar, crear, editar y eliminar centros de costo desde un sistema externo

| Permiso | Endpoints |
| - | - |
| `accounting.cost_centers` | `GET /accounting/cost-centers`, `GET /accounting/cost-centers/{id}` |
| `accounting.cost_centers.write` | `POST /accounting/cost-centers`, `PUT /accounting/cost-centers/{id}`, `DELETE /accounting/cost-centers/{id}` |

<Note>
  Son permisos **explícitos**: deben marcarse uno por uno en **Integraciones externas**; las integraciones existentes no los reciben automáticamente.
</Note>

Los centros de costo son jerárquicos (un centro puede tener subcentros). Sus `id` se envían como `cost_center_id` en [partidas](/docs/api/contabilidad/partidas), [ventas](/docs/api/facturacion/ventas), [compras](/docs/api/facturacion/compras), [cobros](/docs/api/cuentas-por-cobrar#registrar-cobro), [pagos](/docs/api/cuentas-por-pagar#registrar-pago), [transferencias](/docs/api/inventario#completar-transferencia) y [planillas](/docs/api/rrhh/planillas#asignar-centro-de-costo), y sirven de filtro en los [estados financieros](/docs/api/contabilidad/reportes).

<Tip>
  En los documentos y partidas solo se aceptan centros **hoja** (`is_leaf: true`) y activos. Los centros padre agrupan a sus subcentros en los reportes.
</Tip>

Para el uso funcional (política por cuenta, cómo llegan a la partida, reasignación), ver [Centros de costo](/docs/contabilidad/centros-de-costo) en el manual.

## Objeto centro de costo

| Campo | Descripción |
| - | - |
| `id` | Identificador. |
| `code` | Código, único en la empresa. |
| `name` | Nombre. |
| `description` | Descripción (puede ser `null`). |
| `parent_id` | Centro padre (`null` si es un centro raíz). |
| `level` | Nivel en el árbol (1 = raíz). |
| `full_code` | Código completo con la jerarquía. |
| `is_active` | `false` si está desactivado. |
| `is_leaf` | `true` si no tiene subcentros activos: es el único tipo de centro que se puede asignar. |

## Listar centros de costo

```http theme={null}
GET /accounting/cost-centers?include_inactive=false
```

**Permiso requerido:** `accounting.cost_centers`

| Parámetro | Requerido | Descripción |
| - | - | - |
| `include_inactive` | No | `true` para incluir los centros desactivados. Por defecto solo los activos. |

Devuelve la lista plana (ordenada por código) y el mismo conjunto como árbol.

```json theme={null}
{
  "status": true,
  "data": {
    "list": [
      { "id": "c3a0...", "code": "01", "name": "Ventas", "description": null, "parent_id": null, "level": 1, "full_code": "01", "is_active": true, "is_leaf": false },
      { "id": "c3a1...", "code": "0101", "name": "Ventas San Salvador", "description": null, "parent_id": "c3a0...", "level": 2, "full_code": "01.0101", "is_active": true, "is_leaf": true }
    ],
    "tree": [
      {
        "id": "c3a0...", "code": "01", "name": "Ventas", "description": null, "parent_id": null, "level": 1, "full_code": "01", "is_active": true, "is_leaf": false,
        "children": [
          { "id": "c3a1...", "code": "0101", "name": "Ventas San Salvador", "description": null, "parent_id": "c3a0...", "level": 2, "full_code": "01.0101", "is_active": true, "is_leaf": true, "children": [] }
        ]
      }
    ]
  }
}
```

## Consultar centro de costo

```http theme={null}
GET /accounting/cost-centers/{id}
```

**Permiso requerido:** `accounting.cost_centers`

Responde `200` con el [objeto centro de costo](#objeto-centro-de-costo) dentro de `data`, o `404` `Cost center not found`.

## Crear centro de costo

```http theme={null}
POST /accounting/cost-centers
```

**Permiso requerido:** `accounting.cost_centers.write`

```json theme={null}
{
  "code": "0102",
  "name": "Ventas Santa Ana",
  "description": "Equipo comercial de occidente",
  "parent_id": "c3a0...",
  "is_active": true
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `code` | Sí | Código (máx. 50), único en la empresa. |
| `name` | Sí | Nombre (máx. 255). |
| `description` | No | Descripción (máx. 1000). |
| `parent_id` | No | Centro padre de la misma empresa. Sin él, el centro es raíz. |
| `is_active` | No | Por defecto `true`. |

**Comportamiento**

* El nivel (`level`) se calcula a partir del padre.
* Al crear un subcentro, su padre deja de ser hoja: ya no se puede asignar a documentos nuevos, pero sigue agrupando a sus hijos en los reportes.

**Respuesta `201`**: el [objeto centro de costo](#objeto-centro-de-costo) creado.

## Editar centro de costo

```http theme={null}
PUT /accounting/cost-centers/{id}
```

**Permiso requerido:** `accounting.cost_centers.write`

Acepta los mismos campos que la creación, todos opcionales: solo cambian los que envías.

```json theme={null}
{ "name": "Ventas Occidente", "is_active": false }
```

**Comportamiento**

* Si cambias `parent_id`, se recalcula el nivel del centro y de todos sus subcentros.
* Un centro no puede depender de sí mismo ni de uno de sus subcentros.
* Desactivar un centro (`is_active: false`) impide asignarlo a documentos y partidas nuevos; lo ya registrado se conserva.

**Respuesta `200`**: el [objeto centro de costo](#objeto-centro-de-costo) actualizado.

## Eliminar centro de costo

```http theme={null}
DELETE /accounting/cost-centers/{id}
```

**Permiso requerido:** `accounting.cost_centers.write`

**Comportamiento**

* Si el centro **no** se ha usado en partidas ni documentos, se elimina: `{"deleted": true, "deactivated": false}`.
* Si ya tiene movimientos o documentos, no se borra: se **desactiva** para conservar el historial: `{"deleted": false, "deactivated": true}`.
* Si tiene subcentros, responde `422`: elimínalos o muévelos a otro padre primero.

```json theme={null}
{
  "status": true,
  "data": { "deleted": false, "deactivated": true }
}
```

## Errores

| Código | Causa |
| - | - |
| `401` | API key ausente o inválida. |
| `403` | La integración no tiene el permiso requerido. |
| `404` | `Cost center not found` (inexistente o de otra empresa). |
| `422` | `Validation errors`; por ejemplo `code`: `Ya existe un centro de costos con este código.`, `parent_id`: `El centro de costos padre no existe o no pertenece a esta empresa.` o `Un centro de costos no puede depender de sí mismo ni de un subcentro suyo.` |
| `422` | `El centro de costo tiene subcentros; elimínelos o muévalos primero.` (al eliminar). |

```json theme={null}
{
  "status": false,
  "message": "Validation errors",
  "errors": { "code": "Ya existe un centro de costos con este código." }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.