## URL da API URL utilizado para enviar pedidos HTTP: ```url https://portal.bulkgate.com/api/2.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/2.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` | - | | 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 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) (`777777777` + `CZ` = `420777777777`). 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 [ "420777777777", "420888888888", "420999999999" ] ``` - 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": "420777777777", "text": "test1 ", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 ", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` No modelo do parâmetro `text` pode inserir variáveis do array `variables`. ## Canais O objeto `channel` determina por que canais e por que ordem a mensagem é enviada. **A ordem das chaves no pedido é a ordem da cascata** e o SMS não lhe é 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 – promocional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-viber-promocional/) | | `rcs` | [RCS](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-whatsapp/) | ## Exemplos de pedidos **Exemplo de um pedido completo:** ```http-json POST /api/2.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": "420777777777", "text": "test1 ", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 ", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "groups": [1, 2], "admins": [1, 4], "text": "RCS: o futuro das mensagens móveis para empresas", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "Lt. Hagan", "expiration": 100, "button": { "caption": "Ir para o BulkGate", "url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/" }, "image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg", "text": "*RCS: o futuro das mensagens móveis para empresas*\n\nJá desejou poder enviar mais do que simples texto numa SMS, como uma imagem em alta resolução ou um botão interativo? Ou gostaria de receber uma confirmação de leitura para ter a certeza de que a sua mensagem chegou ao destino? O Rich Communication Services (RCS) veio revolucionar a forma como as empresas comunicam, melhorando a experiência de envio de mensagens e ultrapassando estas limitações." }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true, "text": "RCS: o futuro das mensagens móveis para empresas" } } } ``` **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/2.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": [ "420777777777", "420888888888", "420999999999" ], "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":"420777777777", "channel":"sms" }, { "status":"scheduled", "sms_id":"idyrcmdd-1", "part_id":[ "idyrcmdd-1_1", "idyrcmdd-1" ], "number":"420888888888", "channel":"sms" }, { "status":"invalid_number", "code":400, "error":"Invalid phone number", "detail":null, "number":"420999999999", "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/).