> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Crear un Saldo > Utilice este endpoint para agregar nuevos saldos a una cuenta. ## OpenAPI ````yaml es/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances openapi: 3.1.0 info: title: API de Midaz Ledger description: >- Referencia completa de la API para los servicios de Midaz Ledger, incluyendo gestión de organizaciones, operaciones de ledger, activos, segmentos, portafolios, cuentas, tipos de cuenta, transacciones, operaciones, saldos, rutas de operación, rutas de transacción e índices de metadatos. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API - name: Holders API - name: Instruments API - name: Billing Packages API - name: Packages API - name: Billing Calculation API - name: Estimation API - name: Encryption API - name: Protection API - name: Asset Rates API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances: post: tags: - Balances API summary: Crear un Saldo description: Utilice este endpoint para agregar nuevos saldos a una cuenta. parameters: - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/AccountId' requestBody: content: application/json: schema: type: object properties: key: type: string maxLength: 100 description: >- El identificador único del saldo en el contexto de la cuenta. No debe contener espacios en blanco. El valor `"overdraft"` está reservado para saldos companion gestionados por el sistema y no puede ser usado aquí. allowSending: type: boolean description: >- Si es verdadero, indica que el saldo puede ser utilizado para enviar transacciones. allowReceiving: type: boolean description: >- Si es verdadero, indica que el saldo puede ser utilizado para recibir transacciones. direction: type: string enum: - credit - debit default: credit description: >- La dirección contable del saldo. `credit` (predeterminado) para saldos que crecen en crédito; `debit` para saldos que crecen en débito. Definida en la creación e inmutable. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Configuración opcional por saldo. Use esto para habilitar overdraft y definir su límite. required: - key examples: standard: summary: Saldo estándar value: key: settlement allowSending: true allowReceiving: true overdraft-enabled: summary: Saldo con overdraft limitado value: key: checking allowSending: true allowReceiving: true direction: credit settings: allowOverdraft: true overdraftLimitEnabled: true overdraftLimit: '5000.00' responses: '201': description: >- Indica que la solicitud fue exitosa y la respuesta contiene los datos esperados. content: application/json: schema: $ref: '#/components/schemas/GetBalanceResponse' example: id: 019c96a0-0c0d-7915-84b9-e497bfee9916 organizationId: 019c96a0-0a98-7287-9a31-786e0809c769 ledgerId: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 alias: customer-brl-1 key: checking assetCode: BRL available: '0' onHold: '0' version: 1 accountType: deposit allowSending: true allowReceiving: true direction: credit overdraftUsed: '0' settings: allowOverdraft: true overdraftLimitEnabled: true overdraftLimit: '5000.00' balanceScope: transactional position: available: '0' onHold: '0' overdraftLimitAvailable: '5000.00' createdAt: '2026-02-25T21:06:37.197596Z' updatedAt: '2026-02-25T21:06:38.420934Z' deletedAt: null headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0124: $ref: '#/components/examples/Error0124' Error0170: $ref: '#/components/examples/Error0170' Error0171: $ref: '#/components/examples/Error0171' Error0172: $ref: '#/components/examples/Error0172' headers: {} '401': description: No autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Prohibido content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0007: $ref: '#/components/examples/Error0007' headers: {} '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0123: $ref: '#/components/examples/Error0123' headers: {} '500': description: Error Interno del Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: ContentType: name: Content-Type in: header description: >- El tipo de medio del recurso. El valor recomendado es `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: Un identificador único utilizado para rastrear y seguir cada solicitud. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > Token JWT bearer para autenticación. Requerido cuando `PLUGIN_AUTH_ENABLED=true` (obligatorio en despliegues multiinquilino). Opcional en el modo OSS de inquilino único predeterminado. Formato: `Bearer ` OrganizationId: name: organization_id in: path description: El identificador único de la Organización asociada al Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: El identificador único del Ledger asociado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid AccountId: name: account_id in: path description: El identificador único de la cuenta. required: true example: 019c96a0-0c0c-7221-8cf3-13313fb60081 schema: type: string format: uuid schemas: BalanceSettings: type: object description: >- Configuración opcional por saldo que controla el comportamiento de overdraft y el alcance del saldo. properties: allowOverdraft: type: boolean description: >- Cuando `true`, el saldo puede ser debitado más allá de los fondos disponibles. Por defecto `false`. overdraftLimitEnabled: type: boolean description: >- Cuando `true`, debe informarse `overdraftLimit` — el saldo puede quedar negativo hasta ese valor. Cuando `false` con `allowOverdraft` `true`, el overdraft es ilimitado. overdraftLimit: type: string description: >- Monto máximo de overdraft como string decimal (ej., `"5000.00"`). Obligatorio cuando `overdraftLimitEnabled` es `true` y debe ser mayor que cero. Omita cuando el overdraft es ilimitado. balanceScope: type: string enum: - transactional - internal description: >- Alcance gestionado por el sistema. `transactional` es el predeterminado; `internal` marca saldos companion gestionados por el sistema (como el companion de overdraft) y bloquea operaciones directas de usuarios. GetBalanceResponse: type: object properties: id: type: string description: El identificador único del Saldo. organizationId: type: string format: uuid description: El identificador único de la Organización. ledgerId: type: string description: El identificador único del Ledger. format: uuid accountId: type: string description: El identificador único de la Cuenta. format: uuid alias: type: string description: El alias de la cuenta utilizada en la operación. key: type: string description: El identificador único del saldo en el contexto de la cuenta. assetCode: type: string description: El nombre del activo utilizado en la operación. available: type: string description: Saldo disponible anterior. onHold: type: string description: Monto retenido/reservado. version: type: integer description: Versión del saldo, que se actualiza con cada transacción. accountType: type: string description: El tipo de cuenta. allowSending: type: boolean description: >- Si es verdadero, indica que el saldo puede ser utilizado para enviar transacciones. allowReceiving: type: boolean description: >- Si es verdadero, indica que el saldo puede ser utilizado para recibir transacciones. direction: type: string enum: - credit - debit description: >- La dirección contable del saldo. Saldos `credit` crecen en crédito y disminuyen en débito; saldos `debit` crecen en débito y disminuyen en crédito. Definida en la creación e inmutable. overdraftUsed: type: string description: >- La cantidad de overdraft actualmente consumida por este saldo, como string decimal. Siempre no negativa; `"0"` cuando el saldo no tiene overdraft activo. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Configuración opcional por saldo (overdraft, alcance). `null` para saldos legados sin configuraciones personalizadas. position: type: object readOnly: true description: >- Vista computada del estado del saldo en el momento de la respuesta. Siempre presente; nunca persistida. Recalculada a partir de `available`, `onHold`, `overdraftUsed` y `settings` en cada lectura. properties: available: type: string readOnly: true description: >- Monto neto disponible para gastar como string decimal. Igual a `balance.available` menos `overdraftUsed`. Negativo cuando el overdraft está activo. onHold: type: string readOnly: true description: >- Refleja `balance.onHold`. Fondos reservados por operaciones pendientes. overdraftLimitAvailable: type: string readOnly: true description: >- Margen restante de overdraft como string decimal. `"0"` cuando el overdraft está deshabilitado. Omitido completamente cuando el overdraft es ilimitado (`allowOverdraft: true` y `overdraftLimitEnabled: false`). Si no, igual a `overdraftLimit` menos `overdraftUsed`. createdAt: type: string format: date-time description: Fecha y hora de creación (UTC). updatedAt: type: string format: date-time description: Fecha y hora de la última actualización (UTC). deletedAt: type: - string - 'null' format: date-time description: Fecha y hora de la eliminación lógica, si aplica (UTC). metadata: $ref: '#/components/schemas/Metadata' ErrorFormat: type: object description: El mensaje de error de respuesta. required: - code - title - message properties: code: type: string description: Un identificador único y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientación detallada para resolver el error. entityType: type: string description: >- El tipo de entidad a la que se refiere el error (p. ej. organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Información adicional sobre los campos que causaron el error. Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- Un objeto que contiene pares clave-valor para agregar como metadatos, donde el campo `name` es la clave y el campo `value` es el valor. Por ejemplo, para agregar un Centro de Costo, use `'costCenter': 'BR_11101997'`. **Restricciones:** las claves deben tener como máximo 100 caracteres; los valores de cadena de texto, como máximo 2000 caracteres. No se permiten objetos anidados (los valores deben ser cadena de texto, número o booleano), la estructura no puede exceder una profundidad máxima de 10, y se permite un máximo de 100 claves. examples: Error0124: value: code: '0124' title: Additional Balance Creation Not Allowed message: Additional balances are not allowed for external account type. summary: Additional Balance Creation Not Allowed Error0170: summary: Reserved Balance Key value: code: '0170' title: Reserved Balance Key message: >- The balance key provided is reserved for system use (e.g., `overdraft`). Please choose a different key. Error0171: summary: Invalid Balance Direction value: code: '0171' title: Invalid Balance Direction message: >- The balance direction provided is not valid. Accepted values are `credit` and `debit`. Error0172: summary: Invalid Balance Settings value: code: '0172' title: Invalid Balance Settings message: >- The balance settings payload failed validation. Check that `overdraftLimit` is present and positive when `overdraftLimitEnabled` is true, and absent when it is false. Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0007: value: code: '0007' title: Entity Not Found message: >- No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage. summary: Entity Not Found Error0123: value: code: '0123' title: Duplicated Alias Key Value Error message: >- An account alias with the specified key value already exists for this organization and ledger. Please use a different key value. summary: Duplicated Alias Key Value Error Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````