## URL da API URL utilizado para enviar pedidos HTTP: ```url https://portal.bulkgate.com/api/1.0/advanced/promotional ``` > [!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/1.0/advanced/promotional 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 | [Application ID](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/) | **Sim** | - | | application_token | [Application token](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tokens-de-api/) | **Sim** | - | | number | Array de destinatários - [Valor number](#valor-number) | **Sim** ou `admins` ou `groups` | - | | groups | Array de números de grupos na agenda de contactos BulkGate. [Mais informações](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-promotional-envio-para-grupos-da-agenda-de-contactos/) | **Sim** ou `number` ou `admins` | - | | admins | Array de números de administradores BulkGate que recebem notificações. [Mais informações](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-promotional-envio-para-administradores/) | **Sim** ou `number` ou `groups` | - | | text | Texto da mensagem SMS (máx. 612 caracteres, ou 268 caracteres se o Unicode estiver ativado), codificação UTF-8 | **Sim**, se `number` for indicado como array de números ou se for utilizado o parâmetro `groups` ou `admin` | - | | unicode | `Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits | Não | `false` | | 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` (p. ex. "420 777 777 777"), `gText` (p. ex. "BulkGate"), `gProfile` (p. ex. "423"), `gMobile` ou `gPush` [(KEY)](https://www.bulkgate.com/pt/centro-de-ajuda/mobile-connect/instalacao-do-mobile-connect/) | Não | `null` | | country | Indique os números dos destinatários em formato internacional (com o indicativo, p. ex. `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`). Consulte o exemplo de pedido com o país. Se o valor for **`null`**, a informação é completada com base no fuso horário que definiu | 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) Consulte os exemplos abaixo | Não | Agora | | duplicates_check | Selecione **`same_text`** para impedir o envio de mensagens duplicadas para o mesmo número de telefone. Com **`same_number`** impede o envio de uma mensagem com o mesmo texto ou com um texto diferente para o mesmo número. Se for **`null`**, não são removidos duplicados. Os duplicados são removidos **apenas dentro de um único lote**, não entre pedidos. | Não | `null` | | tag | Etiqueta da mensagem para posterior pesquisa pelo utilizador. | Não | - | ### Valor `number` O valor number pode ser indicado de duas formas: - Array de números de telefone ```json [ "420775123456", "420606123456", "44771447678" ] ``` - Array associativo com o esquema `number`, `text` e `variables`, em que o único parâmetro obrigatório é `number`. Se `number` não estiver preenchido, a mensagem é ignorada. ```json [ {"number": "420775123456", "text": "test1 ", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 ", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` No modelo do parâmetro `text` pode inserir variáveis do array `variables`. ### Tipo de ID do remetente `sender_id` | VALOR | SIGNIFICADO | |:-----------|:---------------------------------------------------------------------| | `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 aplicação Mobile Connect | | `gOwn` | Número próprio (requer a verificação do número) | | `gProfile` | [ID do perfil BulkGate](https://www.bulkgate.com/pt/centro-de-ajuda/sms/perfil-de-remetente/) | | `` | ID do perfil BulkGate | ## Exemplos de pedidos **Exemplo de um pedido completo:** ```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" } ``` **Exemplo de um pedido com os destinatários indicados como array de números e a hora agendada em 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" } ``` ## Resposta **Em caso de sucesso:** ```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" } ] } } ``` Em que: - **part_ID** é o array de IDs das partes da mensagem longa original que foi dividida por não cumprir 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 erro HTTP - **detail** contém informações adicionais sobre o erro Todos os tipos de erros da Simple API e da Advanced API podem ser consultados [aqui](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/).