Usendit API Specification v2 MZ

2019-07-18
uSendit API
Especificação do sistema
Versão 2.3.2
uSendit API – Especificação do sistema – v2.3.2 2019-07-18
Copyright
Todos os direitos reservados. Nenhuma parte deste documento pode ser reproduzida em
qualquer forma sem a permissão escrita do detentor dos direitos autorais. O conteúdo deste
documento está sujeito a revisão sem aviso prévio, devido ao progresso contínuo da
metodologia, desenho e desenvolvimento. A Send It não será responsável por qualquer erro
ou dano de qualquer tipo, decorrente do uso deste documento.
1
Índice
1. Versões ............................................................................................................................... 7
2. Introdução .......................................................................................................................... 8
2.1. A Send It......................................................................................................................... 8
2.2. Objectivo ....................................................................................................................... 8
2.3. Glossário ........................................................................................................................ 9
2.4. Convenções tipográficas................................................................................................ 9
3. Organização...................................................................................................................... 10
3.1. Nomenclaturas ............................................................................................................ 10
3.2. Considerações ............................................................................................................. 10
4. Descrição do serviço......................................................................................................... 11
4.1. Configuração de acesso ............................................................................................... 11
4.2. Ambiente de testes ..................................................................................................... 11
5. Operações do serviço ....................................................................................................... 13
5.1. SendMessages ............................................................................................................. 13
5.1.1. Assinatura da operação ........................................................................................... 13
5.1.2. Parâmetros .............................................................................................................. 13
5.1.3. Retorno .................................................................................................................... 15
5.2. SendMessage ............................................................................................................... 19
5.2.2. Protocolos................................................................................................................ 19
5.2.3. Parâmetros .............................................................................................................. 19
5.2.4. Retorno .................................................................................................................... 21
5.2.5. Pedido Exemplo ....................................................................................................... 23
5.3. SmsCharCounter .......................................................................................................... 24
5.3.2. Parâmetros .............................................................................................................. 24
5.3.3. Retorno .................................................................................................................... 24
5.4. GetPartnerEvents ........................................................................................................ 26
2
5.4.2. Parâmetros .............................................................................................................. 26

5.4.3. Retorno .................................................................................................................... 26
5.5. GetSchedule ................................................................................................................ 28
5.5.2. Parâmetros .............................................................................................................. 28
5.5.3. Retorno .................................................................................................................... 28
5.6. AuthenticateUser ........................................................................................................ 30
5.6.2. Parâmetros .............................................................................................................. 30
5.6.3. Retorno .................................................................................................................... 30
5.7. GetCreditPacks ............................................................................................................ 33
5.7.2. Parâmetros .............................................................................................................. 33
5.7.3. Retorno .................................................................................................................... 33
5.8. BuyCredits ................................................................................................................... 35
5.8.2. Parâmetros .............................................................................................................. 35
5.8.3. Retorno .................................................................................................................... 36
5.9. CreateAccount ............................................................................................................. 37
5.9.2. Parâmetros .............................................................................................................. 37
5.9.3. Retorno .................................................................................................................... 39
5.10. ConfirmAccount....................................................................................................... 41
5.10.2. Parâmetros .............................................................................................................. 41
5.10.3. Retorno .................................................................................................................... 41
5.11. ResendConfirmationCode ....................................................................................... 43
5.11.2. Parâmetros .............................................................................................................. 43
5.11.3. Retorno .................................................................................................................... 43
5.12. BuyCreditsWithPromotionalCode ........................................................................... 45
3

5.12.2. Parâmetros .............................................................................................................. 45
5.12.3. Retorno .................................................................................................................... 46
5.13. GetCountries............................................................................................................ 47
5.13.2. Parâmetros .............................................................................................................. 47
5.13.3. Retorno .................................................................................................................... 47
6. Considerações / Responsabilização ................................................................................. 49
7. Contactos ......................................................................................................................... 50
4
Índice de tabelas
Tabela 1 – Versões do documento................................................................................................................ 7

Tabela 2 – Convenções tipográficas ............................................................................................................. 9
Tabela 3 – Nomenclaturas do documento .............................................................................................. 10
Tabela 4 – Especificação dos parâmetros da operação SendMessages................................... 13
Tabela 5 – Especificação do tipo de dados Sms .................................................................................... 14
Tabela 6 – Especificação do tipo de dados ScheduleResult .................................................... 15
Tabela 7 – Especificação do tipo de dados ScheduleStatus .................................................... 16
Tabela 8 – Especificação do tipo de dados EventLogImportStatus ................................... 16
Tabela 9 – Especificação do tipo de dados SmsScheduled .......................................................... 17
Tabela 10 – Especificação do tipo de dados ScheduleMessageStatus ............................. 18
Tabela 11 – Especificação dos parâmetros da operação SendMessage ................................... 20
Tabela 12 – Especificação do retorno da operação SendMessage.................................................. 22
Tabela 13 – Especificação do tipo de dados ScheduleStatus .................................................. 22
Tabela 14 – Especificação do tipo de dados EventLogImportStatus ................................ 22
Tabela 16 – Especificação dos parâmetros da operação SmsCharCounter .......................... 24
Tabela 17 – Especificação do tipo de dados CharactersCountResult ............................. 24
Tabela 18 – Especificação do tipo de dados CharacteresCountStatus........................... 25
Tabela 19 – Especificação do tipo de dados MsgEncoding .......................................................... 25
Tabela 20 – Especificação dos parâmetros da operação GetPartnerEvents..................... 26
Tabela 21 – Especificação do tipo de dados GetPartnerEventsResult........................... 26
Tabela 22 – Especificação do tipo de dados GetPartnerEventStatus ............................. 27
Tabela 23 – Especificação do tipo de dados PartnerEvent ....................................................... 27
Tabela 24 – Especificação dos parâmetros da operação GetSchedule ................................... 28
Tabela 25 – Especificação do tipo de dados GetScheduleResult ......................................... 29
Tabela 26 – Especificação do tipo de dados GetScheduleStatus........................................... 29
Tabela 27 – Especificação do tipo de dados SmsScheduled ....................................................... 29
Tabela 29 – Especificação dos parâmetros da operação AuthenticateUser..................... 30
Tabela 30 – Especificação do tipo de dados AuthenticateResult ...................................... 30
Tabela 31 – Especificação do tipo de dados AuthenticateResultStatus ..................... 32
5
Tabela 32 – Especificação dos parâmetros da operação GetCreditPacks .......................... 33

Tabela 33 – Especificação do tipo de dados GetCreditPackResult ................................... 33
Tabela 34 – Especificação do tipo de dados GetCreditPacksStatus ................................ 34
Tabela 35 – Especificação do tipo de dados Pack............................................................................... 34
Tabela 36 – Especificação dos parâmetros da operação BuyCredits ...................................... 35
Tabela 37 – Especificação do tipo de dados BuyCreditsResult ............................................ 36
Tabela 38 – Especificação do tipo de dados BuyCreditsStatus ............................................ 36
Tabela 39 – Especificação dos parâmetros da operação CreateAccount ............................. 37
Tabela 40 – Especificação do tipo de dados NewAccount ............................................................. 37
Tabela 41 – Especificação do tipo de dados HowDidYouMeetUs ............................................... 38
Tabela 42 – Especificação do tipo de dados InvoiceInfo .......................................................... 39
Tabela 43 – Especificação do tipo de dados CreateAccountResult ................................... 39
Tabela 44 – Especificação do tipo de dados CreateAccountStatus ................................... 40
Tabela 45 – Especificação dos parâmetros da operação ConfirmAccount .......................... 41
Tabela 46 – Especificação do tipo de dados ConfirmAccountResult ................................ 41
Tabela 47 – Especificação do tipo de dados ConfirmAccountStatus ................................ 42
Tabela 48 – Especificação dos parâmetros da operação ResendConfirmationCode ... 43
Tabela 49 – Especificação do tipo de dados ResendConfirmationCodeResult ......... 43
Tabela 50 – Especificação do tipo de dados ResendConfirmationCodeStatus ......... 44
Tabela 51 – Especificação dos parâmetros da operação
BuyCreditsWithPromotionalCode ........................................................................................... 45
Tabela 52 – Especificação do tipo de dados
BuyCreditsWithPromotionalCodeResult .......................................................................... 46
Tabela 53 – Especificação do tipo de dados
BuyCreditsWithPromotionalCodeStatus .......................................................................... 46
Tabela 54 – Especificação dos parâmetros da operação GetCountries ................................ 47
Tabela 55 – Especificação do tipo de dados GetCountriesResult ...................................... 47
Tabela 56 – Especificação do tipo de dados GetCountriesResultStatus ..................... 48
Tabela 57 – Especificação do tipo de dados Country ...................................................................... 48
6
1. Versões
Versão Autor Descrição Data

