1. Introdução

A VITAE CONSULTORIA E SERVIÇOS, LDA disponibiliza a VITAE SMS API, uma interface de integração destinada a permitir que sistemas, aplicações, websites e outras plataformas autorizadas efectuem o envio automatizado de mensagens SMS.

A API permite integrar o serviço de SMS directamente nos sistemas do Cliente, possibilitando o envio de notificações, alertas, confirmações, avisos transaccionais e outras comunicações institucionais autorizadas.

O presente documento estabelece os requisitos técnicos, procedimentos de integração, responsabilidades e regras de utilização da API.

2. Objectivo

A API VITAE SMS tem como objectivo disponibilizar um mecanismo simples e seguro para integração de serviços de SMS em sistemas de terceiros.

Através da API, o Cliente poderá:

• enviar SMS através do seu sistema;
• utilizar um Sender ID previamente autorizado;
• indicar o número de telefone do destinatário;
• definir o conteúdo da mensagem;
• atribuir um identificador externo à mensagem;
• consultar o saldo disponível para envio de SMS.

3. Pré-requisitos de Integração

Para utilizar a API, o Cliente deverá possuir:

• uma conta activa na plataforma VITAE SMS;
• Username autorizado;
• Palavra-Chave/API Credential válida;
• Sender ID aprovado;
• saldo disponível para envio de SMS;
• sistema ou aplicação com capacidade para efectuar requisições HTTP/HTTPS.

As credenciais são atribuídas individualmente ao Cliente e não deverão ser partilhadas com terceiros.

4. Ambiente da API

A VITAE fornecerá ao Cliente o endereço oficial do ambiente da API.

Base URL:

https://[ENDEREÇO-OFICIAL-DA-API]

O endereço utilizado em ambiente de testes poderá ser diferente do endereço utilizado em produção.

A passagem para o ambiente de produção deverá ocorrer após validação da integração.

5. Autenticação

Todas as requisições deverão incluir as credenciais atribuídas pela VITAE.

Parâmetros

Exemplo

username=cliente@empresa.co.mz
password=SUA_CHAVE_API

As credenciais deverão ser armazenadas de forma segura no servidor da aplicação do Cliente.

Nunca deverão ser incorporadas directamente em aplicações frontend, JavaScript público, aplicações móveis sem protecção ou repositórios públicos de código.

6. Envio de SMS

6.1 Endpoint

Método: GET · Endpoint: /api

Estrutura

GET https://[BASE-URL]/api?username=USERNAME&password=PASSWORD&message=MENSAGEM&to=DESTINO&from=SENDERID&messageid=ID

6.2 Parâmetros para Envio

6.3 Número de Destino

O número deverá ser enviado no formato internacional.

Exemplo – Moçambique

258840000000

Recomenda-se que o número seja enviado sem espaços, hífenes ou caracteres especiais.

6.4 Sender ID

O parâmetro from representa a identificação que será apresentada ao destinatário como remetente da mensagem.

Exemplo

from=EMPRESA

O Cliente apenas poderá utilizar Sender IDs previamente aprovados e associados à sua conta.

É expressamente proibida a utilização do nome ou identificação de outra empresa, instituição ou organização sem autorização.

6.5 Message ID

Cada SMS deverá possuir um identificador externo: messageid

Exemplo

messageid=100023

Recomenda-se que cada transacção possua um identificador único, permitindo ao sistema do Cliente efectuar rastreio e reconciliação das mensagens submetidas.

7. Exemplo de Requisição

Requisição

GET https://[BASE-URL]/api?username=cliente@empresa.co.mz&password=SUA_CHAVE_API&message=Pagamento%20recebido%20com%20sucesso&to=258840000000&from=EMPRESA&messageid=100023

Neste exemplo:

• Cliente: cliente@empresa.co.mz
• Destinatário: 258840000000
• Sender ID: EMPRESA
• Message ID: 100023
• Mensagem: Pagamento recebido com sucesso

Todos os parâmetros deverão ser correctamente codificados para utilização numa URL.

8. Consulta de Saldo

A API disponibiliza mecanismos para consulta do saldo de SMS associado à conta.

8.1 Endpoint dedicado

Método: GET · Endpoint: /api/balance

Exemplo

GET https://[BASE-URL]/api/balance?username=USERNAME&password=PASSWORD

Parâmetros

8.2 Consulta através de Action

Alternativamente, poderá ser efectuada a consulta através do endpoint principal:

GET https://[BASE-URL]/api?username=USERNAME&password=PASSWORD&action=balance

Neste caso, action=balance indica que a operação pretendida é uma consulta de saldo e não o envio de uma mensagem.

9. Fluxo Recomendado de Integração

O sistema do Cliente deverá seguir o seguinte fluxo:

Sistema do Cliente → Validação dos Dados → API VITAE SMS → Operadora de Telecomunicações → Destinatário

Antes de submeter a mensagem, o sistema deverá validar:

1. existência das credenciais;
2. validade do número de destino;
3. existência do Sender ID;
4. existência do conteúdo da mensagem;
5. existência do Message ID;
6. cumprimento das regras de conteúdo;
7. existência de saldo suficiente.

10. Conteúdo das Mensagens

A utilização da API está sujeita aos Termos e Condições de Utilização do Serviço VITAE SMS.

É expressamente proibido utilizar a API para envio de SMS contendo:

