> For the complete documentation index, see [llms.txt](https://ledgera.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ledgera.gitbook.io/api/core/transactions/transaction-creation.md).

# Transaction Creation

Transactions are created in the POST /transaction method, where the user informs the type of transaction and the list of entries and their individual currencies and amounts.

{% hint style="info" %} <mark style="color:blue;">**Important**</mark><mark style="color:blue;">: the currency and amount informed in the first entry are those that will be used in transaction queries</mark>
{% endhint %}

It is possible to optionally inform a custom value for later conciliation by the user using the *external\_id* parameter.

It is also possible to optionally inform a date for a transaction referring to a date other than the creation date in the *settled\_at* parameter. If this parameter is not informed, the system will consider the date when the transaction was created.

It is also possible to optionally inform a parent transaction ID referring to another prior transaction. This parameter can be used later for conciliation purposes by the user.

The system finally allows the user to enter a set of data (metadata) to be persisted in the transaction, entries and journal, and returned during queries.

## Entries <a href="#entries" id="entries"></a>

The list of entries corresponds to the desired entries in the transaction (double entries) and receives the values ​​below for each entry:

| Parameter                     | Data type | Description                                                                                    |
| ----------------------------- | --------- | ---------------------------------------------------------------------------------------------- |
| *entry\_type*                 | *string*  | User-defined field for customer use                                                            |
| *entry\_order*                | *integer* | the order of execution of the entry                                                            |
| *currency*                    | *string*  | currency to be moved at entry                                                                  |
| *amount*                      | *integer* | amount to be moved at entry. The amount, in integer, must respect the decimals of the currency |
| *debit\_balance\_id*          | *uuid*    | balance *id* to be debited                                                                     |
| *debit\_balance\_validation*  | *string*  | type of validation to be performed on the balance to be debited                                |
| *credit\_balance\_id*         | *uuid*    | balance *id* to be credited                                                                    |
| *credit\_balance\_validation* | *string*  | type of validation to be performed on the balance to be credited                               |

### Balance Validation <a href="#balance-validation" id="balance-validation"></a>

Balances are validated at entries (debit or credit) using the reserved words:

| Value            | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| *positive*       | The system will not allow balances to go below zero during transactions |
| *negative*       | The system will not allow balances to go above zero during transactions |
| *no\_validation* | The system will not validate balances during transactions               |

Example of transaction creation:

```json
POST /transaction

{
  "transaction_type": "pix_out",
  "parent_id": "ea355ff5-6a2e-a57e-708c-7ab94e79c7f6",
  "external_id": "our id 1234",
  "settled_at": "2023-06-01",
  "entries": [
    {
      "entry_type": "main_amount",
      "entry_order": 1,
      "currency": "brl",
      "amount": 10000,
      "debit_balance_id": "2874d9c5-e919-8715-b3eb-4ee3440a2fe3",
      "debit_balance_validation": "positive",
      "credit_balance_id": "bb2b0e40-2308-5330-bb6a-6de434493f0e",
      "credit_balance_validation": "positive"
    },
    {
      "entry_type": "fee",
      "entry_order": 2,
      "currency": "brl",
      "amount": 300,
      "debit_balance_id": "9517f941-bf40-41ed-aaff-a52f62a635a3",
      "debit_balance_validation": "positive",
      "credit_balance_id": "d6f8a529-b24e-4031-a763-b6b5ebc2dc60",
      "credit_balance_validation": "positive"
    }
  ],
  "metadata": {
    "key": "value"  
  }
}
```

Response Example:

```json
{
  "id": "96296a5c-0cf4-4025-dbc4-1a53f0a3afc6"
}
```