> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/es/nucleo/cuxial-banking/developers.md).

# Exports y eventos

API pública de Cuxial Banking: exports de servidor para mover dinero, pagar sueldos y cobrar con tarjeta, y sus eventos.

Mueve dinero, deja nóminas, cobra con tarjeta y consulta cuentas desde tus propios recursos. Todos los exports se ejecutan en el servidor.

```lua
exports.cuxial_banking:<Nombre>(...)
```

{% hint style="info" %}
Los importes son números enteros positivos. Los decimales se descartan. Con cero, negativos, valores inválidos o desorbitados, el export devuelve `false`.
{% endhint %}

## Dinero del jugador

### AddMoney

Abona dinero a un personaje, conectado o no.

```lua
exports.cuxial_banking:AddMoney(citizenId, amount, account)
```

| Parámetro   | Tipo   | Descripción                                                      |
| ----------- | ------ | ---------------------------------------------------------------- |
| `citizenId` | string | Identificador del personaje.                                     |
| `amount`    | number | Importe a añadir.                                                |
| `account`   | string | `'bank'`, `'cash'` o `'crypto'`. Opcional; `'bank'` por defecto. |

**Devuelve:** `boolean`.

```lua
exports.cuxial_banking:AddMoney(citizenId, 1500)
```

### RemoveMoney

Cobra dinero a un personaje si tiene suficiente.

```lua
exports.cuxial_banking:RemoveMoney(citizenId, amount, account)
```

Los mismos parámetros que `AddMoney`.

**Devuelve:** `boolean`. `false` cuando el saldo no alcanza.

```lua
if exports.cuxial_banking:RemoveMoney(citizenId, 250, 'bank') then
    -- pagado
end
```

{% hint style="warning" %}
`AddMoney` y `RemoveMoney` no anotan nada en el historial. Añade tú el apunte con `AddTransaction`.
{% endhint %}

### GetAccount

Lee el dinero de un personaje que está conectado.

```lua
local account = exports.cuxial_banking:GetAccount(citizenId)
```

**Devuelve:** `{ citizenid, name, bank, cash }`, o `nil` si el personaje no está conectado.

```lua
local account = exports.cuxial_banking:GetAccount(citizenId)
if account and account.bank >= 5000 then
    -- puede pagarlo
end
```

## Historial

### AddTransaction

Anota un movimiento en el historial de una cuenta.

```lua
exports.cuxial_banking:AddTransaction(identifier, transaction)
```

| Parámetro                         | Tipo   | Descripción                                                                                                                           |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier`                      | string | Identificador del personaje, nombre del trabajo o código de la cuenta compartida.                                                     |
| `transaction.value`               | number | Positivo para entradas, negativo para salidas.                                                                                        |
| `transaction.reason`              | string | Texto que se muestra en el historial. Hasta 255 caracteres.                                                                           |
| `transaction.type`                | string | `'deposit'`, `'withdraw'`, `'transfer'`, `'loan'`, `'card'`, `'fee'` o `'interest'`. Cualquier otro valor se guarda como `'deposit'`. |
| `transaction.sender_name`         | string | Nombre del emisor.                                                                                                                    |
| `transaction.sender_identifier`   | string | Identificador del emisor.                                                                                                             |
| `transaction.receiver_name`       | string | Nombre del receptor.                                                                                                                  |
| `transaction.receiver_identifier` | string | Identificador del receptor.                                                                                                           |
| `transaction.date`                | string | `'YYYY-MM-DD HH:MM:SS'`. Opcional; por defecto, ahora.                                                                                |

**Devuelve:** `boolean`.

```lua
exports.cuxial_banking:AddTransaction(citizenId, {
    value = -250,
    reason = 'Multa de aparcamiento',
    type = 'fee',
    sender_name = 'John Doe',
    sender_identifier = citizenId,
    receiver_name = 'Ayuntamiento',
    receiver_identifier = 'cityhall',
})
```

### GetPlayerTransactions

Devuelve los últimos movimientos de una cuenta.

```lua
local list = exports.cuxial_banking:GetPlayerTransactions(identifier)
```

**Devuelve:** `table[]`. Cada entrada tiene los campos de `AddTransaction`. La longitud está limitada por `MaxTransactionsPerPlayer`.

```lua
for _, tx in ipairs(exports.cuxial_banking:GetPlayerTransactions(citizenId)) do
    print(tx.date, tx.value, tx.reason)
