## URL de la API URL a la que se envían las solicitudes HTTP: ```url https://portal.bulkgate.com/api/1.0/integration/transactional-bulk ``` > [!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`. ```http POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > Está **terminantemente prohibido** utilizar los [SMS transaccionales](https://www.bulkgate.com/es/centro-de-ayuda/informacion-general/diferencia-mensajes-promocionales-transaccionales/) con fines promocionales o de marketing. Solo deben utilizarse con fines de notificación, es decir, como notificación por SMS. > [!NOTE] > Si desea utilizar una ruta transaccional para enviar mensajes de notificación masivos, póngase en contacto con [nuestro soporte](https://www.bulkgate.com/es/contacto/). Podemos permitir esta opción si existe un motivo justificado. > [!WARNING] > Los destinatarios que se hayan dado de baja recibirán el mensaje (la baja (opt-out) solo se aplica a los mensajes promocionales). ### 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 | [Token de autenticación de la aplicación](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tokens-de-api/) | **Sí** | - | | tag | Etiqueta de identificación personal | No | - | | messages | Array de mensajes | **Sí** | [Objeto de mensaje](#objeto-de-mensaje) | ### Objeto de mensaje | NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO | |:----------------|:------|:-----------:|:--------------------:| | primary_channel | Canal principal que se utiliza primero en la cascada | No | `sms` | | phone_number | Número de teléfono del destinatario | **Sí** | - | | 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 un ejemplo de lo que exige cada país. Si el valor es **`null`**, se utiliza la zona horaria que tenga configurada para completar la información | No | `null` | | schedule | Programe la fecha y la hora de envío como [marca de tiempo Unix.](https://en.wikipedia.org/wiki/Unix_time) Consulte los ejemplos a continuación. | No | `null` | | channels | Array asociativo de objetos de canal | **Sí** | [Objeto de canal](#objeto-del-canal-viber) | ### Objeto del canal Viber | NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO | |:---------------|:------|:-----------:|:--------------------:| | sender | Nombre del remitente | No | - | | expiration | Tiempo tras el cual el mensaje caduca | No | `3600` | | text | Texto del mensaje. Es posible añadir a la plantilla variables del array `variables` (otro parámetro) `Hello ....` | **Sí** | - | | variables | Array asociativo para añadir variables al texto, p. ej. `{"first_name": "John", "last_name": "Doe"}` | No | `[]` | ### Objeto del canal SMS | NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO | |:----------------|:------|:-----------:|:--------------------:| | 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 | `''` | | unicode | `Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits | No | `false` | | text | Texto del SMS (máx. 612 caracteres o 268 caracteres si Unicode está activado), codificación UTF-8. Es posible añadir a la plantilla variables del array `variables` (parámetro adicional) `Hello ....` | **Sí** | - | | variables | Array asociativo para añadir variables al texto, p. ej.: `{"first_name": "John", "last_name": "Doe"}` | No | `[]` | #### Tipo de ID de remitente `sender_id` | VALOR | DESCRIPCIÓN | |:-----------|:----------------------------------------------------------------------| | `gSystem` | Número del sistema | | `gShort` | Código corto | | `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 su aplicación Mobile Connect | | `gOwn` | Número propio (requiere la verificación del número) | | `gProfile` | [ID del perfil de remitente](https://www.bulkgate.com/es/centro-de-ayuda/sms/perfil-de-remitente/) | | `` | ID del perfil de remitente | **Ejemplo de una solicitud completa:** ```http-json POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## La respuesta a este comando puede ser: **En caso de éxito** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **En caso de error:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null } ``` Donde: - **type** y **error** (descripción del error) se pueden consultar 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 Todos los tipos de error de Simple API y Advanced API se encuentran [aquí](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/).