Hugo Marçal e
1.0 Criação do documento 2015-05-29
Pedro Lopes
Actualização de endereço URL para ambiente de testes e inclusão de
1.1 Hugo Marçal 2017-01-19
suporte HTTPS
Jorge Mendes e Correcções visuais. Adição das operações GetPartnerEvents e
1.2 2017-04-06
Hugo Marçal GetSchedule.
Jorge Mendes e Adição da operação BuyCreditsWithPromotionalCode. Actualização
1.3 2017-07-27
Hugo Marçal do retorno da operação CreateAccount para incluir VerificationKey.
Alteração na operação CreateAccount: o campo InvoiceInfo
1.4 Jorge Mendes 2017-09-01
colocado como opcional.
Remoção do campo Sender da operação CreateAccount.
1.5 Hugo Marçal 2017-09-20
Actualização do enumerado de resposta da operação.
1.6 Pedro Cristina Actualização dos nomes dos campos da operação GetPartnerEvents 2018-02-28
Adicionado tipo de dados TZ. Actualizada operação SendMessages.
2.0 Pedro Cristina Adicionada operação GetCountries. Campos relacionados com 2018-04-04
créditos são agora do tipo D.
2.1 Pedro Cristina Adicionada operação SendMessage 2018-07-25
Revisão do documento. Actualização dos contactos técnicos
Jorge Mendes e
2.2 (support@sendit.pt). Adicionado capítulo sobre a solução DR 2018-07-25
Hugo Marçal
Forwarder (capítulo 6).
2.3 Pedro Cristina Adicionado exemplo para operação SendMessage 2018-08-02
2.3.1 Pedro Cristina Corrigida descrição do parâmetro sender na operação SendMessage 2018-08-23
2.3.2 Pedro Cristina Corrigido pedido exemplo da operação SendMessage 2019-07-18
Tabela 1 – Versões do documento
7
2. Introdução
2.1. A Send It
A Send It é uma empresa de consultoria estratégica e implementação tecnológica, que se