end
```

## Cuentas de empresa

El parámetro `society` es el nombre del trabajo. También se acepta la forma `society_<trabajo>`.

### AddSocietyMoney

```lua
exports.cuxial_banking:AddSocietyMoney(society, amount, reason)
```

| Parámetro | Tipo   | Descripción                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| `society` | string | Nombre del trabajo.                                                          |
| `amount`  | number | Importe a añadir.                                                            |
| `reason`  | string | Opcional. Si se indica, el movimiento se anota en el historial de la cuenta. |

**Devuelve:** `boolean`. `false` cuando la cuenta no existe.

```lua
exports.cuxial_banking:AddSocietyMoney('mechanic', 800, 'Factura de reparación')
```

### RemoveSocietyMoney

```lua
exports.cuxial_banking:RemoveSocietyMoney(society, amount, reason)
```

Los mismos parámetros que `AddSocietyMoney`.

**Devuelve:** `boolean`. `false` cuando la cuenta no existe o el saldo no alcanza.

```lua
if exports.cuxial_banking:RemoveSocietyMoney('police', 500, 'Material') then
    -- pagado desde la cuenta de empresa
end
```

### GetSocietyAccount

```lua
local account = exports.cuxial_banking:GetSocietyAccount(society)
```

**Devuelve:** `{ society, society_name, balance, iban, credit_score, opening_date }`, o `nil` cuando la cuenta no existe.

```lua
local account = exports.cuxial_banking:GetSocietyAccount('police')
print(account and account.balance or 0)
```

## Nóminas

### AddPaycheck

Deja una nómina para que un personaje la cobre en una sucursal. Así llegan los sueldos al banco: por sí solo no los crea.

```lua
exports.cuxial_banking:AddPaycheck(citizenId, sourceKey, sourceName, amount, status)
```

| Parámetro    | Tipo   | Descripción                                               |
| ------------ | ------ | --------------------------------------------------------- |
| `citizenId`  | string | Identificador del personaje.                              |
| `sourceKey`  | string | De dónde viene, normalmente el nombre del trabajo.        |
| `sourceName` | string | Nombre que ve el jugador.                                 |
| `amount`     | number | Importe de la nómina.                                     |
| `status`     | string | `'ready'` o `'pending'`. Opcional; `'ready'` por defecto. |

**Devuelve:** `boolean`.

```lua
exports.cuxial_banking:AddPaycheck(citizenId, 'police', 'Departamento de Policía', 500)
```

## Tarjetas

### ChargeCard

Cobra en una tarjeta que el jugador lleva encima. Sirve para pagos con tarjeta en tiendas.

```lua
local result = exports.cuxial_banking:ChargeCard(source, cardNumber, pin, amount, reason)
```

| Parámetro    | Tipo             | Descripción                                                                               |
| ------------ | ---------------- | ----------------------------------------------------------------------------------------- |
| `source`     | number           | Id de servidor del jugador que paga. Debe llevar la tarjeta.                              |
| `cardNumber` | string           | Número de la tarjeta.                                                                     |
| `pin`        | string \| number | PIN que ha escrito el jugador.                                                            |
| `amount`     | number           | Importe a cobrar. Limitado por `cards.posMaxCharge` y por el límite diario de la tarjeta. |
| `reason`     | string           | Nombre del comercio, que se muestra en el historial. Opcional.                            |

**Devuelve:** `{ success, message, cardHolder, last4 }`. `message` solo viene si falla; `cardHolder` y `last4` solo si se cobra.

```lua
local result = exports.cuxial_banking:ChargeCard(source, cardNumber, pin, 120, 'Supermercado')
if not result.success then
    print(result.message)
end
```

### RefundCard

Devuelve un cobro al titular de la tarjeta.

```lua
exports.cuxial_banking:RefundCard(cardNumber, amount, reason)
```

**Devuelve:** `boolean`. El dinero va siempre al titular de la tarjeta, nunca a quien pagó con ella.

```lua
exports.cuxial_banking:RefundCard(cardNumber, 120, 'Supermercado')
```

### GetPlayerCards

Lista las tarjetas que lleva un jugador.

```lua
local cards = exports.cuxial_banking:GetPlayerCards(source)
```

**Devuelve:** `table[]`. Cada entrada tiene `cardNumber`, `cardHolder`, `cardHolderCitizenId`, `cardHolderIBAN`, `cardType`, `cardTypeLabel`, `dailyLimit`, `accountType`, `status`, `expiryDate`, `slot` e `item`.

```lua
for _, card in ipairs(exports.cuxial_banking:GetPlayerCards(source)) do
    if card.status == 'active' then
        -- ofrecerla como método de pago
    end