• conteúdo político;
• conteúdo religioso;
• apostas ou jogos de fortuna ou azar;
• conteúdo referente a outra entidade sem autorização;
• utilização indevida de Sender ID de terceiros;
• conteúdo fraudulento, enganoso, ofensivo ou ilegal;
• phishing ou tentativa de obtenção de dados confidenciais;
• mensagens destinadas a destinatários obtidos de forma irregular.

A VITAE reserva-se o direito de bloquear mensagens ou suspender credenciais em caso de utilização indevida da API.

11. Segurança

O Cliente é responsável pela segurança das credenciais disponibilizadas para acesso à API.

As seguintes práticas deverão ser observadas:

• utilizar exclusivamente HTTPS;
• não divulgar credenciais;
• não guardar credenciais em código-fonte público;
• não enviar credenciais através de canais não seguros;
• utilizar variáveis de ambiente para armazenamento das credenciais;
• restringir o acesso às credenciais aos sistemas autorizados;
• comunicar imediatamente à VITAE qualquer suspeita de comprometimento;
• solicitar substituição da chave sempre que existir risco de exposição.

A utilização efectuada através das credenciais atribuídas ao Cliente será considerada utilização da respectiva conta.

12. Gestão de Erros

A aplicação integradora deverá estar preparada para tratar situações como:

• credenciais inválidas;
• Sender ID não autorizado;
• número de destino inválido;
• saldo insuficiente;
• parâmetros obrigatórios em falta;
• mensagem rejeitada;
• indisponibilidade temporária do serviço;
• erro de comunicação com a API.

O sistema do Cliente não deverá considerar uma mensagem como entregue apenas pelo facto de ter efectuado uma requisição à API.

O resultado devolvido pela API deverá ser registado para efeitos de controlo e auditoria.

13. Logs e Rastreabilidade

Recomenda-se que o sistema integrado mantenha registos de:

• Message ID;
• número de destino;
• Sender ID;
• data e hora da requisição;
• resposta da API;
• estado da operação.

Por razões de segurança, a Palavra-Chave/API Credential nunca deverá ser registada nos logs da aplicação.

14. Ambiente de Testes e Produção

A integração deverá preferencialmente passar pelas seguintes etapas:

Desenvolvimento → Testes → Homologação → Produção

Durante a fase de testes, deverão ser validados:

• autenticação;
• envio de SMS;
• Sender ID;
• números de destino;
• caracteres especiais;
• consulta de saldo;
• tratamento de erros;
• rastreabilidade através do Message ID.

A entrada em produção deverá ocorrer após confirmação de que a integração funciona correctamente.

15. Responsabilidades da VITAE

Compete à VITAE:

• disponibilizar acesso à API;
• fornecer as credenciais necessárias;
• configurar os serviços contratados;
• associar Sender IDs autorizados;
• prestar suporte técnico relativo à API;
• assegurar a operacionalidade da infraestrutura sob sua responsabilidade;
• comunicar alterações técnicas relevantes que possam afectar a integração.

16. Responsabilidades do Cliente

Compete ao Cliente:

• proteger as suas credenciais;
• utilizar exclusivamente Sender IDs autorizados;
• manter saldo suficiente;
• garantir a correcta implementação da integração;
• garantir a legitimidade dos números utilizados;
• assegurar que as mensagens cumprem os Termos e Condições;
• não disponibilizar a API ou as credenciais a terceiros sem autorização;
• implementar mecanismos adequados de tratamento de erros e segurança.

17. Utilização por Terceiros

As credenciais disponibilizadas são destinadas exclusivamente à entidade para a qual foram emitidas.

O Cliente não poderá revender, sublicenciar, ceder ou disponibilizar as credenciais da API a terceiros sem autorização expressa da VITAE.

Cada entidade deverá utilizar as suas próprias credenciais e Sender IDs devidamente autorizados.

18. Suspensão de Acesso

A VITAE poderá suspender temporariamente ou bloquear o acesso à API sempre que sejam identificadas situações como:

• utilização indevida;
• tentativa de fraude;
• comprometimento das credenciais;
• utilização de Sender ID não autorizado;
• envio de conteúdos proibidos;
• tentativa de contornar mecanismos de segurança;
• utilização susceptível de comprometer a estabilidade da plataforma.

19. Suporte à Integração

Para facilitar a integração, a VITAE poderá disponibilizar ao Cliente:

• documentação técnica da API;
• colecção Postman;
• credenciais de acesso;
• parâmetros de configuração;
• Sender ID autorizado;
• ambiente de testes, quando aplicável;
• assistência técnica durante a integração.

20. Checklist para Entrada em Produção

Antes da activação definitiva, deverá ser confirmado que:

• Conta do Cliente está activa
• Credenciais foram entregues
• Credenciais estão armazenadas de forma segura
• Sender ID está aprovado
• Endpoint de produção está configurado
• Envio de SMS foi testado
• Consulta de saldo foi testada
• Message ID está implementado
• Tratamento de erros está implementado
• Logs estão configurados
• Termos e Condições foram aceites
• Teste final de produção foi realizado

21. Aceitação

A utilização das credenciais e da API VITAE SMS implica a aceitação das condições técnicas e operacionais estabelecidas no presente documento e dos Termos e Condições de Utilização do Serviço de SMS.

O Cliente compromete-se a utilizar a API exclusivamente para finalidades legítimas, autorizadas e relacionadas com a entidade para a qual as respectivas credenciais foram emitidas.