> [!CAUTION] > É **estritamente proibido** utilizar [SMS transacionais](https://www.bulkgate.com/pt/centro-de-ajuda/informacoes-gerais/diferenca-sms-promocional-e-transacional/) para fins promocionais/de marketing. Devem ser utilizadas apenas para fins de notificação - como notificação SMS. > [!NOTE] > Se pretender utilizar uma rota transacional para enviar uma mensagem de notificação em massa, contacte o [nosso suporte](https://www.bulkgate.com/pt/contacto/). Por motivo justificado, podemos permitir esta opção. ## URL da API URL utilizado para enviar os pedidos HTTP: ```url https://portal.bulkgate.com/api/2.0/advanced/transactional ``` > [!NOTE] > Se o pedido não chegar ao destino, repita-o no [servidor de reserva](https://www.bulkgate.com/pt/documentacao/administracao-da-api/servidor-de-reserva/) `backup1.bulkgate.com`. ## Métodos HTTP suportados - `POST` - `application/json` ```http POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tabela de parâmetros | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------:|:------------------------------------------:| | application_id | [Identificador da aplicação](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/) | **Sim** | - | | application_token | [Token de autenticação da aplicação](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tokens-de-api/) | **Sim** | - | | number | Número do destinatário ou array de números de destinatários - [Valor number](#valor-number) | **Sim** ou `admin` | - | | admin | Número do administrador BulkGate que recebe a notificação. [Mais informações](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional-notificacoes-para-administradores/) | **Sim** ou `number` | - | | text | Texto da mensagem SMS (máx. 612 caracteres, ou 268 caracteres se for utilizado Unicode), codificação UTF-8. É possível adicionar ao modelo variáveis do array `variables` (outro parâmetro) `Olá ....` | **Sim** | - | | variables | Array associativo para adicionar variáveis ao texto, por exemplo: `{"first_name": "John", "last_name": "Doe"}` | Não | `[]` | | channel | Canais alternativos. Os canais são tentados em cascata, pela ordem em que os indica no objeto - se não conseguirmos entregar a mensagem pelo primeiro canal, é utilizado o seguinte da lista. O SMS **não** é acrescentado automaticamente; se o quiser como última alternativa, inclua o objeto `sms` na cascata. Se não for indicado nenhum canal, a mensagem é enviada como SMS. | Não | [Objeto SMS](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-sms/) | | country | Indique os números dos destinatários em formato internacional (com prefixo, p. ex. `420`) ou adicione o [código do país no formato ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Consulte o exemplo de pedido com o país. Se for **`null`**, será utilizado o fuso horário que definiu para completar a informação | Não | `null` | | schedule | Agende a data e a hora de envio em [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Não | Agora | | duplicates_check | Selecione **`on`** para evitar o envio de mensagens duplicadas para o mesmo número de telefone. As mensagens com o mesmo texto enviadas para o mesmo número serão removidas se o intervalo entre elas for inferior a 5 minutos. Com **`off`**, nenhum duplicado é removido. | Não | `off` | | tag | Etiqueta da mensagem para posterior pesquisa pelo utilizador. | Não | - | ### Valor `number` O valor number pode ser indicado da seguinte forma: - Array de números de telefone ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Canais O objeto `channel` determina por que canais e por que ordem a mensagem é enviada. **A ordem das chaves no seu pedido é a ordem da cascata** e o SMS não é acrescentado automaticamente - consulte [Cascata de canais](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-cascata-de-canais/). | CHAVE | OBJETO DO CANAL | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-sms/) | | `viber` | [Viber – transacional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-viber-transacional/) | | `rcs` | [RCS](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-whatsapp/) | ## Exemplo de pedido ```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 } } } ``` ## Resposta **Em caso de sucesso:** ```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" } ] } } ``` Em que: - **part_ID** é o array de ID das partes da mensagem longa original, que foi dividida por exceder o limite de 160 caracteres de uma única mensagem. Mais informações [aqui](https://www.bulkgate.com/pt/centro-de-ajuda/sms/concatenacao-de-mensagens/). **Em caso de erro:** ```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 } ``` Em que: - **type** e **error** (descrição do erro) encontram-se na [tabela de tipos de erros](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/) - **code** representa o código de erro HTTP - **detail** contém informações adicionais sobre o erro Consulte todos os tipos de erros da Simple API e da Advanced API [aqui](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/).