## Qué puede añadir usted mismo

Los módulos de BulkGate pueden hacer dos cosas más allá de lo que ofrece la administración. Ambas
están pensadas para desarrolladores: tendrá que intervenir en el código de su tienda online.

| Extensión | Para qué sirve |
|:--|:--|
| [SMS personalizado desde su código](#sms-personalizado-desde-su-codigo) | Enviar un mensaje desde cualquier punto de su código, incluso desde otro plugin |
| [Variables personalizadas](#variables-personalizadas-en-las-plantillas) | Añadir a sus plantillas datos que el módulo no conoce: un número de seguimiento, puntos de fidelidad, cualquier dato de su base de datos |

La compatibilidad varía según el módulo:

| Módulo | SMS personalizado | Variables personalizadas |
|:--|:--|:--|
| WooSMS (WooCommerce) | Sí | Sí |
| PrestaSMS (PrestaShop) | Sí | Sí |
| CartSMS (OpenCart) | — | Sí |

> [!CAUTION]
> Está **terminantemente prohibido** utilizar indebidamente los SMS informativos con
> fines promocionales y de marketing. Por esta vía
> solo puede enviar
> [SMS transaccionales](https://www.bulkgate.com/es/centro-de-ayuda/informacion-general/diferencia-mensajes-promocionales-transaccionales/).

## SMS personalizado desde su código

El mensaje se envía como transaccional, se factura desde el monedero del módulo y
sigue la misma ruta que las notificaciones que el módulo envía por sí mismo.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',          // el nombre de la acción
    '420777123456',               // el número de teléfono
    'Hola <name>, tienes <age>',  // el texto con variables entre corchetes angulares
    [                             // los valores de las variables
        'name' => 'Pedro',
        'age'  => '29',
    ],
    [                             // ajustes opcionales
        'unicode'     => true,       // diacríticos y emoji
        'country'     => 'es',       // ISO 3166 para números en formato nacional
        'senderType'  => 'gText',    // el tipo de remitente
        'senderValue' => 'BulkGate', // el valor del remitente
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Hola <name>, tienes <age>',
    'variables' => [
        'name' => 'Pedro',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'es',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Ajustes del remitente

| `senderType` | Qué significa | `senderValue` |
|:--|:--|:--|
| `gSystem` | Un número de sistema de BulkGate | No se utiliza |
| `gShort` | Un código corto | No se utiliza |
| `gText` | Un remitente alfanumérico | El texto que ve el destinatario |
| `gOwn` | Su propio número de teléfono | El número en formato internacional |

> [!NOTE]
> El nombre de acción anterior `woosms_send_sms` sigue funcionando, pero para las nuevas
> integraciones utilice `bulkgate_send_sms`: es el mismo en todos los módulos.

## Variables personalizadas en las plantillas

Con cada notificación, el módulo recopila datos sobre el pedido y el cliente.
Esta extensión añade sus propios valores a ese conjunto, y después los utiliza en la
plantilla 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> ahora funciona en la plantilla

}, 20, 2);
```

### PrestaSMS

El módulo llama al hook `actionPrestaSmsExtendsVariables` y le pasa un array
con dos claves, `variables` y `database`:

```php
<?php

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

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

### CartSMS

OpenCart no tiene un sistema de hooks, así que la extensión se hace reescribiendo una
clase preparada en el archivo `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]
> Con CartSMS reescribe un archivo dentro del propio módulo, por lo que perderá el
> cambio cuando se actualice. Guarde una copia de seguridad y vuelva a colocarla después de cada actualización.

## Extensiones listas para usar en GitHub

Para los casos habituales (números de seguimiento de los transportistas, puntos de fidelidad,
referencias de pago) existen soluciones listas para usar que solo tiene que instalar:

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

La carpeta `_ready-made-solutions` contiene extensiones para plugins concretos: para
WooSMS incluyen AfterShip, GLS, Nova Poshta o el seguimiento de envíos; para
CartSMS, puntos de fidelidad y números de seguimiento. WooSMS tiene además un esqueleto
vacío en la carpeta `woosms-variables-extension`, un buen punto de partida para
escribir su propia extensión.

> [!TIP]
> Antes de empezar a escribir su propio código, revise las soluciones listas para usar:
> a menudo una de ellas basta tal cual o solo requiere cambiar los nombres de la tabla
> y de las columnas.