> 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/vehiculos/cuxial-gasstations/developers.md).

# Exports y eventos

API pública de Cuxial Gas Stations: exports para conectar un script de combustible, leer precios y reputación y pedir un lavado.

Conecta tu script de combustible con los depósitos de las gasolineras, lee precios, promociones y reputación, o envía los avisos del dueño a otro recurso. Cuxial Fuel ya usa estos exports; solo los necesitas para tus propias integraciones.

Los ids de gasolinera son las claves de `data/stations.lua`, como `gas_station_1`.

## Exports de servidor

### FindStation

Devuelve la gasolinera a la que pertenece una posición. Una posición pertenece a una gasolinera cuando está dentro de su esfera `pumps`.

```lua
local stationId = exports.cuxial_gasstations:FindStation(coords)
```

| Parámetro | Tipo             | Descripción                                           |
| --------- | ---------------- | ----------------------------------------------------- |
| `coords`  | vector3 \| table | Posición con `x`, `y` y `z`, normalmente el surtidor. |

**Devuelve:** `string`, o `nil` cuando la posición está fuera de todas las gasolineras.

```lua
local stationId = exports.cuxial_gasstations:FindStation(GetEntityCoords(pump))
```

### GetFuelPrices

Precios y stock de todos los combustibles de una gasolinera, con los límites del administrador y el happy hour en curso ya aplicados.

```lua
local data = exports.cuxial_gasstations:GetFuelPrices(stationId, countVisit)
```

| Parámetro    | Tipo    | Descripción                                                                                                           |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `stationId`  | string  | Id de la gasolinera.                                                                                                  |
| `countVisit` | boolean | Suma una visita a las estadísticas de la gasolinera. Por defecto `true`; pasa `false` cuando solo releas los precios. |

**Devuelve:** `nil` cuando la gasolinera no existe o no tiene dueño. Si no, una tabla:

| Campo    | Tipo  | Descripción                                                                                                       |
| -------- | ----- | ----------------------------------------------------------------------------------------------------------------- |
| `prices` | table | Precio por litro o kWh, por id de combustible. `0` significa que el dueño no ha fijado precio.                    |
| `stock`  | table | Litros en el depósito para los combustibles; `true` o `false` para los cargadores eléctricos (desbloqueado o no). |

```lua
local data = exports.cuxial_gasstations:GetFuelPrices('gas_station_1', false)
if data then
    print(data.prices.regular, data.stock.regular)
end
```

### GetFuel

Forma corta solo para `regular`.

```lua
local stock, price = exports.cuxial_gasstations:GetFuel(stationId, countVisit)
```

| Parámetro    | Tipo    | Descripción                                    |
| ------------ | ------- | ---------------------------------------------- |
| `stationId`  | string  | Id de la gasolinera.                           |
| `countVisit` | boolean | `true` suma una visita. Por defecto no cuenta. |

**Devuelve:** `stock` (litros) y `price` (por litro), o `nil` cuando la gasolinera no existe o no tiene dueño.

### SellFuel

Comunica una venta. Resta los litros del depósito y suma el dinero a la caja.

```lua
local sold = exports.cuxial_gasstations:SellFuel(stationId, fuel, paid, liters, kind, src)
```

| Parámetro   | Tipo   | Descripción                                                                                                             |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `stationId` | string | Id de la gasolinera.                                                                                                    |
| `fuel`      | string | Id de combustible de `fuels` en el config.                                                                              |
| `paid`      | number | Lo que pagó el cliente.                                                                                                 |
| `liters`    | number | Litros vendidos, o kWh en una carga.                                                                                    |
| `kind`      | string | `'pump'`, `'can'` (bidón) o `'charge'` (eléctrico).                                                                     |
| `src`       | number | Id de servidor del comprador. Opcional. Con él, el comprador puede ganar un bono de lavado y se le pide una valoración. |

**Devuelve:** `boolean`. `false` cuando la gasolinera tiene dueño y le falta stock o el cargador, o el id de combustible no vale: devuelve el dinero al cliente. `true` en cualquier otro caso, incluidas las gasolineras sin dueño.

```lua
local stationId = exports.cuxial_gasstations:FindStation(pumpCoords)
if stationId and not exports.cuxial_gasstations:SellFuel(stationId, 'regular', 120, 40, 'pump', source) then
    -- sin stock: devuelve el dinero
end
```

### RefundFuel

Devuelve al depósito los litros no usados y saca el reembolso de la caja.

```lua
local refunded = exports.cuxial_gasstations:RefundFuel(stationId, fuel, refund, liters, src)
```

| Parámetro   | Tipo   | Descripción                                                                                           |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `stationId` | string | Id de la gasolinera.                                                                                  |
| `fuel`      | string | Id de combustible.                                                                                    |
| `refund`    | number | Importe a devolver al cliente.                                                                        |
| `liters`    | number | Litros pagados y no servidos.                                                                         |
| `src`       | number | Id de servidor del comprador. Opcional. Anula un bono de lavado que ya no llega a los litros mínimos. |

**Devuelve:** `number`, el importe que de verdad sale de la caja. Puede ser menor que `refund` cuando la caja no llega, o `0`. En una gasolinera sin dueño devuelve `refund` tal cual.

### GetPromos

Promociones de una gasolinera, para pantallas públicas como un cartel de precios.

```lua
local promos = exports.cuxial_gasstations:GetPromos(stationId)
```

**Devuelve:** `nil` cuando la gasolinera no existe. Si no, una tabla:

| Campo     | Tipo     | Descripción                                                                                                                                                                                   |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`   | string   | Nombre por defecto de la gasolinera.                                                                                                                                                          |
| `fuelPct` | number   | Descuento actual en combustible, en porcentaje.                                                                                                                                               |
| `washPct` | number   | Descuento actual en lavados, en porcentaje.                                                                                                                                                   |
| `live`    | table\[] | Promociones activas ahora. Un happy hour tiene `kind = 'happy_hour'`, `pct`, `applies` y `endsIn` (segundos). Un bono tiene `kind = 'fuel_voucher'`, `minLiters`, `service` y `validMinutes`. |
| `next`    | table    | Próximo happy hour, con `pct`, `applies` y `startsIn` (segundos). No viene cuando no hay ninguno hoy ni mañana.                                                                               |

### GetReputation

```lua
local rep = exports.cuxial_gasstations:GetReputation(stationId)
```

**Devuelve:** `nil` cuando la gasolinera no existe o el módulo de reputación está apagado. Si no, una tabla:

| Campo      | Tipo   | Descripción                                             |
| ---------- | ------ | ------------------------------------------------------- |
| `avg`      | number | Nota de 1 a 5.                                          |
| `count`    | number | Valoraciones recientes que cuentan.                     |
| `factor`   | number | Multiplicador que se aplica al tráfico de clientes NPC. |
| `bonusPct` | number | Descuento extra de proveedor, en porcentaje.            |

### RequestMobileWash

Abre una solicitud de detailing a domicilio en nombre de un jugador, como hace `/detailing` cuando el jugador confirma.

```lua
local result = exports.cuxial_gasstations:RequestMobileWash(src, service, netId)
```

| Parámetro | Tipo   | Descripción                         |
| --------- | ------ | ----------------------------------- |
| `src`     | number | Id de servidor del cliente.         |
| `service` | string | `'rinse'`, `'foam'` o `'wax'`.      |
| `netId`   | number | Id de red del vehículo del cliente. |

**Devuelve:** una tabla con `ok` (boolean), `id` y `quote` si sale bien, o `error` (un código como `module_disabled`) si falla.

```lua
local result = exports.cuxial_gasstations:RequestMobileWash(source, 'foam', netId)
if not result.ok then print(result.error) end
```

### RegisterNoticeProvider

Recibe en tu recurso cada aviso al dueño, por ejemplo para reenviarlo a otro sistema de mensajería.

```lua
local ok = exports.cuxial_gasstations:RegisterNoticeProvider(name, fn)
```

| Parámetro | Tipo     | Descripción                                             |
| --------- | -------- | ------------------------------------------------------- |
| `name`    | string   | Nombre único, de hasta 40 caracteres.                   |
| `fn`      | function | Se llama con una tabla `notice` por cada aviso enviado. |

Campos de `notice`:

| Campo          | Tipo   | Descripción                                                                                                        |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `citizenid`    | string | Identificador del dueño de la gasolinera.                                                                          |
| `station`      | string | Id de la gasolinera.                                                                                               |
| `stationLabel` | string | Nombre de la gasolinera.                                                                                           |
| `kind`         | string | `low_stock`, `mobile_wait`, `mobile_missed`, `npc_cap`, `rental`, `daily`, `reputation`, `abandon_risk` o `spill`. |
| `title`        | string | Título, ya traducido.                                                                                              |
| `text`         | string | Texto, ya traducido.                                                                                               |
| `at`           | number | Hora en milisegundos.                                                                                              |

**Devuelve:** `boolean`. El proveedor se quita solo cuando tu recurso se detiene.

```lua
exports.cuxial_gasstations:RegisterNoticeProvider('my_mail', function(notice)
    print(notice.stationLabel, notice.kind, notice.text)
end)
```

### UnregisterNoticeProvider

```lua
exports.cuxial_gasstations:UnregisterNoticeProvider(name)
```

### Spill

Para scripts de combustible. Crea un charco de combustible cuando un vehículo arranca con la boquilla puesta. La gasolinera decide si hay derrame y cuántos litros pierde.

```lua
local spilled = exports.cuxial_gasstations:Spill(stationId, coords, src, liters, fuel, netId)
```

| Parámetro   | Tipo    | Descripción                               |
| ----------- | ------- | ----------------------------------------- |
| `stationId` | string  | Id de la gasolinera.                      |
| `coords`    | vector3 | Posición del suelo bajo la boquilla.      |
| `src`       | number  | Id de servidor del jugador que repostaba. |
| `liters`    | number  | Litros pagados y no servidos.             |
| `fuel`      | string  | Id de combustible.                        |
| `netId`     | number  | Id de red del vehículo.                   |

**Devuelve:** `number`, los litros que no vuelven al depósito. `0` significa que no se creó ningún charco.

## Exports de cliente

### FindStation

Igual que el export de servidor.

```lua
local stationId = exports.cuxial_gasstations:FindStation(GetEntityCoords(cache.ped))
```

### IsWaxed

Dice si un vehículo tiene una capa de cera activa.

```lua
local waxed = exports.cuxial_gasstations:IsWaxed(vehicle)
```

| Parámetro | Tipo   | Descripción                        |
| --------- | ------ | ---------------------------------- |
| `vehicle` | number | Handle de la entidad del vehículo. |

**Devuelve:** `boolean`.

## Eventos

Cuxial Gas Stations no expone eventos para otros recursos. Sus eventos internos se validan en el servidor y no están pensados para dispararse desde fuera.


---

# 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/vehiculos/cuxial-gasstations/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.