preocupa, diariamente, em ajudar os seus clientes a encontrar soluções de mobilidade
inovadoras para construir vantagens competitivas no contexto atual de globalização. Somos
diferentes na nossa atitude e abordagem e, por estes motivos, conseguimos entregar
projetos de valor assinalável aos nossos clientes, que desde 2003 nos têm distinguido com a
sua confiança.
2.2. Objectivo
O presente documento tem como objectivo apresentar a interface programática (API), para
integração dos serviços dos nossos clientes com a plataforma de envio massivo de SMSs da
Send It: o uSendit (https://usendit.co.mz).
A integração permite enviar SMSs utilizando uma conta de utilizador com características da
plataforma uSendit (permissões, créditos, entre outras) e utilizar a gateway de envio de
SMSs da Send It, sem necessidade de recorrer à complexa integração com os operadores
móveis.
Para qualquer esclarecimento sobre esta documentação ou outra questão adicional

contacte-nos através dos endereços de e-mail: tech@sendit.pt ou mkt@sendit.pt.
8
Audiência
Sistemas dos clientes do uSendit que pretendam integração com um serviço de

agendamento de SMSs de forma programática e outras operações baseadas na plataforma
uSendit.
2.3. Glossário
GMT Greenwich Mean Time

GSM Global System for Mobile Communications
HTTP Hypertext Transfer Protocol
HTTPS HyperText Transfer Protocol Secure
ISO International Organization for Standardization
MSISDN Mobile Station International Subscriber Directory Number
SMS Short Message Service
SMSC Short Message Service Centre
SOAP Simple Object Access Protocol
UCS2 2-byte Universal Character Set
UDH User Data Header
URL Uniform Resource Locator
2.4. Convenções tipográficas
Convenção Descrição
Calibri Utilizado para texto e tabelas
Calibri Utilizado para estrangeirismos
Utilizado em subtítulos que não são mencionados no índice ou utilizado para destacar o
Calibri
texto
Courier New Utilizado para código
Tabela 2 – Convenções tipográficas
9
3. Organização
3.1. Nomenclaturas
Tipo de dados dos parâmetros das operações:
Tipo Descrição Formato

A Alfanumérico String de N caracteres
I Valor numérico inteiro Intervalo: -2 147 483 648 a 2 147 483 647
B Booliano 1|0
DT Data e Hora Ver ponto 2 do subcapítulo Considerações
S Short Intervalo: -32 768 a 32 767
D Decimal Intervalo: (-7.9 x 1028 to 7.9 x 1028) / (100 to 28)
G Guid Identificador único universal alfanumérico de 128

bits
TZ Timezone String com identificador de fuso horário. Ver ponto 4

do subcapítulo Considerações
Tabela 3 – Nomenclaturas do documento
3.2. Considerações
1. As datas consideradas pelo sistema são referentes ao fuso horário de Portugal

continental, isto é, o fuso horário GMT + 0:00. De notar que, nos meses com horário
de verão, Lisboa adianta uma hora ficando com fuso horário equivalente a GMT +
1:00.
2. O formato dos DateTime (DT) deve ser segundo o padrão ISO 8601
[http://en.wikipedia.org/wiki/ISO_8601] que é o mesmo padrão utilizado no
formato das datas em XSD [http://www.w3.org/TR/xmlschema-2/#isoformats].
3. Algumas operações possuem um parâmetro de entrada Caller que identifica a
origem do pedido e será único para clientes sem requisitos específicos no âmbito do
uSendit:
Caller: 19c684fd-cee1-45fa-bf3c-812802144224
10
4. O valor dos parâmetros do tipo timezone representam um fuso horário no formato

de identificador utilizado pela base de dados tzdb1, na versão 2018c2.
4. Descrição do serviço
Esta API serve os propósitos de um serviço de envio de mensagens SMS, baseado na

plataforma uSendit, utilizando o sistema de gateway da Send It. Tecnologicamente, é um
web service SOAP que disponibiliza uma operação para agendamento de envios massivos de
SMSs contextualizados com as contas de utilizadores da plataforma uSendit.
Adicionalmente, disponibiliza outras operações auxiliares relacionadas com criação e
autenticação de utilizadores e gestão de créditos.
4.1. Configuração de acesso
• Localização:
o https://api.usendit. co.mz/v2/remoteusendit.asmx
• Protocolo:
o HTTP/SOAP
4.2. Ambiente de testes
A Send It disponibiliza um ambiente de testes das operações do serviço que permite aos
clientes simularem o agendamento de SMSs. As mensagens agendadas não serão enviadas
para os operadores móveis, dessa forma, caso esteja a integrar também com a nossa
solução de envio de relatórios de entrega, DR Forwarder3, não irá receber quaisquer
relatórios de entrega.
1 https://www.iana.org/time-zones
2 https://www.ietf.org/timezones/tzdb-2018c/
3A documentação técnica da solução de envio de relatórios de entrega, DR Forwarder, encontra-se disponível
para consulta em: http://docs.sendit.pt/DR_Forwarder_PT.zip
11
• Localização:
o https://apitest.usendit. co.mz/v2/remoteusendit.asmx
12
5. Operações do serviço
5.1. SendMessages
Operação que permite o agendamento de um envio para uma lista de contactos.
Um contacto é uma entidade que possui, entre outras, propriedades que especificam o nº
de telemóvel, texto da mensagem e data de envio.
5.1.1. Assinatura da operação
public ScheduleResult SendMessages (string username, string password, string

partnerEventId, string timezone, Sms [] smsList)
5.1.2. Parâmetros
A tabela seguinte apresenta a descrição dos parâmetros da operação.
Nome Obrigatório Tipo Dimensão Descrição

username Sim A 256 Nome de utilizador
password Sim A 20 Password de utilizador
Identificador do envio (no âmbito do
partnerEventId Não A 256
utilizador)
Identificador do fuso horário a que as datas
timezone Não TZ 100
existentes no parâmetro smsList se aplicam
>= 1 e
smsList Sim Sms [ ] Lista de contactos
<= 10 000
Tabela 4 – Especificação dos parâmetros da operação SendMessages
13
O parâmetro SmsList é um array de elementos do tipo de dados Sms. Este é um tipo

complexo que contém a informação relativa a cada mensagem e é especificado através das
seguintes propriedades:
Propriedade Obrigatório Tipo Dimensão Descrição

Identificador da mensagem (no âmbito do
PartnerMsgId Não A 256
utilizador)
Indisponível de momento. Colocar no valor deste
Sender Sim A 16
campo o valor NULL ou string vazia.
Nº de telemóvel (sem “+” e “00” e com indicativo
Msisdn Sim A 15
do país – Ex. 3519xxxxxxxx, 34xxxxxxxxx)
Identificador do operador móvel (0 – Internacional
MobileOperator Não I 1
| 21- Movitel | 22 – Vodacom | 23 – Mcel)
Data a partir da qual o SMS não será enviado para
ExpirationDatetime Não DT 19
o SMSC (operador móvel)
Prioridade do SMS. Valores entre 0 (menos
Priority Sim I 2
prioritário) e 99 (mais prioritário)
MessageText (a) Sim A 606 Conteúdo da mensagem.
ScheduleDatetime Não DT 19 Data/hora de início do envio
Hora de início do envio no dia (parte da data é
BeginTime Não DT 19
ignorada)
Hora de fim do envio no dia (parte da data é
EndTime Não DT 19
ignorada)
Indicação de envio todos os dias (false) ou apenas
WorkingDays Sim B 1
em dias da semana, 2ª a 6ª (true)
Indicação de envio da mensagem como flash
IsFlash Sim B 1 (visualizada directamente no telemóvel sem ser
guardada automaticamente)
Tabela 5 – Especificação do tipo de dados Sms
(a) A mensagem de texto pode ter as seguintes dimensões quando o seu texto é codificado
em Default GSM 7 Bit (7 bits):
• Mensagem única: 160 caracteres (máximo)
• Mensagens concatenadas: 153 caracteres (por segmento)
e as seguintes dimensões quando codificado em UCS2 (16 bits):
• Mensagem única: máx. 70 caracteres (máximo)
Cada segmento equivale a uma mensagem única para efeitos de cobrança.
(b) Aquando da execução da operação SendMessages, o envio encontra-se em estado de

“importação”, o que significa que os elementos do envio carecem ainda de
14
processamento por parte do sistema até o envio ser iniciado. Assim que o processo
terminar, o envio é iniciado automaticamente
Exemplo
Uma mensagem com 180 caracteres, codificada em GSM 7 Bit, originará 2 SMSs reais (2
segmentos):
• 1º segmento: 153 caracteres e,
• 2º segmento: 27 caracteres
pela qual o cliente será cobrado em função do número de segmentos, da seguinte forma:
• 2 vezes o valor unitário de um SMS
Para mais informações acerca dos caracteres e respectivas codificações, consultar

documento “Sendit - Short Message Length.pdf” 4. Por favor, contacte-nos em caso de
dúvida.
5.1.3. Retorno
A operação retorna um objecto do tipo de dados ScheduleResult, com a seguinte

especificação:
Propriedade Tipo Dimensão Descrição

ScheduleStatus (d) ScheduleStatus 34 Código de resultado da operação
ScheduleMessage A 300 Mensagem com resultado da operação
EventId I 10 Identificador do envio (no âmbito da Send It)
EventLogImportSta
ImportStatus(e) 9 Estado de importação do envio
tus
PartnerEventId A 256 Identificador do envio (enviado pelo utilizador)
TotalScheduledSMS I 10 Nº real de SMSs agendados (nº total de segmentos)
TotalRecipients I 6 Total de contactos do envio (não são SMSs)
AcceptedRecipients I 6 Total de contactos aceites (não são SMSs)
RejectedRecipients I 6 Total de contactos rejeitados (não são SMSs)
CreditsSpent D 10 Total de créditos gasto no envio (c)
SmsScheduledList (f) SmsScheduled [] >= 1 Lista de detalhes sobre cada SMS agendado
Tabela 6 – Especificação do tipo de dados ScheduleResult
4A documentação técnica acerca da dimensão das mensagens encontra-se disponível para consulta em:
http://docs.sendit.pt/Short_Message_Length_PT.zip
15
(c) Dependente da configuração de conta do cliente. Se a conta não contemplar controlo de

créditos o valor retornado neste campo será sempre 0. Caso contrário, será retornado o nº
de créditos gasto para realizar o envio de acordo com o total de segmentos de cada SMS, o
nº de contactos e o correspondente país de destino de cada número de telemóvel
(numeração móvel nacional de Portugal ou internacional):
• Cálculo: Nº de SMSs a enviar x Nº de créditos correspondentes
• Envios Nacionais (MZ): 1 SMS = 1 crédito (sujeito a alteração)
• Envios Internacionais: 1 SMS = 4 créditos (sujeito a alteração)
(d) O tipo do código de resultado da operação é um enumerado ScheduleStatus, com a

seguinte especificação:
Nome Valor Descrição

SCHEDULE_OK 0 Sucesso
SCHEDULE_OK_WARNING 1 Agendamento realizado mas com contactos inválidos
USER_UNKNOWN 2 Username/password inválidos
Registo de utilizador pendente de código de
USER_PENDING_SMS_CONFIRMATION_CODE 3
confirmação enviado por SMS
USER_NOT_ALLOWED 4 Utilizador não tem permissões para enviar SMS
Utilizador não possui créditos suficientes para o
INSUFFICIENT_CREDITS 5
envio
SMS_LIST_EMPTY 6 Lista de contactos null ou vazia
SMS_LIST_EXCEEDS_MAX_LENGTH 7 Lista de contactos excede a dimensão máxima
SMS_LIST_ALL_RECIPIENTS_INVALID 8 Todos os contactos da lista são inválidos
INTERNAL_CONFIGURATION_ERROR 9 Erro interno de configuração
PROCESS_SCHEDULE_LIST_ERROR 10 Erro de processamento da lista de envio
SCHEDULE_ERROR 11 Erro de agendamento
Tabela 7 – Especificação do tipo de dados ScheduleStatus
(e) O tipo do estado resultante do envio é um enumerado EventLogImportStatus, com a


IMPORTED 0 Importado
IMPORTING 1 Em importação
Tabela 8 – Especificação do tipo de dados EventLogImportStatus
16
(f) O tipo de dados SmsScheduled é um tipo complexo com a seguinte especificação:

Identificador númerico da mensagem
(no âmbito da Send It). Enquanto o
envio correspondente se encontrar em
MsgId I 10 estado de importação, este campo terá
o valor 0. No entanto, a mensagem pode
ser alternativamente identifcada pelo
valor no campo MsgGuid.
MsgGuid G 16 Identificador da mensagem
Msisdn A 15 Nº de telemóvel
ScheduleMessageStatus (g) ScheduleMessageStatus 31 Estado do processamento
Identificador da mensagem (no âmbito
do utilizador) que corresponde ao
PartnerMsgId A 256
identificador enviado, para cada SMS, no
parâmetro SmsList desta operação
Nº real de segmentos a que o texto deu
NumberSMS S 2
origem (de acordo com a codificação)
Tabela 9 – Especificação do tipo de dados SmsScheduled
17
(g) A propriedade ScheduleMessageStatus é um enumerado com a seguinte especificação:

SCHEDULED 0 Válido para enviar
MSISDN_EMPTY 1 MSISDN null ou vazio
MSISDN_EXCEEDS_MAX_LENGTH 2 MSISDN excede a dimensão máxima
MSISDN_INVALID 3 MSISDN inválido
MSISDN_MOBILE_OPERATOR_UNKNOWN 4 Operador móvel desconhecido
MSISDN_INVALID_ROUTE 5 Impossível determinar rota de envio
MESSAGE_TEXT_EMPTY 6 Texto da mensagem vazio
MESSAGE_TEXT_EXCEEDS_MAX_LENGTH 7 Texto da mensagem excede a dimensão máxima
SENDER_EXCEEDS_MAX_LENGTH 8 Remetente excede a dimensão máxima
SENDER_NOT_ALLOWED 9 Remetente inválido para o utilizador
PRIORITY_INVALID 10 Valor de prioridade inválida
EXPIRATION_DATETIME_INVALID 11 Data de expiração inválida (h)
Tabela 10 – Especificação do tipo de dados ScheduleMessageStatus
(h) A data de expiração é considerada inválida nas seguintes condições: é inferior à data do
envio, inferior à data atual se não for especificada data de envio e hora de início, inferior à
composição da data atual com a hora de início ou inferior à composição da data atual com a
hora de fim.
18
5.2. SendMessage
Operação que permite o agendamento de um envio para um contacto.

public string SendMessage(string username, string password, string
partnerEventId, string timezone, string partnerMsgId, string sender, string
msisdn, int mobileOperator, int priority, string expirationDatetime, string
messageText, string scheduleDatetime, string beginTime, string endTime, bool
workingDays, bool isFlash)
5.2.2. Protocolos
Em adição ao protocolo HTTPS/SOAP, esta operação pode ser invocada utilizando um pedido
HTTP GET ou POST, devendo os seus parâmetros ser passados no formato de query string5
no URL ou no corpo do pedido (no caso de POST).
5.2.3. Parâmetros
Obrigat
Nome Tipo Dimensão Descrição
ório
Identificador do envio (no âmbito do
partnerEventId Não A 256
utilizador)
Identificador do fuso horário a que as datas
timezone Não TZ 100
existentes no parâmetro smsList se aplicam
partnerMsgId Não A 256
utilizador)
Indisponível de momento. Colocar no valor
sender Sim A 16
deste campo o valor NULL ou string vazia.
Nº de telemóvel (sem “+” e “00” e com
msisdn Sim A 15 indicativo do país – Ex. 3519xxxxxxxx,
34xxxxxxxxx)
Identificador do operador móvel (-1 – Será
inferido pelo sistema da Sendit | 0 –
mobileOperator Sim I 1
Internacional | 21- Movitel | 22 – Vodacom
| 23 – Mcel)
expirationDatetim Data a partir da qual o SMS não será
Não DT 19
e enviado para o SMSC (operador móvel)
priority Sim I 2 Prioridade do SMS. Valores entre 0 (menos
5 https://en.wikipedia.org/wiki/Query_string
19
prioritário) e 99 (mais prioritário)

messageText Sim A 606 Conteúdo da mensagem.
scheduleDatetime Não DT 19 Data/hora de início do envio
Hora de início do envio no dia (parte da
beginTime Não DT 19
data é ignorada)
Hora de fim do envio no dia (parte da data
endTime Não DT 19
é ignorada)
Indicação de envio todos os dias (false) ou
workingDays Sim B 1
apenas em dias da semana, 2ª a 6ª (true)
Indicação de envio da mensagem como
flash (visualizada directamente no
isFlash Sim B 1
telemóvel sem ser guardada
automaticamente)
Tabela 11 – Especificação dos parâmetros da operação SendMessage
(a) O envio de SMSs para números internacionais (não pertencentes à rede móvel de Portugal) deve
ser realizado com remetente numérico (máx. 16 dígitos) para garantia de entrega das mensagens nos
operadores de destino, segundo a recomendação dos operadores móveis.
(b) A mensagem de texto pode ter as seguintes dimensões quando o seu texto é codificado
em Default GSM 7 Bit (7 bits):
• Mensagem única: 160 caracteres (máximo)
e as seguintes dimensões quando codificado em UCS2 (16 bits):
• Mensagem única: máx. 70 caracteres (máximo)
Cada segmento equivale a uma mensagem única para efeitos de cobrança.
(c) Aquando da execução da operação SendMessage, o envio encontra-se em estado de

“importação”, o que significa que os elementos do envio carecem ainda de
processamento por parte do sistema até o envio ser iniciado. Assim que o processo
terminar, o envio é iniciado automaticamente
Exemplo
Uma mensagem com 180 caracteres, codificada em GSM 7 Bit, originará 2 SMSs reais (2
segmentos):
• 1º segmento: 153 caracteres e,
• 2º segmento: 27 caracteres
20
pela qual o cliente será cobrado em função do número de segmentos, da seguinte forma:
• 2 vezes o valor unitário de um SMS
Para mais informações acerca dos caracteres e respectivas codificações, consultar

documento “Sendit - Short Message Length.pdf” 6. Por favor, contacte-nos em caso de
dúvida.
5.2.4. Retorno
A operação retorna um objecto do tipo de dados string, em formato query string, com a

ScheduleStatus (d) ScheduleStatus 34 Código de resultado da operação
EventLogImportSta
ImportStatus(e) 9 Estado de importação do envio
tus
PartnerEventId A 256 Identificador do envio (enviado pelo utilizador)
TotalScheduledSMS I 10 Nº real de SMSs agendados (nº total de segmentos)
TotalRecipients I 6 Total de contactos do envio (não são SMSs)
AcceptedRecipients I 6 Total de contactos aceites (não são SMSs)
RejectedRecipients I 6 Total de contactos rejeitados (não são SMSs)
CreditsSpent D 10 Total de créditos gasto no envio (c)
Identificador númerico da mensagem (no âmbito
da Send It). Enquanto o envio correspondente se
encontrar em estado de importação, este campo
MsgId I 10
terá o valor 0. No entanto, a mensagem pode ser
alternativamente identifcada pelo valor no campo
MsgGuid.
MsgGuid G 16 Identificador da mensagem
ScheduleMessageStat ScheduleMessageSt
31 Estado do processamento
us (f) atus
utilizador) que corresponde ao identificador
PartnerMsgId A 256
enviado, para cada SMS, no parâmetro SmsList
desta operação
Nº real de segmentos a que o texto deu origem (de
NumberSMS S 2
acordo com a codificação)
6A documentação técnica acerca da dimensão das mensagens encontra-se disponível para consulta em:
http://docs.sendit.pt/Short_Message_Length_PT.zip
21
Tabela 12 – Especificação do retorno da operação SendMessage
(c) Dependente da configuração de conta do cliente. Se a conta não contemplar controlo de

créditos o valor retornado neste campo será sempre 0. Caso contrário, será retornado o nº
de créditos gasto para realizar o envio de acordo com o total de segmentos de cada SMS, o
nº de contactos e o correspondente país de destino de cada número de telemóvel
(numeração móvel nacional de Portugal ou internacional):
• Cálculo: Nº de SMSs a enviar x Nº de créditos correspondentes
• Envios Nacionais (PT): 1 SMS = 1 crédito (sujeito a alteração)
• Envios Internacionais: 1 SMS = 4 créditos (sujeito a alteração)
(d) O tipo do código de resultado da operação é um enumerado ScheduleStatus, com a


Registo de utilizador pendente de código de
USER_PENDING_SMS_CONFIRMATION_CODE 3
confirmação enviado por SMS
Utilizador não possui créditos suficientes para o
INSUFFICIENT_CREDITS 5
envio
SMS_LIST_EMPTY 6 Lista de contactos null ou vazia
SMS_LIST_EXCEEDS_MAX_LENGTH 7 Lista de contactos excede a dimensão máxima
INTERNAL_CONFIGURATION_ERROR 9 Erro interno de configuração
PROCESS_SCHEDULE_LIST_ERROR 10 Erro de processamento da lista de envio
Tabela 13 – Especificação do tipo de dados ScheduleStatus
(e) O tipo do estado resultante do envio é um enumerado EventLogImportStatus, com a


IMPORTED 0 Importado
IMPORTING 1 Em importação
Tabela 14 – Especificação do tipo de dados EventLogImportStatus
22
(f) A propriedade ScheduleMessageStatus é um enumerado com a seguinte especificação:

EXPIRATION_DATETIME_INVALID 11 Data de expiração inválida (g)
(g) A data de expiração é considerada inválida nas seguintes condições: é inferior à data do
envio, inferior à data atual se não for especificada data de envio e hora de início, inferior à
composição da data atual com a hora de início ou inferior à composição da data atual com a
hora de fim.
5.2.5. Pedido Exemplo
Exemplifica-se abaixo um pedido de invocação da operação SendMessage, na API de

ambiente de testes.
HTTP/GET
https://apitest.usendit.co.mz/v2/remoteusendit.asmx/SendMessage?username=<yourusername>&
password=<your password>&partnerEventId=&timezone=&partnerMsgId=&sender=
uSendit&msisdn=3519xxxxxxxx&mobileOperator=-
1&priority=0&expirationDatetime=&messageText=teste&scheduleDatetime=&beginTime=&endTim
e=&workingDays=false&isFlash=false
23
5.3. SmsCharCounter
Operação que permite contar o número de caracteres de um texto. Retorna a codificação

necessária para enviar o SMS e o nº real de segmentos (mensagens) a que o texto dará
origem.
public CharactersCountResult SmsCharCounter(string messageText)
5.3.2. Parâmetros

messageText Sim A 606 Texto da mensagem
Tabela 16 – Especificação dos parâmetros da operação SmsCharCounter
5.3.3. Retorno
A operação retorna um objecto do tipo de dados CharacterCountResult, com a seguinte

especificação:

CharactersCountStatus (h) CharactersCountStatus 7 Código de resultado da operação
CharactersCountMessage A 300 Mensagem com resultado da operação
CharactersNumber I 4 Nº de caracteres do texto
Nº total de caracteres disponíveis de acordo
CharactersTotalNumber I 4
com o nº de segmentos
Enconding (i) MsgEncoding 4 Codificação do SMS para enviar o texto
Nº de segmentos necessários para enviar o
SegmentsNumber I 4
SMS com o texto
Tabela 17 – Especificação do tipo de dados CharactersCountResult
24
(h) O tipo do código de resultado da operação é um enumerado

CharactersCountStatus, com a seguinte especificação:

SUCCESS 0 Sucesso na operação
ERROR 1 Erro de processamento do pedido
Tabela 18 – Especificação do tipo de dados CharacteresCountStatus
(i) A codificação do SMS é um enumerado MsgEncoding, com a seguinte especificação:

GSM7 0 Codificação a 7 bits, alfabeto GSM 7 Bit
UCS2 1 Codificação a 16 bits
Tabela 19 – Especificação do tipo de dados MsgEncoding
Exemplo
• MessageText: mensagem de teste
• CharactersNumber: 17
• CharactersTotalNumber: 160
• SegmentsNumber: 1
• Encoding: GSM7
25
5.4. GetPartnerEvents
Operação que permite obter uma lista de eventos (no âmbito da Send It) para um
determinado PartnerEventId do utilizador.
public GetPartnerEventsResult GetPartnerEvents(string username, string

password, string partnerEventId)
5.4.2. Parâmetros

partnerEventId Sim A 256 Identificador do envio (enviado pelo utilizador)
Tabela 20 – Especificação dos parâmetros da operação GetPartnerEvents
5.4.3. Retorno
A operação retorna um objecto do tipo de dados GetPartnerEventsResult, com a


PartnerEventsStatus (j) GetPartnerEventsStatus 4 Código de resultado da operação
Lista do tipo PartnerEvent com informação
PartnerEvents (k) PartnerEvent [] 4 dos Ids de agendamento para o respectivo
PartnerEventId
Tabela 21 – Especificação do tipo de dados GetPartnerEventsResult
26
(j) O tipo do código de resultado da operação é um enumerado

GetPartnerEventsStatus, com a seguinte especificação:

SUCCESS 0 Sucesso
USER_NOT_ALLOWED 2 Utilizador não tem permissões para esta operação
GENERIC_ERROR 3 Erro
Tabela 22 – Especificação do tipo de dados GetPartnerEventStatus
(k) O tipo de dados PartnerEvent é um tipo complexo com a seguinte especificação:

Identificador do envio (enviado pelo
PartnerEventId A 300
utilizador)
Identificador do envio (no âmbito da
EventId I 10
Send It)
Tabela 23 – Especificação do tipo de dados PartnerEvent
27
5.5. GetSchedule
Operação que permite obter a informação de um agendamento. Retorna a informação do

agendamento à semelhança do que é retornado na operação SendMessages.
public GetScheduleResult GetSchedule(string username, string password, int

eventId)
5.5.2. Parâmetros

Identificador do envio recebido (no âmbito da Send It) na
eventId Sim I 10
operação SendMessages
Tabela 24 – Especificação dos parâmetros da operação GetSchedule
5.5.3. Retorno
A operação retorna um objecto do tipo de dados GetScheduleResult, com a seguinte

especificação:
ScheduleStatus (l) GetScheduleStatus 7 Código de resultado da operação
ImportStatus EventLogImportStatus 9 Estado de importação do envio
Identificador do envio (enviado pelo
PartnerEventId A 256
utilizador)
Nº real de SMSs agendados (nº total de
TotalScheduledSMS I 10
segmentos)
TotalRecipients I 6 Total de contactos do envio (não são SMS)
AcceptedRecipients I 6 Total de contactos aceite (não são SMS)
RejectedRecipients I 6 Total de contactos rejeitados (não são SMS)
CreditsSpent I 10 Total de créditos gastos no envio
SmsScheduledList (m) SmsScheduled [] >= 1 Lista de detalhes sobre cada SMS agendado
28
Tabela 25 – Especificação do tipo de dados GetScheduleResult
(l) O tipo do código de resultado da operação é um enumerado GetScheduleStatus, com

a seguinte especificação:

SCHEDULE_UNKNOWN 6 Não há envios para o respectivo EventId
Tabela 26 – Especificação do tipo de dados GetScheduleStatus
(m) O tipo de dados SmsScheduled é um tipo complexo com a seguinte especificação:

MsgId I 10
da Send It)
ScheduleMessageStatus (n) ScheduleMessageStatus 31 Estado do processamento
do utilizador) que corresponde ao
PartnerMsgId A 256
identificador enviado, para cada SMS, no
parâmetro SmsList desta operação
Nº real de segmentos a que o texto deu
NumberSMS S 2
origem (de acordo com a codificação)
Tabela 27 – Especificação do tipo de dados SmsScheduled
(n) A propriedade ScheduleMessageStatus é um enumerado com a seguinte especificação:

