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

# Script de Economia FiveM — Banco, ATMs e Transações

> Sistema econômico completo para FiveM com banco, carteira, ATMs, transferências entre jogadores e histórico de movimentações financeiras.

O módulo de **Economia** gerencia o dinheiro no seu servidor FiveM. Cada personagem tem uma carteira (dinheiro em mãos) e uma conta bancária, com suporte a transferências, ATMs espalhados pelo mapa e histórico completo de transações.

## Funcionalidades

* Carteira (cash) e conta bancária por personagem
* ATMs localizáveis pelo mapa com blips
* Transferências entre jogadores
* Histórico de transações acessível no banco
* Integração com módulo de Jobs para pagamento de salário
* Imposto configurável sobre transferências
* Limites de saque e transferência diários
* Suporte a múltiplas moedas (ex: fichas de casino)

## Configuração Econômica

Defina os valores iniciais e limites financeiros do servidor no `config.lua`. O campo `transferTax` aceita valores decimais — `0.02` representa 2% de taxa sobre cada transferência entre jogadores.

```lua config.lua theme={null}
Config.Economy = {
    startingCash        = 500,      -- Dinheiro em mãos para novos personagens
    startingBank        = 2500,     -- Saldo bancário inicial
    maxCashCarry        = 10000,    -- Máximo de cash que um personagem pode carregar
    dailyWithdrawLimit  = 50000,    -- Limite de saque bancário por dia
    transferTax         = 0.02,     -- Taxa de transferência (2%); use 0 para desativar
    currency            = 'R$',     -- Símbolo exibido na interface
}
```

## Configuração de ATMs

Adicione ATMs em qualquer local do mapa usando coordenadas do GTA V. O jogador interage com o ATM ao se aproximar. Adicione quantos pontos quiser à lista.

```lua config.lua theme={null}
Config.ATMs = {
    { coords = vector3(247.8,   220.6,  106.3), heading = 340.0 },
    { coords = vector3(-1393.8, -580.9,  30.0), heading = 305.0 },
    { coords = vector3(-2963.5,  481.6,  15.7), heading = 90.0  },
    -- Adicione novos ATMs seguindo o mesmo padrão
}
```

## Integração com Outros Módulos

Controle como o módulo de Economia interage com Jobs e Veículos:

```lua config.lua theme={null}
Config.EconomyIntegration = {
    salaryAccount         = 'bank',   -- Salários de jobs: 'bank' ou 'cash'
    vehiclePurchaseAccount = 'bank',  -- Compra de veículos debita de: 'bank' ou 'cash'
    enableTaxOnSalary     = false,    -- Aplicar imposto de transferência sobre salários?
}
```

## Comandos de Economia

| Comando                            | Permissão        | Descrição                              |
| ---------------------------------- | ---------------- | -------------------------------------- |
| `/bank`                            | Qualquer jogador | Abre a interface do banco mais próximo |
| `/money`                           | Qualquer jogador | Exibe o saldo atual de cash e banco    |
| `/pay [id] [valor]`                | Qualquer jogador | Paga outro jogador em dinheiro em mãos |
| `/addmoney [id] [tipo] [valor]`    | `economy.admin`  | Adiciona dinheiro a um jogador         |
| `/removemoney [id] [tipo] [valor]` | `economy.admin`  | Remove dinheiro de um jogador          |

<Tip>
  Nos comandos administrativos, o parâmetro `[tipo]` aceita `'cash'` para dinheiro em mãos ou `'bank'` para saldo bancário. Exemplo: `/addmoney 1 bank 1000`.
</Tip>

## API — Integrações via Exports e Eventos

### Obter saldo de um jogador (servidor)

```lua theme={null}
local cash = exports['economia']:GetPlayerCash(source)
local bank = exports['economia']:GetPlayerBank(source)
-- Retorna o valor numérico do saldo atual
```

### Adicionar dinheiro a um jogador (servidor)

```lua theme={null}
local success = exports['economia']:AddMoney(source, 'bank', 500)
-- Parâmetros: source, tipo ('cash' ou 'bank'), valor
-- Retorna true em caso de sucesso
```

### Remover dinheiro de um jogador (servidor)

```lua theme={null}
local success = exports['economia']:RemoveMoney(source, 'cash', 200)
-- Retorna false se o jogador não tiver saldo suficiente
```

### Evento disparado após transação (servidor)

```lua theme={null}
AddEventHandler('economia:onTransaction', function(source, tipo, valor, novoSaldo)
    -- tipo: 'deposit', 'withdraw', 'transfer', 'salary'
    print('Transação: ' .. tipo .. ' de R$' .. valor)
end)
```

## Resolução de Problemas

| Problema                          | Causa provável                                      | Solução                                             |
| --------------------------------- | --------------------------------------------------- | --------------------------------------------------- |
| ATM não aparece no mapa           | Coordenadas fora do alcance ou recurso não iniciado | Verifique as coordenadas e reinicie o recurso       |
| Transferência bloqueada           | Limite diário atingido ou saldo insuficiente        | Revise `dailyWithdrawLimit` ou oriente o jogador    |
| Salário não é depositado no banco | `salaryAccount` definido como `'cash'`              | Altere para `'bank'` em `Config.EconomyIntegration` |
| Taxa inesperada em transferências | `transferTax` maior que zero                        | Defina `transferTax = 0` para remover a taxa        |