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

# API de proveedores

> Referencia de los exports de registro de proveedores de servidor y cliente.

La versión actual de la API de proveedores es `1`. Los nombres de proveedor
deben estar en minúsculas, tener como máximo 64 caracteres y contener solo
letras, dígitos, `_`, `.` o `-`. Las prioridades deben ser números finitos entre
`-100000` y `100000`.

## Registrar un proveedor de servidor

```lua theme={null}
local ok, errorMessage = exports.humalike:RegisterProvider(domain, descriptor)
```

`domain` es `player`, `inventory`, `dispatch` o `actions`. El registro debe
hacerse desde un recurso externo. Devuelve `true` si tiene éxito o `false` más
un motivo estable y legible cuando el descriptor es rechazado.

Todo descriptor requiere:

| Campo        | Tipo               | Descripción                                                                                   |
| ------------ | ------------------ | --------------------------------------------------------------------------------------------- |
| `name`       | string             | Nombre del proveedor usado por su convar de selección.                                        |
| `apiVersion` | number             | Debe ser `1`.                                                                                 |
| `priority`   | number             | En `auto` gana la prioridad disponible más alta.                                              |
| `Available`  | function, opcional | Devuelve `true` cuando las dependencias están listas; opcionalmente devuelve `false, reason`. |

### Descriptor de jugador

| Callback                             | Obligatorio | Contrato                                                                                                             |
| ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `GetCharacterId(source)`             | Sí          | Devuelve un id estable del personaje activo o `nil`.                                                                 |
| `GetCharacterName(source)`           | Sí          | Devuelve el nombre visible del personaje activo o `nil`.                                                             |
| `IsCharacterLoaded(source)`          | Sí          | Devuelve exactamente `true` cuando el estado de juego está listo.                                                    |
| `HasJob(source, names, requireDuty)` | No          | Devuelve exactamente `true` cuando coincide uno de los trabajos solicitados y se cumplen los requisitos de servicio. |
| `Notify(source, message, kind)`      | No          | Muestra una notificación al jugador.                                                                                 |

`kind` puede ser `success`, `error`, `warning` o `inform`. Trata los tipos
desconocidos como informativos.

### Descriptor de inventario

```lua theme={null}
exports.humalike:RegisterProvider('inventory', {
    name = 'my_inventory',
    apiVersion = 1,
    priority = 100,
    AddItem = function(source, itemName, quantity, metadata)
        return true
    end,
})
```

`AddItem` debe devolver exactamente `true` tras aceptar la operación. Devuelve
`false` si el inventario está lleno, el objeto es desconocido, los metadatos son
inválidos o por cualquier otro rechazo.

### Descriptor de dispatch

```lua theme={null}
exports.humalike:RegisterProvider('dispatch', {
    name = 'my_dispatch',
    apiVersion = 1,
    priority = 100,
    Report = function(kind, payload)
        return true
    end,
})
```

Traduce el `kind` y el `payload` neutrales a tu recurso de dispatch. Devuelve
`false` solo cuando el reporte fue rechazado; `nil` cuenta como aceptado tras un
callback correcto.

### Descriptor de acciones

```lua theme={null}
exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = { 'hand_over_money' },
    RunAction = function(action, source, npcCoords, params)
        return true
    end,
})
```

Las claves de acción deben empezar por una letra minúscula, contener solo letras
minúsculas, dígitos y `_`, y tener como máximo 64 caracteres. `RunAction` debe
devolver exactamente `true` tras completar o aceptar la acción; es opcional para
un proveedor cuyo `SupportedActions` esté vacío.

Valida `source`, la distancia a `npcCoords`, los permisos, los identificadores,
las cantidades y todos los `params` en el servidor. El nombre de la acción no es
una autorización.