EXPIRATION_DATETIME_INVALID 11 Data de expiração inválida
29
(m) Nota: Se o valor do campo ImportStatus for IMPORTING, então o campo

SmsScheduledList não terá qualquer valor, uma vez que o envio ainda se encontra em
processamento.
5.6. AuthenticateUser
Esta operação serve exclusivamente para validar os dados de acesso e estado de uma conta
de utilizador. Caso seja autenticado com sucesso, será retornado o número de créditos
disponíveis para esse utilizador.
public AuthenticateResult AuthenticateUser(string username, string password)
5.6.2. Parâmetros

Tabela 29 – Especificação dos parâmetros da operação AuthenticateUser
5.6.3. Retorno
A operação retorna um objecto do tipo de dados AuthenticateResult, com a seguinte

especificação:

AuthenticateResultStatus (o) AuthenticateResultStatus 7 Código de resultado da operação
AuthenticateResultMessage A 300 Mensagem com resultado da operação
UserCredits I 4 Nº de créditos do utilizador
Tabela 30 – Especificação do tipo de dados AuthenticateResult
30
31
(o) O tipo do código de resultado da operação é um enumerado

AuthenticateResultStatus, com a seguinte especificação:

USER_UNKNOWN 1 Dados de autenticação inválidos
O utilizador não confirmou a conta depois de
efetuar o registo. Terá de aceder à plataforma para
PENDING_SMS_CONFIRMATION_CODE 2
confirmar a conta por código de SMS ou utilizar o
endereço fornecido no email que foi enviado
GENERIC_ERROR 3 Erro no processamento do pedido
Tabela 31 – Especificação do tipo de dados AuthenticateResultStatus
32
5.7. GetCreditPacks
Operação para obter os pacotes de créditos disponíveis para compra.
public GetCreditPackResult GetCreditPacks(string username, string password)
5.7.2. Parâmetros

