manual webservice comunika
DESCRIPTION
Comunika WSDL Webservice ManualTRANSCRIPT
2
Man
ual W
ebse
rvic
eSU
MÁ
RIO Sumário
1. Webservice Comunika .............................................................................................3
2. Vantagens do Webservice Comunika ....................................................................3
3. Utilização do Webservice Comunika ......................................................................43.1 Autenticação Diferenciada ..................................................................................................4
3.2 O que é um Token? ..............................................................................................................4
3.3 Como utilizar o Token no Webservice Comunika ............................................................4
3.4 Importação das interfaces do Webservice Comunika ....................................................4
3.5 Tempo de Intervalo entre Requisições de Retorno de Status e MO’s no Webservice
Comunika ...................................................................................................................................4
4. Interfaces ..................................................................................................................54.1 Classe WSManager .............................................................................................................5
4.2 Classe WSSend ...................................................................................................................6
4.3 Classe WSReceive .............................................................................................................10
5. Classes (Objetos) ....................................................................................................145.1 CancelReturn .....................................................................................................................14
5.2 MessageResult ..................................................................................................................14
5.3 MessageReturn .................................................................................................................14
5.4 MOResult ............................................................................................................................14
5.5 ResponseCancelMessage ................................................................................................14
5.6 ResponseGeneric ..............................................................................................................15
5.7 ResponseGetCredit ............................................................................................................15
5.8 ResponseGetMessageStatus ...........................................................................................15
5.9 ResponseMessageCount ..................................................................................................15
5.10 ResponseMessageReceive .............................................................................................15
5.11 ResponseSendBatch .......................................................................................................16
5.12 ResponseSendMessage ..................................................................................................16
5.13 ResponseSendSeveral ....................................................................................................16
5.14 TargetResult .....................................................................................................................16
5.15 WSToken ...........................................................................................................................16
6. Testando o Webservice Comunika .......................................................................17
Apêndice A – Parâmetros .........................................................................................18
Apêndice B – Códigos de Erro ..................................................................................19
Apêndice C – Códigos de Status de Mensagens .....................................................20
Apêndice D – Tamanho de Mensagens ....................................................................20
Apêndice E – Resultados ...........................................................................................20
3
Man
ual W
ebse
rvic
eW
EBSE
RVI
CE C
OM
UN
IKA1. Webservice Comunika
O Webservice Comunika disponibiliza uma interface para envio, recebimento e gerenciamento de SMS ba-seados na tecnologia XML/SOAP. Essa interface possibilita grande agilidade na integração entre aplicações e a plataforma Comunika, com a segurança e confiabilidade de uma conexão criptografada.
2. Vantagens do Webservice Comunika
A tecnologia dos webservices provê um formato destinado a execução de métodos remotos via HTTPS, amplamente suportado pelas mais diversas plataformas e servidores de aplicação (.NET, JEE, etc.). Desta forma é possível que aplicações diferentes possam interagir com a plataforma Comunika, de forma simples e direta.
Principais vantagens do WebService Comunika:
• Permite às aplicações enviar e receber dados em formato XML. Cada aplicação pode ter a sua própria “linguagem”, que é traduzida para uma linguagem universal, o formato XML;
• Disponibiliza muito mais segurança no tráfego de mensagens via Internet, através de conexões seguras e publicação do serviço de forma simples e isoladas da base de dados;
• Permite uma integração de sistemas completamente simples, segura, reutilizável e padronizada. • Utiliza um fator de segurança adicional por meio de Token de autenticação, tornando o acesso mais
prático e rápido.
4
Man
ual W
ebse
rvic
eU
TILI
ZAÇÃ
O 3. Utilização do Webservice Comunika
3.1 Autenticação DiferenciadaO Webservice Comunika utiliza uma tecnologia que garante mais segurança na autenticação de usuários. Esta tecnologia é baseada na utilização de tokens de autenticação.
3.2 O que é um Token?O token de autenticação é uma string utilizada para autenticação de usuários no Webservice Comunika, que au-xilia o usuário quanto à segurança de sua utilização. Trata-se de uma senha temporária para acesso a aplicação, que elimina a necessidade do envio de usuário e senha nas chamadas aos métodos do WebService Comunika.
3.3 Como utilizar o Token no Webservice ComunikaPara criar o token de autenticação corretamente basta executar o método WSManager.getAutentication(String login, String senha).
Este método irá retornar um objeto do tipo WSToken que contém o Token, ou seja, a string de autenticação temporária, que deverá ser usada em cada requisição de métodos do webservice.
O token de autenticação tem validade de 5 minutos. Caso não seja feito nenhum acesso ao Webservice Comunika neste tempo, o token será expirado e haverá a necessidade de gerar um novo token através de nova chamada ao método WSManager.getAutentication(String login, String senha).
3.4 Importação das interfaces do Webservice ComunikaA utilização do Webservice Comunika para integração de sistemas e envio de mensagens, deve iniciar com a importação das interfaces disponíveis (contratos) no ambiente de desenvolvimento do cliente através das URLs abaixo.
• https://webservice.comunika.com.br/WSComunika/WSManager?wsdl• https://webservice.comunika.com.br/WSComunika/WSSend?wsdl• https://webservice.comunika.com.br/WSComunika/WSReceive?wsdl
Após a importação bem sucedida das interfaces, o ambiente de desenvolvimento utilizado deve gerar auto-maticamente uma série de classes e métodos que farão a comunição entre a aplicação cliente e a plataforma Comunika.
3.5 Tempo de Intervalo entre Requisições de Retorno de Status e MO’s no Webservice
Comunika
O tempo de Intervalo entre Requisições de Retorno de Status e MO’s através dos métodos do WebService Co-munika é de um minuto.
Caso esse tempo não seja respeitado a aplicação irá retornar o status 94 - TIME_OUT - Tempo mínimo entre requisições excedido.
5
Man
ual W
ebse
rvic
eIN
TER
FACE
S4. Interfaces
As interfaces disponíveis no Webservice Comunika são as seguintes:
Interface Descrição
WSManager Classe de gerenciamento de mensagens e de administração geral
WSSend Classe de envio de mensagens
WSReceive Classe de recebimento de mensagens
4.1 Classe WSManager
4.1.1 Método cancelScheduleMessageByBatchPossibilita cancelar as mensagens de um determinado lote.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
batchname String Identificador do lote a ser cancelado
Retorno ResponseCancelMessage
Exemplo de Requisição XML: <web:cancelScheduleMessageByBatch> <token>token</token> <batch>LoteNatal</batch> </web:cancelScheduleMessageByBatch>
Resultados: Results.ERROR Results.OK Results.OK_WITH_ERROR Results.IN_CANCEL
4.1.2 Método cancelScheduleMessageByPeriodPossibilita cancelar as mensagens por horário ou período.
Parâmetros Nome Tipo Descrição
Entrada Token String Token de autenticação
Begin String Início do período no formato
End String Fim do período
Retorno ResponseCancelMessage
Exemplo de Requisição: <web:cancelScheduleMessageByPeriod> <token>token</token> <begin>2010-12-01 00:00:00</begin> <end>2010-12-31 12:59:59</end> </web:cancelScheduleMessageByPeriod>
6
Man
ual W
ebse
rvic
eIN
TER
FACE
S Retornos: Results.ERROR Results.OK Results.OK_WITH_ERROR Results.IN_CANCEL
4.1.3 Método cancelScheduleMessageByIdsPossibilita cancelar as mensagens por ids.
Parâmetros Nome Tipo Descrição
Entrada Token String Token de autenticação
Ids String Identificadores de mensagens a serem canceladas
Retorno ResponseCancelMessage
Exemplo de Requisição:<web:cancelScheduleMessageByIds> <token>token</token> <ids>01,02,03</ids></web:cancelScheduleMessageByIds>
Resultados: Results.ERROR Results.OK Results.OK_WITH_ERROR Results.IN_CANCEL
4.1.4 Método getAuthenticationCria Token de autenticação de usuário.
Parâmetros Nome Tipo Descrição
Entrada Login String Login do usuário Comunika
Pass String Senha do usuário Comunika
Retorno WSToken
Exemplo de Requisição: <web:getAuthentication> <login>user_comunika</login> <pass>senhacomunika</pass> </web:getAuthentication>
Resultados: Results.OK Results.ERROR
4.2 Classe WSSend4.2.1 Método sendMessageEnvia uma única mensagem:
7
Man
ual W
ebse
rvic
eIN
TER
FACE
SParâmetros Nome Tipo Descrição
Entrada token string Token de autenticação
sender String Identificação de remetente
target String Destinatário
id String ID da mensagem do usuário
sched String Agendamento da Mensagem
periodFirst Int Início da janela de envio
periodLast Int Fim da janela de envio
expireTime String Expiração da mensagem
message String Mensagem
Retorno ResponseSendMessage
Exemplo de Requisição: <web:sendMessage> <token>token</token> <sender>WSTest</sender> <target>555185497589</target> <idMessage>IdWSTest</idMessage> <sched>2011-02-09 10:00:00</sched> <activePeriodFirst>8</activePeriodFirst> <activePeriodLast>22</activePeriodLast> <expireTime>5</expireTime> <message>Mensagem de teste WSTest</message> </web:sendMessage>
Resultados: Results.SCHED_ERROR Results.MSG_LENGTH_EXCEEDED Results.OUTOFCREDITS_USER Results.OK Results.CARRIER_NOT_FOUND Results.ERROR
4.2.2 Método sendBatchReplica uma mesma mensagem (com as mesmas configurações de agendamento, expiração, etc.) para vários destinatários:
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
sender String Identificação de remetente
targets TargetResult[] Destinatários
sched String Agendamento da Mensagem
periodFirst Int Início da janela de envio
periodLast Int Fim da janela de envio
expireTime String Expiração da mensagem
message String Mensagem
batchName String Nome do lote
Retorno ResponseSendBatch
8
Man
ual W
ebse
rvic
eIN
TER
FACE
S Exemplo de Requisição: <web:sendBatch> <token>token</token> <sender>WSTest</sender> <targets> <id>01</id> <target>555185497589</target> </targets> <targets> <id>02</id> <target>555185497590</target> </targets> <sched>2011-12-25 00:00:00</sched> <activePeriodFirst>8</activePeriodFirst> <activePeriodLast>22</activePeriodLast> <expireTime>2011-12-26 00:00:00</expireTime> <message>Feliz Natal</message> <batchName>LoteNatal</batchName> </web:sendBatch>
Resultados: Results.SCHED_ERROR Results.MSG_LENGTH_EXCEEDED Results.OUTOFCREDITS_USER Results.OK Results.OK_WITH_ERROR Results.CARRIER_NOT_FOUND Results.ERROR
4.2.3 Método sendSeveralMétodo que envia diversas mensagens completamente distintas (configurações de agendamento, expiração, etc.) para vários destinatáros.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
MessageResult Message Mensagem
Retorno ResponseSendSeveral
Exemplo de Requisição: <web:sendSeveral> <token>token</token> <messages> <id>1</id> <message>Mensagem de Teste 01</message> <sched>2011-02-09 10:00:00</sched> <sender>WSTest</sender> <target>555185497589</target> <periodFirst>8</periodFirst> <periodLast>22</periodLast> <expireTime>5</expireTime> </messages>
9
Man
ual W
ebse
rvic
eIN
TER
FACE
S <messages> <id>2</id> <message>Mensagem de Teste 02</message> <sched>2011-02-09 10:00:00</sched> <sender>WSTest</sender> <target>555185497590</target> <periodFirst>8</periodFirst> <periodLast>22</periodLast> <expireTime>5</expireTime> </messages> </web:sendSeveral>
Resultados: Results.SCHED_ERROR Results.MSG_LENGTH_EXCEEDED Results.OUTOFCREDITS_USER Results.OK Results.OK_WITH_ERROR Results.CARRIER_NOT_FOUND Results.ERROR
4.2.4 Método sendScheduleBatchMétodo que gera lotes com base na passagem de parâmetros para o inicio e fim do envio e o intervalo de tempo para cada lote que será gerado.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
sender String Mensagem
targets TargetResult[] Destinatários
startBatch String Data para inicio da geração do Lote
endBatch String Data para o fim da geração do Lote
sendInterval Int Intervalo em minutos para definir cada lote
periodFirst Int Início da janela de envio
periodLast Int Fim da janela de envio
expireTime String Expiração da mensagem
message String Mensagem
batchName String Nome do lote
Retorno ResponseSendBatch
Exemplo de Requisição XML:<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:web=”http:// webservice.comunika.com.br”> <soapenv:Header/> <soapenv:Body> <web:sendScheduleBatch> <token>sms</token> <sender>BW</sender> <targets> <id>Teste</id> <target>555195229608</target> </targets>
10
Man
ual W
ebse
rvic
eIN
TER
FACE
S <startBatch>2011-05-25 12:00:00</startBatch> <endBatch>2011-05-25 12:00:00</endBatch> <sendInterval>60</sendInterval> <activePeriodFirst>9</activePeriodFirst> <activePeriodLast>17</activePeriodLast> <expireTime>2011-05-26 12:00:00</expireTime> <message>Teste de Particionamento de Lotes</message> <batchName>Teste_Part_Lote</batchName> </web:sendScheduleBatch> </soapenv:Body></soapenv:Envelope>
Resultados: Results.SCHED_ERROR Results.MSG_LENGTH_EXCEEDED Results.OUTOFCREDITS_USER Results.OK Results.OK_WITH_ERROR Results.CARRIER_NOT_FOUND Results.ERROR
4.3 Classe WSReceive
4.3.1 Método getCreditVerifica os créditos restantes na conta do usuário.
Parâmetros Nome Tipo Descrição
Entrada Token String Token de autenticação
Retorno ResponseGetCredit
Exemplo de Requisição: <web:getCredit> <token>token</token> </web:getCredit>
Resultados: Results.OK Results.ERROR
4.3.2 Método getMessageStatusByBatchVerifica o status de entrega de mensagens enviadas previamente em um mesmo grupo.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
batch String Lote pelo qual mensagens foram enviadas
offSet Long Limite de registros retornados
Retorno ResponseGetMessageStatus
11
Man
ual W
ebse
rvic
eIN
TER
FACE
SExemplo de Requisição: <web:getMessageStatusByBatch> <token>token</token> <batch>LoteNatal</batch> <offSet>10</offSet> </web:getMessageStatusByBatch>
Resultados: Results.OK Results.ERROR Results.TIME_OUT
4.3.3 Método getMessageStatusByIdVerifica o status de entrega de mensagens enviadas previamente.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
ids String Ids de mensagens para buscaObs.: Para buscar o status de mais de um ID, informe todos os IDs desejados separados por vírgula.
Retorno ResponseGetMessageStatus
Exemplo de Requisição: <web:getMessageStatusById> <token>token</token> <ids>01,02</ids> </web:getMessageStatusById>
Resultados: Results.OK Results.ERROR Results.TIME_OUT
4.3.4 Método getMessageStatusByPeriodVerifica o status de entrega de mensagens enviadas previamente pela data de envio.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
begin String Data no formato yyyy-mm-dd hh:mm:ss
end String Data no formato yyyy-mm-dd hh:mm:ss
offSet Long Limite de registros retornados
Retorno ResponseGetMessageStatus
Exemplo de Requisição: <web:getMessageStatusByPeriod> <token>token</token> <begin>2010-12-24 00:00:00</begin> <end>2010-12-25 23:59:59</end> <offset>100</offset> </web:getMessageStatusByPeriod>
12
Man
ual W
ebse
rvic
eIN
TER
FACE
S Resultados: Results.OK Results.ERROR Results.TIME_OUT
4.3.5 Método messageReceiveO método messageReceive também retornará a propriedade “la” indicando o número do LA e operadora que originaram MO.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
limit Long Quantidade máxima de MO’s a serem retornados
Retorno ResponseGetMessageStatus
Exemplo de Requisição: <web:messageReceive> <token>sms</token> <limit>100</limit> </web:messageReceive>
Resultados: <return> <result>100</result> <resultDesc>1 MO’(s) Retornado(s)</resultDesc> <token>token</token> <mos> <sender>555199999999</sender> <msg>Teste OK</msg> <datetime>2011-08-29 15:13:28</datetime> <la>27400_Vivo</la> </mos> </return>
4.3.6 Método messageReceiveByDate O método messageReceiveByDate também retornará a propriedade “la” indicando o número do LA e operadora que originaram MO.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
begin String Início do Período
end String Fim do Período
limit Long Quantidade máxima de MO’s a serem retornados
Retorno ResponseGetMessageStatus
Exemplo de Requisição: <web:messageReceiveByDate> <token>sms</token> <begin>2011-08-29 15:20:00</begin> <end>2011-08-29 19:00:00</end> <limit>100</limit> </web:messageReceiveByDate>
13
Man
ual W
ebse
rvic
eIN
TER
FACE
SResultados: <return> <return> <result>100</result> <resultDesc>1 MO’(s) Retornado(s)</resultDesc> <token>sms</token> <mos> <sender>555195229608</sender> <msg>TESTE OK</msg> <datetime>2011-08-29 15:24:25</datetime> <la>27400_Vivo</la> </mos> </return>
4.3.7 Método messageReceiveCount Retorna a quantidade de MO’s recebidos que não lidos.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
Retorno ResponseMessageCount
Exemplo de Requisição: <web:messageReceiveCount> <token> token </token> </web:messageReceiveCount>
Resultados: Results.OK Results.ERROR
4.3.8 Método messageReceiveCountByDate Retorna quantidade de MO’s recebidos e não lidos no período informado.
Parâmetros Nome Tipo Descrição
Entrada token String Token de autenticação
begin String Início do Período
end String Fim do Período
Retorno ResponseMessageCount
Exemplo de Requisição: <web:messageReceiveCountByDate> <token>token</token> <begin>2010-12-24 00:00:00</begin> <end>2010-12-25 23:59:59</end> </web:messageReceiveCountByDate>
Resultados: Results.OK
Results.ERROR
14
Man
ual W
ebse
rvic
eCL
ASS
ES (O
BJE
TOS) 5. Classes (Objetos)
A aplicação Webservice Comunika utiliza as classes (objetos) abaixo para seu funcionamento. Abaixo as des-crevemos em maiores detalhes.
5.1 CancelReturnClasse utilizada para armazenar resultados de cancelamento de mensagens:
Propriedade Tipo Descrição
ID string Identificador da mensagem
result int Resultado de cancelamento da mensagem
5.2 MessageResultClasse que armazena os dados relativos a uma mensagem a ser enviada a um destinatário.
Propriedade Tipo Descrição
ID string Identificação do cliente Comunika
message string Conteúdo da mensagem
sched string Agendamento no formato yyyy-mm-dd HH:mm:ss
sender string Remetente
targed string Destinatário
periodFirst int Início da janela de envio
periodLast int Fim da janela de envio
expireTime string Expiração da mensagem, no formato yyyy-mm-dd HH:mm:ss ou quantidade de horas após postagem
5.3 MessageReturnClasse que armazena os resultados de envios de mensagem.
Propriedade Tipo Descrição
ID string Identificador da mensagem
result int Resultado do envio da mensagem
5.4 MOResultClasse que armazena o retorno de MO’s.
Propriedade Tipo Descrição
sender string Número que originou o MO
msg string Texto da mensagem
datetime string Data de recebimento da mensagem
la string Retorna LA e operadora que originou MO
5.5 ResponseCancelMessageClasse que armazena a resposta de um cancelamento de envio via WebService.
Propriedade Tipo Descrição
ArrayList<CancelReturn>msgs array Array de mensagens a serem canceladas
15
Man
ual W
ebse
rvic
eCL
ASS
ES (O
BJE
TOS)result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.6 ResponseGenericClasse que abriga parâmetros base para recebimento de retorno de método Webservice.
Propriedade Tipo Descrição
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.7 ResponseGetCreditClasse que armazena resposta de uma requisição de créditos.
Propriedade Tipo Descrição
credit float Quantidade de créditos
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.8 ResponseGetMessageStatusClasse que armazena resposta de uma requisição de quantidade de créditos.
Propriedade Tipo Descrição
ArrayList<SMSStatus> status array Array de status StatusPartResult
offset long Offset
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.9 ResponseMessageCountClasse que armazena a resposta de uma requisição WebService de quantidade de MO’s recebidos.
Propriedade Tipo Descrição
MOsCount long Quantidade de MO’s
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.10 ResponseMessageReceiveClasse que armazena os MO’s recebidos.
Propriedade Tipo Descrição
ArrayList<MOResult> mos array Array de MO’s.
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
16
Man
ual W
ebse
rvic
e5.11 ResponseSendBatchClasse que armazena resposta de um envio de Lote.
Propriedade Tipo Descrição
ArrayList<MessageReturn> messageReturn array Array de status de envio das mensagens.
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.12 ResponseSendMessageClasse que armazena resposta de um envio de Mensagem.
Propriedade Tipo Descrição
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.13 ResponseSendSeveralClasse que armazena resposta de um envio de diversas mensagens.
Propriedade Tipo Descrição
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
5.14 TargetResultClasse que armazena os dados de destinatário para envio de mensagens através do método SendBatch.
Propriedade Tipo Descrição
ID string Identificação do cliente Comunika
target string Número do destinatário da mensagem
5.15 WSTokenObjeto de resposta de uma autenticação Webservice.
Propriedade Tipo Descrição
lastupdate date Data da última atualização do Token
result int Resultado da operação
resultDesc string Descrição do resultado da operação
token string Token de autenticação Comunika
CLA
SSES
(OB
JETO
S)
17
Man
ual W
ebse
rvic
eTE
STA
ND
O6. Testando o Webservice Comunika
O Webservice Comunika disponibiliza uma classe para envio de testes da funcionalidade. O teste para simulação de envio de mensagens pode ser realizado utilizando-se a classe WSSendTest. O funcionamento desta classe é exatamente igual a da classe WSSend, descrito anteriormente.
É importante realizar o teste para verificar se os parâmetros, formato de datas, etc. estão sendo passados corretamente. A url para utilização da classe de testes é:
http://webservice.comunika.com.br/WSComunika/WSSendTest?wsdl
As características da utilização desta classe de teste são as seguintes:
• O Webservice Comunika realiza a operação normalmente, retornando o devido resultado de processamento da requisição;
• As mensagens não são enviadas, após o processamento e o retorno do método, elas são descartadas e nada fica registrado no Painel de Controle;
• Nenhum crédito é descontado.
18
Man
ual W
ebse
rvic
eA
PÊN
DIC
ES Apêndice A – Parâmetros
Nome Tipo Descrição
sender String Sender é o remetente da mensagem, informação que é adicionada no início da mensagem. Se por exemplo, tivermos uma mensagem: “Mensa-gem de Teste” e o usuário coloque como valor deste parâmetro “Cliente” o destinatário da mensagem receberá: “Cliente:Mensagem de Teste”. Caso o valor de sender seja nulo mensagem, a mensagem a ser enviada será apenas: “Mensagem de Teste”.
targets List<TargetResult> TargetResult é o objeto de destinatário da mensagem. Este objeto é formado por String id e String target.
id String Este id é um identificador interno do cliente e deve ser único para que seja possível identificar unicamente as mensagens. Caso seja repetido o identificador da mensagem, quando for feita uma consulta por aquele código, será retornado mais de um resultado, tornado a informação inválida para acompanhamento. O mais usual é que se utilize um valor incremental, gerado automaticamente pela base de dados do cliente.
target String Target é o destinatário do telefone. Deve ser informado DDI, DDD e o número de celular, como por exemplo: 555199000000.
sched String Este campo é utilizado para definir o agendamento de envio da mensa-gem e deve seguir o formato yyyy-mm-dd hh:mm:ss. Caso a mensagem deva ser enviada imediatamente o valor deste parâmetro deve ser nulo. Caso o agendamento enviado seja anterior à postagem, a mensagem será enviada imediatamente.
periodFirstperidoLast
Int Estes valores indicam respectivamente o início e o término da janela de envio. Eles permitem que o cliente determine limites de horário em que mensagem deve ser enviada. Um exemplo: O agendamento da mensagem deve estar dentro do período de janela de envio. Caso uma mensagem esteja agendada para as 7:00 com periodFirst=8, periodLast=11, ela nunca será enviada. A janela de envio deve ser sempre definida na chamada do mé-todo. Caso o cliente não queira utilizá-las, ou seja, enviar mensagem em qualquer período, ele deve enviar periodFirst=0 e periodLast=23, que indicarão que mensagem deve ser enviada entre as 0 horas e 23 horas do dia.
expireTime String Define um horário em que a mensagem deixa de ser válida. Esta de-finição é útil para casos onde a mensagem não deva ser enviada após determinado horário. Caso este horário seja atingido e a mensagem ainda não tenha sido enviada, ela é expirada e os respectivos créditos são estornados. Tal situação pode acontecer devido à instabilidades ou indisponibilidades das operadoras, que são situações onde o Comunika realiza várias tentativas de entrega até obter sucesso.Este parâmetro pode assumir três tipos de valores: -Data e hora no formato yyyy-mm-dd hh:mm:ss -Número inteiro de horas -Nulo caso a mensagem não deva conter regra de expiração O exemplo a seguir ilustra a relação entre os dois tipos de va-lores: Caso seja enviada uma mensagem às 2010-12-25 08:00:00 que deva ser enviada no máixmo até às 10:00, o cliente poderá definir sua expiração como ‘2010-12-25 10:00:00’ ou como 2.
19
Man
ual W
ebse
rvic
eA
PÊN
DIC
ES
message String Informa o conteúdo da mensagem. Existe um limite de caracteres para o texto da mensagem, que é de 150 caracteres, somando-se remetente e mensagem. Caso este limite seja ultrapassado, será retornado um erro.
batchName String Nome do lote o qual mensagens serão agrupadas, estes poderão ser utilizados posteriormente para relatórios, cancelamentos e administração de grupos de mensagens.
targets List<MessageResult> MessageResult é o objeto de destinatário de mensagens N pra N. Este objeto é formado por String expireTime, String id, String message, int periodFirst, int periodLast, String sched, String sender, String target
ids Int Ids são os códigos identificadores enviados pelo cliente Comunika no momento da postagem, este poderá ser usado na extração de relatórios no formato: Id1,Id2,Id3,...
begin end
String Define período de pesquisa em métodos, estes devem seguir o formato yyyy-mm-dd hh:mm:ss
loginpass
String Login e pass são utilizados para autenticação no ambiente comunika, estes devem ser utilizados para criação do token de acesso através do método WSManager.getAuthentication()
offset Long OffSet é um parâmetro para realização de busca de status/MOs, este fun-ciona como um limitador para consultas que retornem muitos registros. Para auxiliar integrações visando melhorar performance foi criado este parâmetro no qual uma consulta que contenha mais que 1000 registros possa ser dividida em diversas requisições. Exemplo: WSReceive.getMessageStatusByBatch(token,LoteNatal,0) tem 5100 MOs, estes se-rão divididos em 6 requisições enviando o offSet seguindo esta ordem 0,1000,2000,3000,4000,5000 retornando 1000,1000,1000,1000,1000,100 MOs. OffSet 0 retorna registros de 0 a 1000, Offset 1000 retorna re-gistros de 1001 a 2000 e assim sucessivamente.
limit Long Limit é o parâmetro utilizado para limitar quantos registros deverão ser retornados em uma determinada requisição. Exemplo: WSReceive.messageReceive(token,10) retorna no má-ximo 10 registros.
startBatch String Este campo é utilizado para definir a data de inicio da geração de lotese deve seguir o formato yyyy-mm-dd hh:mm:ss. Não aceita valor nulo.
endBatch String Este campo é utilizado para definir a data final da geração de lotes e deve seguir o formato yyyy-mm-dd hh:mm:ss. Não aceita valor nulo.
sendInterval Int Este campo é utilizado para definir o intervalo em minutos entre cada lote. Não aceita valor nulo.
la string Este parâmetro retorna o número do LA (Large Account) e o nome da operadora que enviou a mensagem. LA ou Short Code é o número curto, geralmente disposto em 5 caracteres, no qual usuário móvel pode interagir por SMS, enviando a mensagem para o respectivo número.Esse número é mantido pelas operadoras e alocado ao cliente.
Apêndice B – Códigos de Erro
Objeto de resposta de uma Requisição Webservice – Valores de Result.
20
Man
ual W
ebse
rvic
eOs códigos de erro retornados pelo sistema são os seguintes: 90 - Mensagem não Processada 91 – Erro genérico 92 – Erro de falha de autenticação 93 – Parâmetro(s) inválido(s) ou faltando 94 - Tempo mínimo entre requisições excedido 95 – Operadora não encontrada 96 – Usuário sem créditos 97 – Erro de Agendamento 98 – Quantidade de caracteres excedidos 99 – Cliente está cancelando uma mensagem 100 – Operação realizada com sucesso 101 - Operação realizada com sucesso porém com restrições
Apêndice C – Códigos de Status de Mensagens
Objeto de resposta de uma Requisição Webservice – Valores de Status de Mensagem.
Os códigos de status para mensagens postadas são: 3 – enviada para a operadora 5 – entregue ao aparelho celular 6 – rejeitada pela operadora 7 – expirada dentro da operadora (aparelho desligado ou fora de área por muito tempo) 8 – removida da operadora por algum motivo
Apêndice D – Tamanho de Mensagens
As mensagens para todas as operadoras devem ser consideradas como Remetente + Mensagem < 150 caracteres.
Apêndice E – ResultadosValores de resultados: 91 - int ERROR - Erro Genérico 92 - int AUTH_FAIL - Falha na Autenticação 93 - int INCORRECT_PARAMETERS - Parâmetros incorretos 94 - int TIME_OUT - Tempo minimo entre requisições excedido 95 - int CARRIER_NOT_FOUND - Operadora não encontrada 96 - int OUTOFCREDITS_USER - Usuário sem créditos 97 - int SCHED_ERROR - Constante para erro de agendamento 98 - int MSG_LENGTH_EXCEEDED - Constante para erro quantidade de caracteres excedidos 99 - int IN_CANCEL - Cliente esta cancelando uma mensagem 100 - int OK - Resultado OK 101 - int OK_WITH_ERROR - Resultado OK Com Restrições
AP
ÊND
ICES
21
Man
ual W
ebse
rvic
eW
EBSE
RVI
CE C
OM
UN
IKA