El mismo descriptor declara las observaciones del servidor que la integración
puede reportar (consulta [Observaciones del servidor](/es/ai-npc/integrations/world-events#observaciones-del-servidor)):

```lua theme={null}
exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = {},
    Namespace = 'myserver',
    Observations = {
        item_given = {
            fields = { item = 'string', quantity = 'integer' },
            template = {
                en = 'the character handed you {quantity} x {item}',
                pl = 'postać wręczyła ci {quantity} x {item}',
            },
        },
    },
})
```

* `Namespace` coincide con `^[a-z][a-z0-9]{1,15}$` y es obligatorio en cuanto
  `Observations` no esté vacío. Prefija cada clave en el cable
  (`myserver:item_given`), de modo que una clave del servidor nunca coincida con
  un tipo de evento integrado.
* `Observations` asigna hasta 32 claves (`^[a-z][a-z0-9_]{0,31}$`) a una
  definición con hasta 8 `fields`, nombrados como las claves y tipados como
  `string`, `integer`, `number` o `boolean`, y una `template` con al menos uno
  de los idiomas que ofrece el panel (se usa el idioma del NPC; si no, inglés;
  si no, el primero declarado). Cada línea tiene como máximo 400 caracteres sin caracteres de
  control, sus `{placeholders}` nombran campos declarados y no contiene otras
  llaves. Una plantilla también se dimensiona por su renderizado en el peor
  caso -- cada aparición de un marcador con el valor más ancho de su campo (64
  caracteres para un `string`, 21 para un `number`, 17 para un `integer`, 5
  para un `boolean`) -- que debe mantenerse dentro de 912 caracteres.

El recurso aplica todo esto en `RegisterProvider`: un descriptor que incumple
una regla es rechazado con el motivo y no se registra nada.

## Anular el registro de un proveedor de servidor

```lua theme={null}
local ok, errorMessage = exports.humalike:UnregisterProvider(domain, name)
```

Solo el recurso propietario puede anular el registro de su proveedor. Detener el
propietario realiza esta limpieza automáticamente.

## Estado del servidor

```lua theme={null}
local status = exports.humalike:GetProviderStatus()
```

El resultado contiene:

* `apiVersion` y `runtimeEpoch`;
* `selected`, un mapa compacto por dominio;
* `domains`, incluyendo para cada uno su ajuste, estado, motivo, proveedor
  seleccionado y todos los candidatos registrados.

Los estados son `selected`, `disabled`, `unavailable`, `ambiguous` o `degraded`.
Un fallo en un callback degrada el proveedor seleccionado; un callback correcto
posterior limpia el estado de fallo.

## Registrar un proveedor de interacción de cliente

```lua theme={null}
local ok, errorMessage = exports.humalike:RegisterInteractionProvider({
    name = 'my_target',
    apiVersion = 1,
    priority = 100,
    Available = function() return true end,
    watchedResources = { 'my-target' },
    Add = function(id, entity, options) return true end,
    Remove = function(id) end,
    Progress = function(durationMs, label) return true end,
})
```

`Add` y `Remove` son obligatorios. `Progress` es opcional. `Add` debe devolver
exactamente `true` cuando el registro tiene éxito. `Progress` devuelve
exactamente `true` al completarse y `false` si se cancela o falla.

`watchedResources` enumera las dependencias cuyo inicio/parada debe provocar la
reevaluación del proveedor.

```lua theme={null}
exports.humalike:UnregisterInteractionProvider('my_target')
local status = exports.humalike:GetInteractionProviderStatus()
```

El estado de cliente informa de `apiVersion`, `runtimeEpoch`, el ajuste, el
estado, el motivo y el proveedor seleccionado.

## Evento ready

```lua theme={null}
AddEventHandler('humalike:integration:ready', function(info)
    print(info.apiVersion, info.runtimeEpoch)
end)
```

El evento es local y se emite de forma independiente en el servidor y en el
cliente tras cada inicio de Humalike. Vuelve a registrar los proveedores de ese
lado cuando se dispare.

## Siguiente

* [Implementar el ejemplo completo de puente](/es/ai-npc/integrations/custom-bridge).
* [Reportar eventos del jugador](/es/ai-npc/integrations/world-events).
* [Revisar la referencia pública compacta](/es/ai-npc/reference).