Tabela 32 – Especificação dos parâmetros da operação GetCreditPacks
5.7.3. Retorno
A operação retorna um objecto do tipo de dados GetCreditPackResult, com a seguinte

especificação:

GetCreditPacksStatus (p) GetCreditPacksStatus 7 Código de resultado da operação
GetCreditPacksMessage A 300 Mensagem com resultado da operação
Packs (q) Pack [] >= 1 Lista de pacotes disponíveis
AccountName A 256 Nome da conta
Tabela 33 – Especificação do tipo de dados GetCreditPackResult
33
(p) O tipo do código de resultado da operação é um enumerado GetCreditPacksStatus,

com a seguinte especificação:

O utilizador não confirmou a conta depois de efetuar o
registo. Terá de aceder à plataforma para confirmar a
conta por código de SMS ou utilizar o endereço
fornecido no email que foi enviado
Não existem pacotes disponíveis para compra de
NO_CREDIT_PACKS_AVAILABLE 3
momento
Tabela 34 – Especificação do tipo de dados GetCreditPacksStatus
(q) O tipo de dados Pack é um tipo complexo com a seguinte especificação:

Identificador do pacote (no âmbito da
Id I 10
Send It)
Description A 256 Designação do pacote
Credits D 4 Nº de créditos disponíveis no pacote
Price D 16 Preço do pacote (IVA não incluído)
TaxPercentage D 16 Taxa de IVA em vigor
TotalPrice D 16 Preço do pacote (IVA incluído)
Tabela 35 – Especificação do tipo de dados Pack
34
5.8. BuyCredits
Operação para obter os dados de pagamento de um pacote de créditos. A forma de

