# Objeto Button

Métodos do botão devolvido por generateButton() e os objetos actions.

`generateButton()` devolve um objeto Button. Renderize-o com `.render()` e controle-o com
os métodos abaixo.

<Note>
Referência baseada na implementação **JavaScript** atual (`Button.js`), a fonte autoritativa.
</Note>

```js
const button = facipay.generateButton({ /* ... */ });
button.render('#facipay-button-container');
```

## Ciclo de vida

<ResponseField name="render(container)" type="void">
  Renderiza o botão. `container` pode ser um seletor (`'#facipay-button-container'`) ou um
  elemento DOM. Lança `Error('Container not found')` se o elemento não existir. Aguarda a
  validação da chave antes de mostrar o botão.
</ResponseField>

<ResponseField name="update(newOptions)" type="void">
  Funde novas opções nas atuais (`Object.assign`) e re-renderiza o botão.
</ResponseField>

<ResponseField name="destroy()" type="void">
  Remove o botão e limpa o container.
</ResponseField>

<ResponseField name="enable()" type="void">
  Ativa o botão.
</ResponseField>

<ResponseField name="disable()" type="void">
  Desativa o botão.
</ResponseField>

## Referências de pagamento

Usadas para mostrar o valor no botão e suportar vários itens. Ver
[Referências múltiplas](/pt/sdk/recipes/multiple-references).

<ResponseField name="addPaymentReference(ref)" type="void">
  Adiciona **uma** referência de pagamento e recalcula o total.
</ResponseField>

<ResponseField name="addAllPaymentReferences(refs)" type="void">
  Substitui o conjunto de referências por uma lista (ignora entradas sem `referenceNumber`)
  e recalcula o total.
</ResponseField>

<ResponseField name="removePaymentReferenceNumber(referenceNumber)" type="void">
  Remove a referência com o `referenceNumber` indicado e recalcula o total.
</ResponseField>

<ResponseField name="updateQuantity(referenceNumber, quantity)" type="void">
  Atualiza a quantidade de uma referência existente (valida contra `referenceTotalQuantity`)
  e recalcula o total.
</ResponseField>

<ResponseField name="getTotalAmount()" type="number">
  Soma `referenceAmount × (referenceQuantity || 1)` de todas as referências (uma quantidade ausente ou zero conta como 1).
</ResponseField>

Cada referência tem a forma:

```ts
{
  referenceNumber: string;        // id único
  referenceAmount: number;        // preço unitário (AOA, inteiro)
  referenceQuantity: number;      // quantidade
  referenceTotalQuantity: number; // stock disponível (limite do updateQuantity)
}
```

```js
button.addAllPaymentReferences(cart.items.map((item) => ({
  referenceNumber: String(item.id),
  referenceAmount: item.price,
  referenceQuantity: item.quantity,
  referenceTotalQuantity: item.stock_quantity,
})));
```

## Cliente

<ResponseField name="addCustomerInfo(info)" type="void">
  Define os dados do cliente (`{ name, phone }`), tipicamente dentro de `onClick`.
</ResponseField>

```js
facipay.button.addCustomerInfo({ name: 'Pascoal Luís', phone: '947554613' });
```

## Objetos `actions`

A SDK passa um objeto `actions` diferente conforme o callback:

| Callback | `actions` disponível |
|---|---|
| `onInit(actions)` | `enable()`, `disable()` |
| `onClick(data, actions)` | `enable()`, `disable()`, `reject()` |
| `onApprove(data, actions)` / `onPending(data, actions)` | `onPopupWindowClosed(cb)` |

<ResponseField name="actions.enable() / actions.disable()" type="function">
  Ativam/desativam o botão (em `onInit` e `onClick`).
</ResponseField>

<ResponseField name="actions.reject()" type="function">
  Interrompe a sequência do botão neste clique (em `onClick`) — o popup não abre.
</ResponseField>

<ResponseField name="actions.onPopupWindowClosed(cb)" type="function">
  Regista uma função a correr quando o popup fecha (em `onApprove`/`onPending`).
</ResponseField>

<Card title="Próximo passo: Eventos" icon="arrow-right" href="/pt/sdk/events">
  Comunicação por postMessage entre o popup e a sua página.
</Card>