## URL da API URL utilizado para enviar pedidos HTTP: ```url https://portal.bulkgate.com/api/1.0/integration/transactional-bulk ``` > [!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`. ```http POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!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 utilizados apenas para fins de notificação - como notificação por SMS. > [!NOTE] > Se pretender utilizar a rota transacional para enviar mensagens de notificação em massa, contacte o [nosso suporte](https://www.bulkgate.com/pt/contacto/). Por motivo justificado, podemos permitir esta opção. > [!WARNING] > Os destinatários que cancelaram a subscrição receberão a mensagem (o opt-out aplica-se apenas a mensagens promocionais). ### Tabela de parâmetros | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:------------------|:--------------------------------------------------------|:---------:|:---------------------------------:| | application_id | [Application ID](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** | - | | tag | Etiqueta de identificação pessoal | Não | - | | messages | Array de mensagens | **Sim** | [Objeto de mensagem](#objeto-de-mensagem) | ### Objeto de mensagem | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:---------------------------------------:| | primary_channel | O canal principal a utilizar em primeiro lugar na cascata | Não | `sms` | | phone_number | Número de telefone do destinatário | **Sim** | - | | country | Indique os números dos destinatários em formato internacional (com indicativo, por exemplo `420`) ou acrescente o [código do país](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Veja um exemplo do requisito de um país. Se o valor for **`null`**, é utilizado o fuso horário definido 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) Veja os exemplos abaixo. | Não | `null` | | channels | Array associativo de objetos de canal | **Sim** | [Objeto de canal](#objeto-do-canal-viber) | ### Objeto do canal Viber | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender | Nome do remetente | Não | - | | expiration | Tempo após o qual a mensagem expira | Não | `3600` | | text | Texto da mensagem. É possível acrescentar ao modelo variáveis do array `variables` (outro parâmetro) `Olá ....` | **Sim** | - | | variables | Array associativo para acrescentar variáveis ao texto, por exemplo `{"first_name": "John", "last_name": "Doe"}` | Não | `[]` | ### Objeto do canal SMS | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender_id | ID do remetente, consulte [Tipo de ID do remetente](#tipo-de-id-do-remetente-sender-id) | Não | `gSystem` | | sender_id_value | Valor do remetente - `gOwn` (por exemplo, "420 777 777 777"), `gText` (por exemplo, "BulkGate"), `gProfile` (por exemplo, "423"), `gMobile` ou `gPush` [(KEY)](https://www.bulkgate.com/pt/centro-de-ajuda/mobile-connect/instalacao-do-mobile-connect/) | Não | `''` | | unicode | `Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits | Não | `false` | | text | Texto do SMS (máx. 612 caracteres ou 268 caracteres se o Unicode estiver ativado), codificação UTF-8. É possível acrescentar ao modelo variáveis do array `variables` (parâmetro adicional) `Olá ....` | **Sim** | - | | variables | Array associativo para acrescentar variáveis ao texto, por exemplo: `{"first_name": "John", "last_name": "Doe"}` | Não | `[]` | #### Tipo de ID do remetente `sender_id` | VALOR | DESCRIÇÃO | |:-----------|:----------------------------------------------------------------------| | `gSystem` | Número do sistema | | `gShort` | Short code | | `gText` | Remetente de texto | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/pt/centro-de-ajuda/mobile-connect/instalacao-do-mobile-connect/) | | `gPush` | Mobile Connect push - Envia uma notificação para a sua aplicação Mobile Connect | | `gOwn` | Número próprio (requer verificação do número) | | `gProfile` | [ID do perfil de remetente](https://www.bulkgate.com/pt/centro-de-ajuda/sms/perfil-de-remetente/) | | `` | ID do perfil de remetente | **Exemplo de um pedido completo:** ```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" } } } } ] } ``` ## A resposta a este comando pode ser: **Em caso de sucesso** ```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" } ] } } ``` **Em caso de erro:** ```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 } ``` Em que: - **type** e **error** (descrição do erro) encontram-se na [tabela de tipos de erro](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/) - **code** representa o erro HTTP - **detail** é uma informação adicional sobre o erro Todos os tipos de erro da Simple API e da Advanced API encontram-se [aqui](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/).