# Edara API v3: Cash In/Out

Read the [guide](../guide.md) first: authentication, paging, errors, rate limits and the shared `PagedResult`, `BatchResult` and `*Reference` shapes.

- `POST /v3/cash-in`: Records a cash-in.
- `POST /v3/cash-out`: Records a cash-out.

## Endpoints

### `POST /v3/cash-in`: Records a cash-in.

Operation `CreateCashIn` · permission `create:cash-transaction`

**Body**: `CashTransactionRequest`

| field | type | default | validation | description |
|---|---|---|---|---|
| `mainAccountId` | `int?` |  | GreaterThan(0) | The main cash account identifier. |
| `documentDate` | `DateTime?` |  | NotNull() | The accounting document date. |
| `paperNumber` | `string` |  |  | The external paper number. |
| `responsibleId` | `int?` |  | GreaterThan(0) .When(x => x.ResponsibleId.HasValue) | The responsible user identifier. |
| `notes` | `string` |  |  | Optional document notes. |
| `currencyId` | `int?` |  | GreaterThan(0) .When(x => x.CurrencyId.HasValue) | The optional document currency identifier. |
| `exchangeRate` | `decimal?` |  | GreaterThan(0m) .When(x => x.ExchangeRate.HasValue) | The exchange rate when a currency is supplied. |
| `accountingDocumentDetails` | `List<CashTransactionDetailRequest>` |  | NotNull() .NotEmpty(); each: SetValidator(new CashTransactionDetailRequestValidator()); Must((request, details) => details == null \|\| details.All(detail => detail.AccountId != request.MainAccountId))  .When(x => x.AccountingDocumentDetails != null && x.MainAccountId.HasValue) | The detail lines making up the transaction. |

**Responses**: Created `CashTransactionResponse`: Cash transaction created.

**Business errors** (HTTP 409, match on `errorCode`):

- `CannotInsertDocumentBeforeClosingDate`: The document date is before the closing date.
- `CK_NoCustomerOrSupplierSelectedforAccount`: The selected account requires a linked customer or supplier, but none was provided.
- `CK_NocustomerSelectedforAR`: The selected receivable account requires a linked customer, but none was provided.
- `CK_NoSupplierSelectedforAP`: The selected payable account requires a linked supplier, but none was provided.
- `DocumentmainAccountHasNoAlias`: The selected main account does not have the cash-account alias required by this document type.
- `ExchangeRateDecimalsExceedLimit`: The exchange rate has too many decimal places.
- `PreventSaveDocumentsInFutureDate`: The document date is in the future.

**Notes**

- `mainAccountId` must be an existing account of type `Cash`. A bank account returns `400`.
- Each detail line needs an existing account and an amount above 0, and it cannot use the main account. Otherwise you get `400`.
- You send only the detail lines, which are recorded as credits. The API adds one debit line on the main cash account for their total.
- Without `currencyId`, `exchangeRate` is ignored and the rate is stored as 1.
- With `currencyId`, in an organization that uses multiple currencies, any account whose default foreign currency is different returns `400`.
- An `exchangeRate` with more than 6 decimal places returns `409` with `ExchangeRateDecimalsExceedLimit`.
- If you omit the cost center on a line whose account accepts one, the account's default cost center is used. If the account has no default and the organization requires cost centers, you get `400`, so code defensively.
- A cost center sent for an account that does not accept cost centers is ignored without an error. A customer or supplier sent on a line whose account is not accounts receivable (AR) or accounts payable (AP) is ignored too.
- An AR line without `customerId` or an AP line without `supplierId` returns `400`. A customer or supplier that is not linked to the line's account returns `400` too.
- A `documentDate` in the future returns `409`, whatever the organization's setting for future-dated documents. A date before the closing period returns `409` too.
- The document code is generated from the type `CI` and the main account's alias. A main account with no alias returns `409` with `DocumentmainAccountHasNoAlias`.
- Whether the document is posted depends on an organization setting: it is either posted immediately or left unposted. Code defensively, because unposted documents are left out of GET /v3/journal-entries and of balance calls by default.
- An unknown cost center, customer or supplier id returns `400`.
- `paperNumber` is not checked for duplicates.
- The response contains only `documentCode`.

---

### `POST /v3/cash-out`: Records a cash-out.

Operation `CreateCashOut` · permission `create:cash-transaction`

**Body**: `CashTransactionRequest`

| field | type | default | validation | description |
|---|---|---|---|---|
| `mainAccountId` | `int?` |  | GreaterThan(0) | The main cash account identifier. |
| `documentDate` | `DateTime?` |  | NotNull() | The accounting document date. |
| `paperNumber` | `string` |  |  | The external paper number. |
| `responsibleId` | `int?` |  | GreaterThan(0) .When(x => x.ResponsibleId.HasValue) | The responsible user identifier. |
| `notes` | `string` |  |  | Optional document notes. |
| `currencyId` | `int?` |  | GreaterThan(0) .When(x => x.CurrencyId.HasValue) | The optional document currency identifier. |
| `exchangeRate` | `decimal?` |  | GreaterThan(0m) .When(x => x.ExchangeRate.HasValue) | The exchange rate when a currency is supplied. |
| `accountingDocumentDetails` | `List<CashTransactionDetailRequest>` |  | NotNull() .NotEmpty(); each: SetValidator(new CashTransactionDetailRequestValidator()); Must((request, details) => details == null \|\| details.All(detail => detail.AccountId != request.MainAccountId))  .When(x => x.AccountingDocumentDetails != null && x.MainAccountId.HasValue) | The detail lines making up the transaction. |

**Responses**: Created `CashTransactionResponse`: Cash transaction created.

**Business errors** (HTTP 409, match on `errorCode`):

- `CannotInsertDocumentBeforeClosingDate`: The document date is before the closing date.
- `CK_NoCustomerOrSupplierSelectedforAccount`: The selected account requires a linked customer or supplier, but none was provided.
- `CK_NocustomerSelectedforAR`: The selected receivable account requires a linked customer, but none was provided.
- `CK_NoSupplierSelectedforAP`: The selected payable account requires a linked supplier, but none was provided.
- `DocumentmainAccountHasNoAlias`: The selected main account does not have the cash-account alias required by this document type.
- `ExchangeRateDecimalsExceedLimit`: The exchange rate has too many decimal places.
- `PreventSaveDocumentsInFutureDate`: The document date is in the future.

**Notes**

- The same rules as POST /v3/cash-in apply, with document type `CO`.
- The sides are reversed: your detail lines are recorded as debits, and the API adds one credit line on the main cash account for their total.

## Types

### `CashTransactionDetailRequest`

Request describing a cash transaction detail line.

| field | type | validation | description |
|---|---|---|---|
| `accountId` | `int?` | GreaterThan(0) | The detail account identifier. |
| `costCenterId` | `int?` | GreaterThan(0) .When(x => x.CostCenterId.HasValue) | The optional cost center identifier. |
| `amount` | `decimal` | GreaterThan(0m) | The line amount. |
| `comments` | `string` |  | Optional line comments. |
| `customerId` | `int?` | GreaterThan(0) .When(x => x.CustomerId.HasValue) | The optional customer identifier for receivable accounts. |
| `supplierId` | `int?` | GreaterThan(0) .When(x => x.SupplierId.HasValue) | The optional supplier identifier for payable accounts. |

### `CashTransactionResponse`

Response describing a created cash transaction.

| field | type | description |
|---|---|---|
| `documentCode` | `string` | The generated accounting document code. |