> [!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, como notificación SMS. > [!NOTE] > Si desea utilizar la ruta transaccional para enviar un mensaje de notificación masivo, póngase en contacto con [nuestro soporte](https://www.bulkgate.com/es/contacto/). Podemos permitir esta opción si existe un motivo justificado. ## URL de la API URL a la que se envían las solicitudes HTTP: ```url https://portal.bulkgate.com/api/2.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/2.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 | [Identificador de la aplicación](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í** | - | | number | Número del destinatario o array de números de destinatarios: [Valor number](#valor-number) | **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 utiliza Unicode), codificación UTF-8. Es posible añadir a la plantilla variables del array `variables` (otro parámetro) `Hola ....` | **Sí** | - | | variables | Array asociativo para añadir variables al texto, p. ej.: `{"first_name": "Juan", "last_name": "García"}` | No | `[]` | | channel | Canales alternativos. Los canales se prueban en cascada, en el orden en que los indique en el objeto: si no conseguimos entregar su mensaje por el primer canal, se utiliza el siguiente de la lista. El SMS **no** se añade automáticamente; si lo quiere como última alternativa, incluya el objeto `sms` en la cascada. Si no se indica ningún canal, el mensaje se envía como SMS. | No | [Objeto SMS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-sms/) | | 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 en formato ISO 3166-1 alpha-2](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 | - | ### Valor `number` El valor number puede escribirse de la siguiente manera: - Array de números de teléfono ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Canales El objeto `channel` determina por qué canales se envía el mensaje y en qué orden. **El orden de las claves en su solicitud es el orden de la cascada** y el SMS no se añade a ella automáticamente; consulte [Cascada de canales](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-cascada-de-canales/). | CLAVE | OBJETO DEL CANAL | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-sms/) | | `viber` | [Viber – transaccional](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-viber-transaccional/) | | `rcs` | [RCS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-whatsapp/) | ## Ejemplo de solicitud ```http-json POST /api/2.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": ["777777777", "777777778"], "text": "example text ", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } } ``` ## Respuesta **En caso de éxito:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } } ``` 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/).