## URL de la API URL utilizada para enviar las solicitudes HTTP: ```url https://portal.bulkgate.com/api/1.0/advanced/promotional ``` > [!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 compatibles - `POST` - `application/json` ```http POST /api/1.0/advanced/promotional 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 | [Application ID](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/) | **Sí** | - | | application_token | [Application token](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tokens-de-api/) | **Sí** | - | | number | Array de destinatarios - [Valor number](#valor-number) | **Sí** o `admins` o `groups` | - | | groups | Array de números de grupos de la agenda de contactos de BulkGate. [Más información](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-envio-a-grupos/) | **Sí** o `number` o `admins` | - | | admins | Array de números de administradores de BulkGate que reciben notificaciones. [Más información](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-promotional-envio-a-administradores/) | **Sí** o `number` o `groups` | - | | text | Texto del mensaje SMS (máx. 612 caracteres, o 268 caracteres si se activa Unicode), codificación UTF-8 | **Sí**, si `number` se indica mediante el array de números o se utiliza el parámetro `groups` o `admin` | - | | 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) (`775123456` + `CZ` = `420775123456`). Consulte el ejemplo de solicitud con país. Si el valor es **`null`**, la información se completará según la zona horaria configurada | 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) Consulte los ejemplos de abajo | No | Ahora | | duplicates_check | Seleccione **`same_text`** para evitar el envío de mensajes duplicados al mismo número de teléfono. Con **`same_number`** desactiva la posibilidad de enviar un mensaje con el mismo texto o con otro distinto al mismo número. Si es **`null`**, no se eliminará ningún duplicado. Los duplicados se eliminan **solo dentro de un mismo lote**, no entre solicitudes distintas. | No | `null` | | tag | Etiqueta del mensaje para que el usuario pueda localizarlo posteriormente. | No | - | ### Valor `number` El valor number puede escribirse de dos maneras: - Array de números de teléfono ```json [ "420775123456", "420606123456", "44771447678" ] ``` - Array asociativo con el esquema `number`, `text` y `variables`, donde el único parámetro obligatorio es `number`. Si `number` no está rellenado, el mensaje se omite. ```json [ {"number": "420775123456", "text": "test1 ", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 ", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` En la plantilla del parámetro `text` puede añadir variables del array `variables`. ### 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` | [BulkGate Profile ID](https://www.bulkgate.com/es/centro-de-ayuda/sms/perfil-de-remitente/) | | `` | BulkGate Profile ID | ## Ejemplos de solicitudes **Ejemplo de solicitud completa:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "420775123456", "text": "test1 ", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 ", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, ", "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" } ``` **Ejemplo de solicitud que indica los destinatarios mediante un array de números y programa la hora en unix timestamp:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420775123456", "420606123456", "44771447678" ], "text": "Hello, ", "schedule": "1526992636" } ``` ## Respuesta **En caso de éxito:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 1, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "sms_id": "idyrcmdd-0", "part_id": [ "idyrcmdd-0_1", "idyrcmdd-0" ], "number": "420775123456", "channel": "sms" }, { "status": "scheduled", "sms_id": "idyrcmdd-1", "part_id": [ "idyrcmdd-1_1", "idyrcmdd-1" ], "number": "420606123456", "channel": "sms" }, { "status": "invalid_number", "code": 400, "error": "Invalid phone number", "detail": null, "number": "44771447678", "channel": "sms" } ] } } ``` 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 solo 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 error HTTP - **detail** es información adicional sobre el error Consulte todos los tipos de error de Simple API y Advanced API [aquí](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/).