## O que pode acrescentar por si

Os módulos BulkGate permitem duas coisas para além do que a administração oferece. Ambas
se destinam a programadores — intervém no código da sua loja online.

| Extensão | Para que serve |
|:--|:--|
| [SMS personalizada a partir do seu código](#sms-personalizada-a-partir-do-seu-codigo) | Enviar uma mensagem a partir de qualquer ponto do seu código, até de outro plugin |
| [Variáveis personalizadas](#variaveis-personalizadas-nos-modelos) | Acrescentar aos seus modelos dados que o módulo desconhece — um número de seguimento, pontos de fidelização, qualquer dado da sua base de dados |

O suporte varia consoante o módulo:

| Módulo | SMS personalizada | Variáveis personalizadas |
|:--|:--|:--|
| WooSMS (WooCommerce) | Sim | Sim |
| PrestaSMS (PrestaShop) | Sim | Sim |
| CartSMS (OpenCart) | — | Sim |

> [!CAUTION]
> A utilização indevida de SMS informativas para fins
> promocionais e de marketing é **estritamente proibida.**
> Desta forma, só pode enviar
> [SMS transacionais](https://www.bulkgate.com/pt/centro-de-ajuda/informacoes-gerais/diferenca-sms-promocional-e-transacional/).

## SMS personalizada a partir do seu código

A mensagem é enviada como transacional, é cobrada da carteira do módulo e
segue a mesma rota que as notificações que o módulo envia por si.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',          // o nome da ação
    '420777123456',               // o número de telefone
    'Olá <name>, tem <age> anos', // o texto com variáveis entre parênteses angulares
    [                             // os valores das variáveis
        'name' => 'João',
        'age'  => '29',
    ],
    [                             // definições opcionais
        'unicode'     => true,       // acentos e emoji
        'country'     => 'pt',       // ISO 3166 para números em formato nacional
        'senderType'  => 'gText',    // o tipo de remetente
        'senderValue' => 'BulkGate', // o valor do remetente
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Olá <name>, tem <age> anos',
    'variables' => [
        'name' => 'João',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'pt',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Definições do remetente

| `senderType` | O que significa | `senderValue` |
|:--|:--|:--|
| `gSystem` | Um número do sistema BulkGate | Não utilizado |
| `gShort` | Um código curto | Não utilizado |
| `gText` | Um remetente alfanumérico | O texto apresentado ao destinatário |
| `gOwn` | O seu próprio número de telefone | O número em formato internacional |

> [!NOTE]
> O nome de ação mais antigo `woosms_send_sms` continua a funcionar, mas utilize
> `bulkgate_send_sms` nas novas integrações — é igual em todos os módulos.

## Variáveis personalizadas nos modelos

Em cada notificação, o módulo recolhe dados sobre a encomenda e o cliente.
Esta extensão acrescenta os seus próprios valores a esse conjunto, que depois utiliza no
modelo como `<variable_name>`.

### WooSMS

```php
<?php

use BulkGate\Plugin\{Database\Connection, Event\Variables};

add_action('bulkgate_extends_variables', function (Variables $variables, Connection $database): void
{
    $order_id = $variables->get('order_id');

    $row = $database->fetch('SELECT tracking_number FROM `order` WHERE order_id = ?', $order_id);

    if ($row !== null)
    {
        $variables->set('tracking_number', $row->tracking_number);
    }

    // <tracking_number> funciona agora no modelo

}, 20, 2);
```

### PrestaSMS

O módulo chama o hook `actionPrestaSmsExtendsVariables` e passa-lhe um array
com duas chaves — `variables` e `database`:

```php
<?php

public function hookActionPrestaSmsExtendsVariables(array $params): void
{
    $variables = $params['variables'];
    $database = $params['database'];

    $variables->set('tracking_number', '1234567890');
}
```

### CartSMS

O OpenCart não tem um sistema de hooks, por isso a extensão faz-se reescrevendo uma
classe preparada no ficheiro `system/library/cartsms/cartsms/src/HookExtension.php`:

```php
<?php

namespace BulkGate\CartSms;

use BulkGate\Extensions;

class HookExtension extends Extensions\Strict implements Extensions\Hook\IExtension
{
    public function extend(Extensions\Database\IDatabase $database, Extensions\Hook\Variables $variables)
    {
        $row = $database->execute($database->prepare(
            "SELECT `tracking_no` FROM `{$database->table('order')}` WHERE `order_id` = %s LIMIT 1",
            [$variables->get('order_id')]
        ))->getRow();

        if ($row)
        {
            $variables->set('tracking_no', $row->tracking_no);
        }
    }
}
```

> [!WARNING]
> Com o CartSMS reescreve um ficheiro dentro do próprio módulo, pelo que perde a
> alteração quando o módulo é atualizado. Guarde uma cópia de segurança e reponha-a após cada atualização.

## Extensões prontas a usar no GitHub

Para os casos comuns — números de seguimento das transportadoras, pontos de fidelização, referências
de pagamento — existem soluções prontas que só precisa de instalar:

| Módulo | Repositório |
|:--|:--|
| WooSMS | [github.com/BulkGate/woosms-extensions](https://github.com/BulkGate/woosms-extensions) |
| CartSMS | [github.com/BulkGate/cartsms-extensions](https://github.com/BulkGate/cartsms-extensions) |

A pasta `_ready-made-solutions` contém extensões para plugins específicos — no caso do
WooSMS incluem AfterShip, GLS, Nova Poshta ou o seguimento de envios; no caso do
CartSMS, pontos de fidelização e números de seguimento. O WooSMS tem ainda um esqueleto
vazio na pasta `woosms-variables-extension`, um bom ponto de partida para
escrever a sua própria extensão.

> [!TIP]
> Antes de começar a escrever o seu próprio código, consulte as soluções prontas —
> muitas vezes uma delas basta tal como está, ou só precisa de alterar os nomes da
> tabela e das colunas.