> [!CAUTION]
> Está **terminantemente prohibido** utilizar las notificaciones SMS con fines promocionales o de marketing. Solo deben utilizarse con fines de notificación, como [SMS transaccionales](https://www.bulkgate.com/es/centro-de-ayuda/informacion-general/diferencia-mensajes-promocionales-transaccionales/).

## URL de la API

URL a la que se envían las solicitudes HTTP:

```url
https://portal.bulkgate.com/api/1.0/advanced/transactional
```

> [!NOTE]
> Si la solicitud no llega a su destino, repítala en el [servidor de respaldo](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/servidor-de-respaldo/) `backup1.bulkgate.com`.

## Métodos HTTP admitidos

- `POST` - `application/json`

```http
POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

## Tabla de parámetros

| NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO |
|:------------------|:------------------------------------------------------------------------------------------------------------------|:--------------------:|:--------------:|
| application_id    | [ID de aplicación](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/) |       **Sí**        |       -        |
| application_token | [Token de aplicación](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tokens-de-api/) |       **Sí**        |       -        |
| number            | Número del destinatario |  **Sí** o `admin`  |       -        |
| admin             | Número del administrador de BulkGate que recibe la notificación. [Más información](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-notificacion-al-administrador/) | **Sí** o `number`  |       -        |
| text              | Texto del mensaje SMS (máx. 612 caracteres, o 268 caracteres si se activa Unicode), codificación UTF-8. Es posible añadir a la plantilla variables del array `variables` (otro parámetro) `Hola <first_name> <last_name> ....` |       **Sí**        |       -        |
| variables         | Array asociativo para añadir variables al texto, p. ej.: `{"first_name": "Juan", "last_name": "García"}` |          No          |      `[]`      |
| unicode	          | `Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits |          No          |    `false`     |
| sender_id         | ID de remitente, consulte [Tipo de ID de remitente](#tipo-de-id-de-remitente-sender-id) |          No          |   `gSystem`    |
| sender_id_value   | Valor del remitente: `gOwn` (p. ej. "420 777 777 777"), `gText` (p. ej. "BulkGate"), `gProfile` (p. ej. "423"), `gMobile` o `gPush` [(KEY)](https://www.bulkgate.com/es/centro-de-ayuda/mobile-connect/instalacion-de-mobile-connect/) |          No          |     `null`     |
| country           | Indique los números de los destinatarios en formato internacional (con prefijo, p. ej. `420`), o añada el [código de país](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Consulte el ejemplo de solicitud con el país. Si el valor es **`null`**, se utilizará la zona horaria que tenga configurada para completar la información |          No          |     `null`     |
| schedule          | Programe la fecha y la hora de envío en [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) o [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). |          No          |      Ahora       |
| duplicates_check  | Seleccione **`on`** para evitar el envío de mensajes duplicados al mismo número de teléfono. Los mensajes con el mismo texto enviados al mismo número se eliminarán si entre ellos transcurre un intervalo inferior a 5 minutos. Con **`off`** no se elimina ningún duplicado. |          No          |     `off`      |
| tag               | Etiqueta del mensaje para que el usuario pueda recuperarlo posteriormente. |          No          |       -        |

### Tipo de ID de remitente `sender_id`

| VALOR | SIGNIFICADO |
|:--- |:---|
|`gSystem` |Número del sistema|
|`gShort`|Short Code|
|`gText` |Remitente de texto|
|`gMobile`|[Mobile Connect](https://www.bulkgate.com/es/centro-de-ayuda/mobile-connect/instalacion-de-mobile-connect/)|
|`gPush`|Mobile Connect push: envía una notificación a la aplicación Mobile Connect|
|`gOwn` |Número propio (requiere la verificación del número)|
|`gProfile`|[ID de perfil de BulkGate](https://www.bulkgate.com/es/centro-de-ayuda/sms/perfil-de-remitente/)|
| `<int>` |ID de perfil de BulkGate|

## Ejemplo de solicitud

```http-json
POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",  	
	"number": "420777777777",
	"unicode": true,
	"text": "Hola, <first_name> <last_name>",
	"variables": {"first_name": "Juan", "last_name": "García"},
	"sender_id": "gText",
	"sender_id_value": "BulkGate",
	"country": "es",
	"schedule": "2018-05-14T18:30:00-01:00"
}
```

## Respuesta

**En caso de éxito:**

```json
{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1"
        ],
        "number": "420777777777"
    }
}
```

Donde:

- **part_ID** es el array de ID de las partes del mensaje largo original, que se dividió porque superaba el límite de 160 caracteres de un único mensaje. Más información [aquí](https://www.bulkgate.com/es/centro-de-ayuda/sms/concatenacion-de-mensajes/).

**En caso de error:**

```json
{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Invalid phone number",
    "detail": null
}
```

```json
{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}
```

Donde:

- **type** y **error** (descripción del error) se encuentran en la [tabla de tipos de error](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/)
- **code** representa el código de error HTTP
- **detail** es información adicional sobre el error

Consulte todos los tipos de error de la Simple API y la Advanced API [aquí](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/).