end
```

## Ajustes

### getSetting

Lee una sección de los ajustes en vivo, tal como se está usando en ese momento.

```lua
local cards = exports.cuxial_banking:getSetting('config.cards')
```

| Parámetro | Tipo   | Descripción                                                                                                                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string | `'config.general'`, `'config.accounts'`, `'config.cards'`, `'config.loans'`, `'config.savings'`, `'config.cheques'`, `'config.rewards'`, `'config.creditScore'`, `'config.atm'`, `'config.admin'` o `'config.logs'`. |

**Devuelve:** `table`, o `nil` si la sección no existe.

```lua
local general = exports.cuxial_banking:getSetting('config.general')
print(general.currency)
```

## Informe de riqueza

La pestaña Ciudadanos del panel de staff suma todo lo que tiene un personaje. Tu recurso puede añadir sus propias líneas.

### RegisterWealthProvider

```lua
exports.cuxial_banking:RegisterWealthProvider(name, fn)
```

| Parámetro | Tipo     | Descripción                                                           |
| --------- | -------- | --------------------------------------------------------------------- |
| `name`    | string   | Nombre único de la fuente.                                            |
| `fn`      | function | Recibe el identificador del personaje y devuelve una lista de líneas. |

Cada línea:

| Campo    | Tipo   | Descripción                                                                                                                                                                                               |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`    | string | Identificador de la línea.                                                                                                                                                                                |
| `label`  | string | Texto que se muestra en el panel.                                                                                                                                                                         |
| `amount` | number | Valor. Las líneas a cero se descartan.                                                                                                                                                                    |
| `kind`   | string | `'asset'` suma al patrimonio. `'transit'` también suma: dinero en camino. `'liability'` resta. `'control'` se muestra sin sumar: fondos que el personaje maneja pero no son suyos. `'asset'` por defecto. |
| `detail` | table  | Opcional. Valores extra de texto, número o booleano.                                                                                                                                                      |

**Devuelve:** `boolean`. `false` cuando otro recurso ya registró ese nombre.

```lua
exports.cuxial_banking:RegisterWealthProvider('myshop', function(citizenId)
    return {
        { key = 'till', label = 'Caja de la tienda', amount = 3200, kind = 'asset' },
    }
end)
```

La fuente se retira sola cuando tu recurso se detiene.

### UnregisterWealthProvider

```lua
exports.cuxial_banking:UnregisterWealthProvider(name)
```

**Devuelve:** `boolean`. Solo el recurso que registró una fuente puede retirarla.

## Eventos

### cuxial\_banking:client:OpenAtm

Evento de cliente. Abre el cajero al jugador local desde tu propio recurso, por ejemplo desde un prop de cajero personalizado.

| Parámetro | Tipo    | Descripción                                                          |
| --------- | ------- | -------------------------------------------------------------------- |
| `coords`  | vector3 | Posición del cajero. Opcional; por defecto, la posición del jugador. |

```lua
TriggerEvent('cuxial_banking:client:OpenAtm', GetEntityCoords(atmEntity))
```

El jugador sigue necesitando una tarjeta activa y su PIN, y debe mantenerse a menos de `atmDistance` de esas coordenadas.

### cuxial\_banking:settingsApplied

Evento local, en el servidor y en cada cliente. Se dispara cuando una sección de ajustes se carga o se cambia desde el panel de staff.

| Parámetro | Tipo   | Descripción                                            |
| --------- | ------ | ------------------------------------------------------ |
| `id`      | string | Sección que ha cambiado, por ejemplo `'config.cards'`. |

```lua
-- en el servidor
AddEventHandler('cuxial_banking:settingsApplied', function(id)
    if id == 'config.cards' then
        local cards = exports.cuxial_banking:getSetting('config.cards')
    end
end)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/es/nucleo/cuxial-banking/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.