Integración

Integración y API

Esta página documenta la superficie pública soportada para conectar otros recursos con RC Billing. Los callbacks NUI y los eventos internos pueden cambiar entre versiones; no deben utilizarse como API externa.

Export de servidor CreateInvoice

Nombre completo:

exports['rc-billing']:CreateInvoice(data)

La llamada es síncrona y debe hacerse desde código de servidor. Devuelve una tabla con success, un mensaje y, cuando se crea correctamente, invoiceId.

Campos de entrada

Campo	Tipo	Obligatorio	Descripción
creatorSource	number	Sí	Server ID conectado del personaje emisor.
recipientSource	number	Condicional	Server ID conectado del destinatario.
recipientIdentifier	string	Condicional	Identificador persistente del destinatario.
recipientDNI	string	Condicional	Alias de recipientIdentifier.
recipientName	string	Condicional	Nombre cuando no se usa recipientSource.
amount	number	Sí	Importe positivo, sujeto a límites.
description	string	Sí	Entre 3 y 255 caracteres.
category	string	No	ID de categoría; predeterminado service.
source	string	No	personal o trabajo del emisor.
dueDays	number	No	Días hasta vencimiento.
resource	string	No	Nombre del recurso originador para auditoría.

Debes proporcionar una de estas parejas:

• recipientSource, mientras el destinatario está conectado.

• recipientIdentifier y recipientName para un destinatario persistente.

• recipientDNI y recipientName como alias del caso anterior.

Cuando existe recipientSource, el servidor obtiene identificador y nombre desde el framework e ignora valores de identidad aportados por el llamador.

Respuesta

Correcta

{
    success = true,
    invoiceId = 1842,
    message = 'Factura #1842 creada correctamente.'
}

Fallida

{
    success = false,
    message = 'Descripción demasiado corta.'
}

No dependas del texto de message para lógica. Está localizado. Usa success y registra el mensaje para diagnóstico.

Ejemplo personal

RegisterNetEvent('my-resource:server:billPlayer', function(targetSource, amount, reason)
    local src = source

    local result = exports['rc-billing']:CreateInvoice({
        creatorSource = src,
        recipientSource = tonumber(targetSource),
        amount = tonumber(amount),
        description = tostring(reason),
        category = 'service',
        source = 'personal',
        dueDays = 7,
        resource = GetCurrentResourceName()
    })

    if not result.success then
        print(('[my-resource] Invoice failed for source %s: %s'):format(src, result.message))
        return
    end

    print(('[my-resource] Created invoice #%s'):format(result.invoiceId))
end)

El export vuelve a comprobar Config.AllowPersonalInvoices y ACE. No permite saltarse la política del recurso.

Ejemplo de empresa

local result = exports['rc-billing']:CreateInvoice({
    creatorSource = source,
    recipientSource = customerSource,
    amount = 3200,
    description = 'Reparación completa del motor',
    category = 'repair',
    source = 'mechanic',
    dueDays = 3,
    resource = GetCurrentResourceName()
})

El trabajo actual del emisor debe coincidir con source, estar en Config.CompanyJobs y alcanzar minRank. El export calcula comisión y sociedad desde la configuración; el recurso integrador no debe calcularlas.

Ejemplo con destinatario desconectado

local result = exports['rc-billing']:CreateInvoice({
    creatorSource = source,
    recipientIdentifier = citizenId,
    recipientName = characterName,
    amount = 500,
    description = 'Tasa administrativa',
    category = 'tax',
    source = 'personal',
    resource = GetCurrentResourceName()
})

El export guarda la factura, pero no puede abrir el aviso interactivo a un jugador desconectado. El receptor la verá en su historial y recibirá un recordatorio al conectarse.

La factura se crea como awaiting_acceptance. El destinatario debe aceptarla para que pase a pending y pueda pagarse.

Recomendaciones de seguridad

No conectes directamente un evento de cliente al export sin validar el contexto de tu propio recurso. Aunque RC Billing valida permisos e importes, tu integración debe decidir cuándo una acción de gameplay autoriza facturar.

Evita este patrón:

-- No recomendado: el cliente controla todos los datos sin contexto de gameplay.
RegisterNetEvent('my-resource:bill', function(data)
    exports['rc-billing']:CreateInvoice(data)
end)

Prefiere construir el payload en servidor usando datos confiables:

RegisterNetEvent('mechanic:server:finishRepair', function(orderId, customerSource)
    local src = source
    local order = ActiveRepairOrders[orderId]
    if not order or order.mechanicSource ~= src then return end

    exports['rc-billing']:CreateInvoice({
        creatorSource = src,
        recipientSource = customerSource,
        amount = order.serverCalculatedPrice,
        description = order.invoiceDescription,
        category = 'repair',
        source = 'mechanic',
        resource = GetCurrentResourceName()
    })
end)

Compatibilidad de versiones

La API pública estable de la versión actual contiene únicamente CreateInvoice. Si una versión futura añade exports, quedarán registrados aquí y en CHANGELOG.md.

Para detectar fallos sin acoplarte al idioma:

local ok, result = pcall(function()
    return exports['rc-billing']:CreateInvoice(payload)
end)

if not ok then
    print(('[integration] rc-billing export unavailable: %s'):format(result))
elseif not result.success then
    print(('[integration] rc-billing rejected invoice: %s'):format(result.message))
end

Comprueba que GetResourceState('rc-billing') == 'started' si tu integración puede arrancar antes que este recurso.