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

# Definindo os Metadados do Benefício

> Como descrever as informações e parâmetros de integração de um benefício

Cada benefício integrado precisa declarar um arquivo de JSON de metadados que descreve suas informações básicas, parâmetros de autenticação, opções configuráveis e as ações que ele suporta.

Esse arquivo serve para suprir metadados sobre o Benefício, que ficarão disponíveis no portal benStore, informando o que é necessário para a o uso do benefício (por exemplo: tokens, URLs de API, parâmetros adicionais etc).

## Estrutura do Template

O arquivo `benefit.manifest.json` possui os campos necessário para descrever todos os dados necessárias.

```json theme={null}
{
  "benefitName": "Nome do Benefício",
  "supportingText": "Texto curto explicando o propósito do benefício",
  "shortDescription": "Resumo das principais vantagens do benefício",
  "description": "Descrição completa do benefício e seu funcionamento.",
  ....
}
```

## Descrição

🔹 `benefitName`:
Nome comercial do benefício.

🔹 `auth`:
Lista de informação que a integração benSDK utilizará para autenticação que é configurável via portal benStore.
Cada item representa uma variável para sua autenticação (como token, URL, client ID, etc).

🔹 `availiableActions`:
Determina quais ações são automatizadas no benefício, elas se tornam configuráveis pelo portal benStore.
Geralmente é o mesmo definido no `benefit-definition.ts`.

🔹 `options`:
Define parâmetros que podem ser personalizados no portal benStore, e ficará disponível para uso no SDK.
Eles são exibidos na interface do portal e podem alterar o comportamento do benefício.

* `key`: identificador único do campo
* `label`: nome exibido no painel
* `type`: tipo do valor (BOOLEAN, TEXT, MAP, etc)
* `jsonSchema`: validação do valor informado

## Onde o Template é Usado

Durante a integração, usamos para:

* Montar automaticamente a tela de configuração do benefício;
* Validar credenciais e parâmetros antes de inicializar a execução;
* Exibir o benefício corretamente no catálogo do portal benStore.

## Ícone do benefício

É importante definir uma imagem PNG substituindo o arquivo `ICON.png` placeholder na raiz do projeto. Esse ícone será usado pelo portal benStore.

### Exemplo

```json theme={null}
{
    "benefitName": "Benefício X",
    "supportingText": "Texto breve sobre o benefício",
    "shortDescription": "Descrição curta e objetiva do benefício",
    "description": "Descrição detalhada do benefício, explicando seus principais recursos e vantagens para os colaboradores.",
    "auth": [
        {
            "key": "api.token",
            "label": "Token da API",
            "description": "Token de autenticação fornecido pelo benefício",
            "type": "TEXT",
            "required": true,
            "jsonSchema": {
                "type": "string",
                "minLength": 2
            }
        },
        {
            "key": "api.url",
            "label": "URL da API",
            "description": "URL base do endpoint do provedor",
            "type": "TEXT",
            "required": true,
            "jsonSchema": {
                "type": "string",
                "minLength": 1
            }
        }
    ],
    "provider": "benefits-orchestrator",
    "category": "Outros",
    "products": [
        {
            "productID": "PRODUCT_A",
            "productName": "Produto A"
        }
    ],
    "availiableActions": [
        "GRANT",
        "REVOKE",
        "DEDUCTION"
    ],
    "options": [
        {
            "key": "option.booleanFlag",
            "label": "Opção Booleana",
            "description": "Ativa ou desativa determinada funcionalidade",
            "type": "BOOLEAN",
            "default": false,
            "required": true,
            "jsonSchema": {
                "type": "boolean"
            }
        },
        {
            "key": "option.referenceID",
            "label": "ID de referência externa",
            "description": "Identificador vinculado a um sistema externo",
            "type": "TEXT",
            "default": "placeholder-id",
            "required": true,
            "jsonSchema": {
                "type": "string",
                "minLength": 1
            }
        }
    ]
}
```