> ## 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.

# Journal entries

> Query journal entries, create draft entries, and manage entry types from an external system

**Required permission:** `accounting.journal_entries` (changes to the [entry types](#journal-entry-types) catalog also require `accounting.entry_types.write`)

## Create journal entry

```http theme={null}
POST /accounting/journal-entries
```

Use it to bring operations that originate in another system (external payroll, a collections system, an ERP, etc.) into FileXpress accounting.

> [!NOTE]
>
> Journal entries created through the API are **always saved as DRAFT**. The accountant reviews and posts them in FileXpress; until then they do not affect the financial statements.

```json theme={null}
{
  "branch_id": "uuid",
  "entry_date": "2026-10-31",
  "description": "Comisiones de ventas octubre",
  "external_reference": "COM-2026-10",
  "entry_type": "PROV",
  "details": [
    { "account_code": "510201", "debit": 1250.00, "credit": 0, "description": "Gasto por comisiones", "cost_center_id": "c3b7..." },
    { "account_code": "210305", "debit": 0, "credit": 1250.00, "description": "Comisiones por pagar" }
  ]
}
```

| Field | Required | Description |
| - | - | - |
| `branch_id` | Yes | Branch. See `GET /branches`. |
| `entry_date` | Yes | Entry date. An **OPEN** period must exist for that month. |
| `description` | Yes | Description (max. 1000 characters). |
| `entry_type` | No | Entry type code (max. 20 characters), for example `DIA`, `ING`, `EGR`. It must be an **active** type of the business; see [Journal entry types](#journal-entry-types). |
| `entry_type_id` | No | Entry type ID, as an alternative to `entry_type`. If both are sent, `entry_type_id` takes precedence. |
| `external_reference` | No | Reference in your system; it is appended to the description for traceability. |
| `details` | Yes | Entry lines (from 2 to 200). |

### `details[]`

| Field | Required | Description |
| - | - | - |
| `account_id` or `account_code` | Yes (one) | Account from the chart of accounts. It must be a posting account (`accepts_movements: true`). |
| `debit` | Yes | Debit amount (0 if the line is a credit). |
| `credit` | Yes | Credit amount (0 if the line is a debit). |
| `description` | No | Line detail. |
| `cost_center_id` | Depends on the account | Line [cost center](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md) (leaf and active center). Required if the account requires it; not allowed on accounts that do not accept a center. See [Cost center behavior](#cost-center-behavior). |
| `cost_center_distribution_id` | No | Active [distribution](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md#distributions) instead of a single center. Only on accounts that accept a center; mutually exclusive with `cost_center_id` on the same line. The entry is saved as a draft with the line as sent and, when it is posted in FileXpress, the line is split into one line per center. |

**Rules**

* Each line carries an amount in the debit **or** the credit, not both.
* The entry must balance: sum of debits = sum of credits.
* The entry type comes from the same catalog used by the new journal entry screen in FileXpress ([Journal entry types](#journal-entry-types)). If `entry_type` or `entry_type_id` is sent and does not match an active type of the business, it responds `422` with the list of valid codes.
* Without `entry_type` or `entry_type_id`, the type configured for the external API in the business accounting settings is used (`DIA` if none was configured), as before.
* The saved description includes the integration name, for example `Comisiones de ventas octubre [Ref: COM-2026-10] (API: Mi ERP)`.

### Cost center behavior

Each account in the chart of accounts has a cost center policy, configured in FileXpress (see [Cost centers](https://docs.filexpress.app/en/docs/contabilidad/centros-de-costo.md#policy-per-account)):

| Policy | `cost_center_id` on the line |
| - | - |
| None (balance sheet accounts: banks, cash, VAT (IVA), customers, suppliers) | Not allowed. |
| Optional (default for income, costs, and expenses) | May or may not be sent. |
| Required | Mandatory. |

If the company has the option to require cost centers turned on, accounts with an optional policy are treated as required. Get the center IDs with [Cost centers](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md).

**`201` response**: the created entry (format below), with `status: "BORRADOR"`, `entry_code: null` (the code is assigned when it is posted) and `entry_type_id` with the applied type.

**Common errors (`422`)**

```json theme={null}
{
  "status": false,
  "message": "Validation errors",
  "errors": {
    "details.1.account": "Account 2103 has sub-accounts; use a movement account.",
    "details.0.cost_center_id": "La cuenta 510201 requiere centro de costo.",
    "details": "The entry is not balanced: debit 1250.00, credit 1200.00.",
    "entry_type": "Entry type not found or inactive. Valid codes: DIA, EGR, ING, PROV (see GET /accounting/entry-types)."
  }
}
```

Other `details.N.cost_center_id` messages: `La cuenta <código> no acepta centro de costo (solo las cuentas de resultado lo llevan).` and those for a center that does not exist, is inactive, or has sub-centers.

It also responds `422` if there is no open period for `entry_date`.

## List journal entries

```http theme={null}
GET /accounting/journal-entries?start_date=2026-10-01&end_date=2026-10-31
```

| Parameter | Required | Description |
| - | - | - |
| `start_date`, `end_date` | Yes | Range by entry date (max. 370 days). |
| `status` | No | `BORRADOR` or `PROCESADA`. |
| `branch_id` | No | Filter by branch. |
| `per_page`, `page` | No | Pagination (max. 200 per page). |

## Get journal entry

```http theme={null}
GET /accounting/journal-entries/{id}
```

```json theme={null}
{
  "status": true,
  "data": {
    "id": "uuid",
    "branch_id": "uuid",
    "entry_code": "DIA-2026-10-0042",
    "entry_type_id": "uuid",
    "entry_type": "DIA",
    "entry_date": "2026-10-31",
    "description": "Planilla Primera quincena octubre 2026 (01/10/2026 al 15/10/2026)",
    "status": "PROCESADA",
    "reference_type": "payroll",
    "total_debit": 5320.10,
    "total_credit": 5320.10,
    "is_balanced": true,
    "details": [
      { "account_code": "510101", "account_name": "Sueldos y salarios", "debit": 4850.00, "credit": 0, "description": "Sueldos y salarios", "cost_center_id": "c3a1..." },
      { "account_code": "210401", "account_name": "Sueldos por pagar", "debit": 0, "credit": 4820.35, "description": "Sueldos por pagar", "cost_center_id": null }
    ]
  }
}
```

`reference_type` indicates the origin: `sale`, `expense`, `payment_received`, `payment_made`, `payroll`, `payroll_payment`, `payroll_provision`, `external_integration`, or empty (manual entry).

Each `details` line includes `cost_center_id` (`null` if it has no center) and `cost_center_distribution_id` (the originating distribution, or `null`). In entries generated from documents, the center only appears on income statement account lines.

## Journal entry types

The business's catalog of journal entry types is the same one used by the new journal entry screen in FileXpress. The `code` of each type is the value you send as `entry_type` when you [create a journal entry](#create-journal-entry) (or its `id` as `entry_type_id`).

| Operation | Permission |
| - | - |
| List and get | `accounting.journal_entries` |
| Create, edit, and delete | `accounting.entry_types.write` |

An entry type from another business responds `404`, the same as one that does not exist.

### List entry types

```http theme={null}
GET /accounting/entry-types?include_inactive=false
```

| Parameter | Required | Description |
| - | - | - |
| `include_inactive` | No | `true` includes deactivated types. By default only active ones are listed. |

```json theme={null}
{
  "status": true,
  "data": {
    "list": [
      {
        "id": "uuid",
        "code": "PROV",
        "name": "Provisiones",
        "description": "Provisiones mensuales",
        "prefix": "PRV",
        "requires_approval": false,
        "is_active": true
      }
    ]
  }
}
```

### Get entry type

```http theme={null}
GET /accounting/entry-types/{id}
```

Returns one type in the same format as each element of `list`.

### Create entry type

```http theme={null}
POST /accounting/entry-types
```

```json theme={null}
{
  "code": "PROV",
  "name": "Provisiones",
  "description": "Provisiones mensuales",
  "prefix": "PRV",
  "requires_approval": false,
  "is_active": true
}
```

| Field | Required | Description |
| - | - | - |
| `code` | Yes | Code (max. 20 characters: letters, numbers, `-`, and `_`). It is saved in uppercase and must be unique within the business. |
| `name` | Yes | Name (max. 100 characters). |
| `description` | No | Description (max. 1000 characters). |
| `prefix` | Yes | Prefix of the sequence number for entries of this type (max. 10 characters). |
| `requires_approval` | No | Whether entries of this type require approval. Defaults to `false`. |
| `is_active` | No | Defaults to `true`. |

**`201` response**: the created type. If the code already exists it responds `422` (`Entry type PROV already exists.`). If the code belonged to a previously deleted type, that type is restored with the data sent.

### Edit entry type

```http theme={null}
PUT /accounting/entry-types/{id}
```

Updates only the fields sent: `name`, `description`, `prefix`, `requires_approval`, and `is_active`. The `code` cannot be changed because entries reference it; sending it responds `422`. To use a different code, create a new type.

### Delete entry type

```http theme={null}
DELETE /accounting/entry-types/{id}
```

If no entry uses the type, it is deleted. If any entry uses it, it is only deactivated (it is no longer accepted when creating entries, but existing ones keep it).

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


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