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

# Solicitar dispersión

> Solicita la dispersión del balance a una cuenta bancaria registrada de tu empresa.

Dispersa el balance de tu cuenta OnePay a una cuenta bancaria registrada de tu empresa.

Ambos parámetros son opcionales:

* Si no envías `amount`, se dispersa el **balance completo**.
* Si no envías `account_id`, se usa la **cuenta bancaria principal** (fundable) de tu empresa.

<Note>
  La cuenta bancaria debe pertenecer directamente a tu empresa. Cuentas de tipo PSE no son elegibles como cuenta principal.
  Si envías un `account_id` que pertenece a un cliente o invitado, recibirás un error `company_account_not_found`.
</Note>

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="amount" type="number" placeholder="500000">
  Monto a dispersar en pesos (COP). Mínimo \$10.000. Si no se envía, se dispersa el balance completo.
</ParamField>

<ParamField body="account_id" type="string" placeholder="9d0ac58c-2226-4f1c-b305-15e6dc3b47f6">
  ID de la cuenta bancaria destino. Debe pertenecer a tu empresa (no a un cliente o invitado). Si no se envía, se usa la cuenta principal. [Aprende a registrar cuentas](/client/accounts/create).
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="Balance completo">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab title="Monto específico">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{"amount": 500000}'
    ```
  </Tab>

  <Tab title="Cuenta específica">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{"amount": 500000, "account_id": "9d0ac58c-2226-4f1c-b305-15e6dc3b47f6"}'
    ```
  </Tab>
</Tabs>

### Errores

| Código | Nombre                      | HTTP | Descripción                                                |
| ------ | --------------------------- | ---- | ---------------------------------------------------------- |
| 10500  | `balance_is_empty`          | 401  | El saldo está vacío                                        |
| 10501  | `insufficient_funds`        | 401  | El monto solicitado supera el balance disponible           |
| 10809  | `company_account_not_found` | 422  | No se encontró cuenta bancaria o no pertenece a tu empresa |

<ResponseExample>
  ```json 204 theme={null}
  (No Content)
  ```

  ```json 401 theme={null}
  {
    "message": "Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.",
    "code": 10500,
    "code_name": "balance_is_empty"
  }
  ```

  ```json 401 theme={null}
  {
    "message": "No tienes fondos suficientes para hacer está operación.",
    "code": 10501,
    "code_name": "insufficient_funds"
  }
  ```

  ```json 422 theme={null}
  {
    "message": "No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance.",
    "code": 10809,
    "code_name": "company_account_not_found"
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>