pagamento será através de multibanco (ATM ou homebanking) ou cartão de crédito (em
website de parceiro de pagamentos).
Nota: A Send It utiliza, como parceiro tecnológico de pagamentos electrónicos, a Easypay

(www.easypay.pt), entidade devidamente referenciada no mercado. Os pagamentos via
cartão de crédito são realizados em website do parceiro.
public BuyCreditsResult BuyCredits(string username, string password, short

packId, string caller)
5.8.2. Parâmetros

Identificador do pacote (no âmbito da Send It) retornado
packId Sim S 2
após invocação da operação GetCreditPacks.
caller Sim A 256 Consultar ponto 3.2 Considerações deste documento
Tabela 36 – Especificação dos parâmetros da operação BuyCredits
35
5.8.3. Retorno
A operação retorna um objecto do tipo de dados BuyCreditsResult, com a seguinte

especificação:

BuyCreditsStatus (r) BuyCreditsStatus 7 Código de resultado da operação
BuyCreditsMessage A 300 Mensagem com resultado da operação
Entity A 265 Entidade para pagamento
PaymentReference A 256 Referência para pagamento
Amount A 256 Valor para pagamento
Endereço para pagamento via cartão de
CreditCardLink A 256
crédito (ligação segura com Easypay)
Tabela 37 – Especificação do tipo de dados BuyCreditsResult
(r) O tipo do código de resultado da operação é um enumerado BuyCreditsStatus, com a


O utilizador não confirmou a conta depois de efetuar
o registo. Terá de aceder à plataforma para confirmar
a conta por código de SMS ou utilizar o endereço
INVALID_PACK_ID 3 Identificador do pacote não é reconhecido
ERROR_GENERATING_PAYMENT_REFERENCE 4 Ocorreu um erro a gerar a referência para pagamento
A identificação da origem do pedido não foi
CALLER_UNKNOWN 5
reconhecida
É necessário fornecer os dados de faturação no
MISSING_INVOICE_INFO 6
registo ou na plataforma em usendit.co.mz
Tabela 38 – Especificação do tipo de dados BuyCreditsStatus
36
5.9. CreateAccount
Operação que permite a criação de conta no uSendit. Retorna um token (VerificationKey)

que pode ser utilizado em caso de redirect do utilizador para a página do uSendit onde pode
confirmar a criação de conta através do código numérico enviado por SMS
(https://usendit.co.mz/Account/Register/ConfirmSMS?key=abcdefgh123).
public CreateAccountResult CreateAccount(NewAccount newAccount, InvoiceInfo

invoiceInfo, string caller)
5.9.2. Parâmetros

newAccount Sim NewAccount (s) Informação dos dados da conta a ser criada
invoiceInfo Não InvoiceInfo (t) Dados para faturação
Consultar ponto 3.2 Considerações deste
caller Sim A 256
documento
Tabela 39 – Especificação dos parâmetros da operação CreateAccount
(s) Um dos parâmetros da operação é do tipo NewAccount, com a seguinte especificação:

AccountName A 256 Nome e descrição da conta
Username A 256 Nome de utilizador para autenticar a conta
Password usada para autenticar a conta (Entre

Password A 20 5 e 20 caracteres com, pelo menos, uma letra
e um caracter de outro tipo)
Email A 256 Email do utilizador
Identificador do país (ver operação
Country I 2
GetCountries)
Nº de telemóvel (sem “+” e “00” e com
Msisdn A 15
indicativo do país - Ex. 3519xxxxxx, 34xxxxxxx)
HowDidYouFindUs HowDidYouMeetUs (v) 2 Indicação de como conheceu a plataforma
Indicação se o utilizador pretende receber
AllowMarketingCampaigns B 1
informações e/ou ofertas de marketing
Tabela 40 – Especificação do tipo de dados NewAccount
37
(t) A operação possui ainda um parâmetro caracterizado pelo enumerado com tipo
HowDidYouMeetUs, com a seguinte especificação:
Nome Descrição
SMS_MARKETING Sms marketing
EMAIL_MARKETING Email marketing
FACEBOOK Facebook
LINKED_IN LinkedIn
RECOMMENDATION Recomendação de terceiros
COMMERCIAL_AGENT Agente comercial
INTERNET_SEARCH Pesquisa na internet
TV_SPOT Anúncio televisivo
WEB_SITE_SPOT Anúncios nos websites de parceiros
OTHER Outro
Tabela 41 – Especificação do tipo de dados HowDidYouMeetUs
38
(v) A operação CreateAccount possui ainda um parâmetro caracterizado pelo objeto com
tipo InvoiceInfo, com a seguinte especificação:

Name A 4000 Nome da pessoa ou empresa a faturar
Address A 4000 Morada a faturar
TaxIdentificationNumber A 20 NIF a constar na fatura
Email A 256 Email para onde será enviada a faturação
Country A 256 País
City A 256 Cidade
ZipCode A 256 Código Postal
Tabela 42 – Especificação do tipo de dados InvoiceInfo
5.9.3. Retorno
A operação retorna um objecto do tipo de dados CreateAccountResult, com a seguinte

especificação:

CreateAccountStatus (x) CreateAccountStatus 7 Código de resultado da operação
CreateAccountMessage A 300 Mensagem com resultado da operação
Token associado ao registo do utilizador.
Pode ser usado na página
VerificationKey A 100 (https://usendit.co.mz/Account/Register/C
onfirmSMS?key=abcdefgh123) para
confirmar o registo.
Tabela 43 – Especificação do tipo de dados CreateAccountResult
39
(x) O tipo do código de resultado da operação é um enumerado CreateAccountStatus,


USERNAME_EMPTY 1 Nome de utilizador vazio
USERNAME_NOT_ALLOWED 2 Nome de utilizador não permitido
USERNAME_EXCEEDS_MAX_LENGTH 3 Nome de utilizador excede o limite de caracteres
PASSWORD_EXCEEDS_MAX_LENGTH 4 Password excede o limite de caracteres
PASSWORD_INVALID 5 Password inválida
EMAIL_EXCEEDS_MAX_LENGTH 6 Email excede o limite de caracteres
EMAIL_INVALID 7 Endereço de email inválido
MSISDN_EXCEEDS_MAX_LENGTH 8 Msisdn excede o limite
MSISDN_INVALID 9 Msisdn inválido
MSISDN_ALREADY_IN_USE 10 O Msisdn fornecido já se encontra em uso
ACCOUNT_NAME_EMPTY 11 Nome da conta vazio
ACCOUNT_NAME_EXCEEDS_MAX_LENGTH 12 Nome da conta excede o limite de caracteres
ACCOUNT_NAME_NOT_ALLOWED 13 Nome da conta não permitido
CALLER_UNKNOWN 17 Chave do originador não existente
ERROR_SENDING_SMS_CONFIRMATION 18 Ocorreu um erro a enviar a SMS de confirmação
ACCOUNT_VALIDATION_ERROR 19 Ocorreu um erro na validação da conta
USERNAME_OR_EMAIL_ALREADY_IN_USE 20 Nome de utilizador ou email já se encontra em uso
ACCOUNT_INFO_EMPTY 21 Informação de conta incompleta
INVOICE_INFO_EMPTY 22 Informação de faturação incompleta
INVOICE_INFO_INVALID 23 Informação de faturação contém campos inválidos
Tabela 44 – Especificação do tipo de dados CreateAccountStatus
40
5.10. ConfirmAccount
Operação para efetuar a confirmação de uma conta previamente criada. Ao efetuar a

criação de uma conta, irá receber um código de confirmação por SMS que irá servir para
confirmar o registo através desta operação.
public ConfirmAccountResult ConfirmAccount(string username, string password,

short confirmationCode)
5.10.2. Parâmetros

Código de confirmação recebido por SMS na criação
confirmationCode Sim A 10
de conta
Tabela 45 – Especificação dos parâmetros da operação ConfirmAccount
5.10.3. Retorno
A operação retorna um objecto do tipo de dados ConfirmAccountResult, com a seguinte

especificação:

ConfirmAccountStatus (y) ConfirmAccountStatus 7 Código de resultado da operação
ConfirmAccountMessage A 300 Mensagem com resultado da operação
Tabela 46 – Especificação do tipo de dados ConfirmAccountResult
41
(y) O tipo do código de resultado da operação é um enumerado ConfirmAccountStatus,


EMPTY_CONFIRMATION_CODE 2 Código de confirmação vazio
INVALID_CONFIRMATION_CODE 3 Código de confirmação não reconhecido
ACCOUNT_ALREADY_CONFIRMED 4 A conta já foi confirmada
Tabela 47 – Especificação do tipo de dados ConfirmAccountStatus
42
5.11. ResendConfirmationCode
Operação que permite o reenvio do código de confirmação de conta para o número de

telefone especificado no registo.
public ResendConfirmationCodeResult ResendConfirmationCode(string username,

string password)
5.11.2. Parâmetros

Tabela 48 – Especificação dos parâmetros da operação ResendConfirmationCode
5.11.3. Retorno
A operação retorna um objecto do tipo de dados ResendConfirmationCodeResult, com

a seguinte especificação:

Código de resultado da
ResendConfirmationCodeStatus (z) ResendConfirmationCodeStatus 7
operação
Mensagem com resultado
ResendConfirmationCodeMessage A 300
da operação
Tabela 49 – Especificação do tipo de dados ResendConfirmationCodeResult
43
(z) O tipo do código de resultado da operação é um enumerado

ResendConfirmationCodeStatus, com a seguinte especificação:

NO_MORE_RETRIES_ALLOWED 2 Atingiu o número máximo de reenvios do código
ERROR_RESENDING_SMS_CONFIRMATION 3 Ocorreu um erro no envio do código
ACCOUNT_ALREADY_CONFIRMED 4 A conta já foi confirmada
Tabela 50 – Especificação do tipo de dados ResendConfirmationCodeStatus
44
5.12. BuyCreditsWithPromotionalCode
Operação para obter os dados de pagamento de um pacote de créditos utilizando um código

promocional. A forma de pagamento será através de multibanco (ATM ou homebanking) ou
cartão de crédito (em website de parceiro de pagamentos).
Nota: A Send It utiliza, como parceiro tecnológico de pagamentos electrónicos, a Easypay

(www.easypay.pt), entidade devidamente referenciada no mercado. Os pagamentos via
cartão de crédito são realizados em website do parceiro.
public BuyCreditsWithPromotionalCodeResult BuyCreditsWithPromotionalCode

(string username, string password, short packId, string code, string caller)
5.12.2. Parâmetros

Identificador do pacote (no âmbito da Send It) retornado
packId Sim S 2
após invocação da operação GetCreditPacks.
code Sim A 256 Código promocional a redimir
caller Sim A 256 Consultar ponto 3.2 Considerações deste documento
Tabela 51 – Especificação dos parâmetros da operação BuyCreditsWithPromotionalCode
45
5.12.3. Retorno
A operação retorna um objecto do tipo de dados

BuyCreditsWithPromotionalCodeResult, com a seguinte especificação:

BuyCreditsWithPromotional BuyCreditsWithPromotio
11 Código de resultado da operação
CodeStatus (aa) nalCodeStatus
BuyCreditsWithPromotional
A 300 Mensagem com resultado da operação
CodeMessage
Entity A 265 Entidade para pagamento
PaymentReference A 256 Referência para pagamento
Amount A 256 Valor para pagamento
Endereço para pagamento via cartão de
CreditCardLink A 256
crédito (ligação segura com Easypay)
Tabela 52 – Especificação do tipo de dados BuyCreditsWithPromotionalCodeResult
(aa) O tipo do código de resultado da operação é um enumerado

BuyCreditsWithPromotionalCodeStatus, com a seguinte especificação:

O utilizador não confirmou a conta depois de efetuar
o registo. Terá de aceder à plataforma para confirmar
a conta por código de SMS ou utilizar o endereço
INVALID_PACK_ID 3 Identificador do pacote não é reconhecido
ERROR_GENERATING_PAYMENT_REFERENCE 4 Ocorreu um erro a gerar a referência para pagamento
A identificação da origem do pedido não foi
CALLER_UNKNOWN 5
reconhecida
É necessário fornecer os dados de faturação no
MISSING_INVOICE_INFO 6
registo ou na plataforma em usendit.co.mz
Não existe nenhuma campanha promocional a
PROMOTIONAL_CAMPAIGN_NOT_EXISTS 7
decorrer com o código indicado
PROMOTIONAL_CAMPAIGN_NOT_ACTIVE 8 Campanha promocional não se encontra ativa
PROMOTIONAL_CAMPAIGN_EXCEEDED_MAX
9 Número máximo de redenções do código excedido
_CODE_REDEMPTION
O código promocional não é aplicável ao pack
PROMOTIONAL_CAMPAIGN_INVALID_PACK 10
escolhido
Tabela 53 – Especificação do tipo de dados BuyCreditsWithPromotionalCodeStatus
46
5.13. GetCountries
Operação que permite obter a lista de países suportados pelo sistema
public GetCountriesResult GetCountries(string username, string password)
5.13.2. Parâmetros

Tabela 54 – Especificação dos parâmetros da operação GetCountries
5.13.3. Retorno
A operação retorna um objecto do tipo de dados GetCountriesResult, com a seguinte

especificação:

Código de resultado da
GetCountriesResultStatus (a) GetCountriesResultStatus 7
operação
Mensagem com resultado
GetCountriesResultMessage A 300
da operação
Countries(b) Country[] Lista de países
Tabela 55 – Especificação do tipo de dados GetCountriesResult
47
(a) O tipo do código de resultado da operação é um enumerado

GetCountriesResultStatus, com a seguinte especificação:

Tabela 56 – Especificação do tipo de dados GetCountriesResultStatus
(b) O tipo de dados Country é um tipo complexo com a seguinte especificação:

Id I 10 Identificador do país
ShortName A 10 Nome curto do país
Tabela 57 – Especificação do tipo de dados Country
48
6. Considerações / Responsabilização
A Send It recomenda aos clientes que realizem a integração com este serviço que nos
solicitem apoio em toda e qualquer circunstância que se revele necessária. Adicionalmente,
indicamos, desde já, algumas considerações relevantes para o desenvolvimento de um
módulo de integração com este serviço:
1. O cliente deve estar ciente da dimensão dos pedidos e respostas que serão
enviados/recebidos na interação com o serviço;
2. O cliente deve, igualmente, determinar o tempo necessário para a realização dos
pedidos e aceitação das respectivas respostas do serviço;
3. A incorrecta avaliação do tempo e da quantidade de dados necessários para
recepcionar a resposta de um pedido pode originar timeouts na resposta (do lado do
cliente). Nota: embora ocorra timeout do lado do cliente, o pedido continua a ser
processado do lado do servidor / serviço;
4. O timeout do lado do cliente não permite inferir qualquer conclusão acerca do
resultado do processamento do pedido. Sempre que ocorra timeout do lado do
cliente deve, este, contactar a Send It antes de realizar um retry para determinar
qual foi a conclusão do processamento do pedido anterior (erro ou sucesso);
5. A realização de retries sem determinação do resultado prévio da execução de um
pedido ao serviço pode originar múltiplas repetições do mesmo envio e o cliente
pode incorrer em custos indeterminados;
6. A Send It não tem qualquer responsabilidade na implementação e operação do
módulo de integração com o serviço. A Sendit está, por este motivo, ausente de
qualquer forma de responsabilização em caso de comportamento não previsto
(repetições de envios, pedidos mal parametrizados, entre outros) excepto quando
se verifique ser consequência de falha de operação do serviço.
49
7. Contactos
Em caso de dúvida ou esclarecimento adicional, contacte-nos através dos seguintes

endereços de acordo com o assunto em questão:
• Contacto técnico:
o tech@sendit.pt
• Contacto comercial:
o suporte.comercial@sendit.pt
50

Idioma

Usendit API Specification v2 MZ

Enviado por

Dados do documento

Título original

Direitos autorais

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Usendit API Specification v2 MZ

Enviado por

Direitos autorais:

2019-07-18

5.4.2. Parâmetros .............................................................................................................. 26

5.12.1. Assinatura da operação ........................................................................................... 45

Tabela 1 – Versões do documento................................................................................................................ 7

Tabela 32 – Especificação dos parâmetros da operação GetCreditPacks .......................... 33

Versão Autor Descrição Data

Tabela 1 – Versões do documento

A Send It é uma empresa de consultoria estratégica e implementação tecnológica, que se

Para qualquer esclarecimento sobre esta documentação ou outra questão adicional

Sistemas dos clientes do uSendit que pretendam integração com um serviço de

GMT Greenwich Mean Time

2.4. Convenções tipográficas

Tabela 2 – Convenções tipográficas

Tipo de dados dos parâmetros das operações:

Tipo Descrição Formato

G Guid Identificador único universal alfanumérico de 128

TZ Timezone String com identificador de fuso horário. Ver ponto 4

Tabela 3 – Nomenclaturas do documento

1. As datas consideradas pelo sistema são referentes ao fuso horário de Portugal

4. O valor dos parâmetros do tipo timezone representam um fuso horário no formato

Esta API serve os propósitos de um serviço de envio de mensagens SMS, baseado na

4.1. Configuração de acesso

4.2. Ambiente de testes

Operação que permite o agendamento de um envio para uma lista de contactos.

5.1.1. Assinatura da operação

public ScheduleResult SendMessages (string username, string password, string

A tabela seguinte apresenta a descrição dos parâmetros da operação.

Nome Obrigatório Tipo Dimensão Descrição

Tabela 4 – Especificação dos parâmetros da operação SendMessages

O parâmetro SmsList é um array de elementos do tipo de dados Sms. Este é um tipo

Propriedade Obrigatório Tipo Dimensão Descrição

Tabela 5 – Especificação do tipo de dados Sms

Cada segmento equivale a uma mensagem única para efeitos de cobrança.

(b) Aquando da execução da operação SendMessages, o envio encontra-se em estado de

Para mais informações acerca dos caracteres e respectivas codificações, consultar

A operação retorna um objecto do tipo de dados ScheduleResult, com a seguinte

Propriedade Tipo Dimensão Descrição

Tabela 6 – Especificação do tipo de dados ScheduleResult

(c) Dependente da configuração de conta do cliente. Se a conta não contemplar controlo de

(d) O tipo do código de resultado da operação é um enumerado ScheduleStatus, com a

Nome Valor Descrição

Tabela 7 – Especificação do tipo de dados ScheduleStatus

(e) O tipo do estado resultante do envio é um enumerado EventLogImportStatus, com a

Nome Valor Descrição

Tabela 8 – Especificação do tipo de dados EventLogImportStatus

(f) O tipo de dados SmsScheduled é um tipo complexo com a seguinte especificação:

Propriedade Tipo Dimensão Descrição

Tabela 9 – Especificação do tipo de dados SmsScheduled

(g) A propriedade ScheduleMessageStatus é um enumerado com a seguinte especificação:

Nome Valor Descrição

Tabela 10 – Especificação do tipo de dados ScheduleMessageStatus

Operação que permite o agendamento de um envio para um contacto.

5.2.1. Assinatura da operação

A tabela seguinte apresenta a descrição dos parâmetros da operação.

prioritário) e 99 (mais prioritário)

Tabela 11 – Especificação dos parâmetros da operação SendMessage

Cada segmento equivale a uma mensagem única para efeitos de cobrança.

(c) Aquando da execução da operação SendMessage, o envio encontra-se em estado de

Para mais informações acerca dos caracteres e respectivas codificações, consultar

Propriedade Tipo Dimensão Descrição

Tabela 12 – Especificação do retorno da operação SendMessage

(c) Dependente da configuração de conta do cliente. Se a conta não contemplar controlo de

(d) O tipo do código de resultado da operação é um enumerado ScheduleStatus, com a

Nome Valor Descrição

Tabela 13 – Especificação do tipo de dados ScheduleStatus