SUMRIO

Sumrio
1. Webservice Comunika..............................................................................................3 2. Vantagens do Webservice Comunika.....................................................................3 3. Utilizao do Webservice Comunika.......................................................................4
3.1 Autenticao Diferenciada...................................................................................................4 3.2 O que um Token?...............................................................................................................4 3.3 Como utilizar o Token no Webservice Comunika.............................................................4 3.4 Importao das interfaces do Webservice Comunika.....................................................4 3.5 Tempo de Intervalo entre Requisies de Retorno de Status e MOs no Webservice . Comunika....................................................................................................................................4

4. Interfaces...................................................................................................................5
4.1 Classe WSManager..............................................................................................................5 4.2 Classe WSSend....................................................................................................................6 4.3 Classe WSReceive..............................................................................................................10

5. Classes (Objetos).....................................................................................................14
5.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

Manual Webservice
2

6. Testando o Webservice Comunika........................................................................17 Apndice A Parmetros..........................................................................................18 Apndice B Cdigos de Erro...................................................................................19 Apndice C Cdigos de Status de Mensagens......................................................20 Apndice D Tamanho de Mensagens.....................................................................20 Apndice E Resultados............................................................................................20

1. Webservice Comunika
O Webservice Comunika disponibiliza uma interface para envio, recebimento e gerenciamento de SMS baseados na tecnologia XML/SOAP. Essa interface possibilita grande agilidade na integrao entre aplicaes e a plataforma Comunika, com a segurana e confiabilidade de uma conexo criptografada.

2. Vantagens do Webservice Comunika

A tecnologia dos webservices prov um formato destinado a execuo de mtodos remotos via HTTPS, amplamente suportado pelas mais diversas plataformas e servidores de aplicao (.NET, JEE, etc.). Desta forma possvel que aplicaes diferentes possam interagir com a plataforma Comunika, de forma simples e direta. Principais vantagens do WebService Comunika: Permite s aplicaes enviar e receber dados em formato XML. Cada aplicao pode ter a sua prpria linguagem, que traduzida para uma linguagem universal, o formato XML; Disponibiliza muito mais segurana no trfego de mensagens via Internet, atravs de conexes seguras e publicao do servio de forma simples e isoladas da base de dados; Permite uma integrao de sistemas completamente simples, segura, reutilizvel e padronizada. Utiliza um fator de segurana adicional por meio de Token de autenticao, tornando o acesso mais prtico e rpido.

Manual Webservice
3

WEBSERVICE COMUNIKA

UTILIZAO Manual Webservice

4

3. Utilizao do Webservice Comunika

3.1 Autenticao Diferenciada
O Webservice Comunika utiliza uma tecnologia que garante mais segurana na autenticao de usurios. Esta tecnologia baseada na utilizao de tokens de autenticao.

3.2 O que um Token?

O token de autenticao uma string utilizada para autenticao de usurios no Webservice Comunika, que auxilia o usurio quanto segurana de sua utilizao. Trata-se de uma senha temporria para acesso a aplicao, que elimina a necessidade do envio de usurio e senha nas chamadas aos mtodos do WebService Comunika.

3.3 Como utilizar o Token no Webservice Comunika

Para criar o token de autenticao corretamente basta executar o mtodo WSManager.getAutentication(String login, String senha). Este mtodo ir retornar um objeto do tipo WSToken que contm o Token, ou seja, a string de autenticao temporria, que dever ser usada em cada requisio de mtodos do webservice. O token de autenticao tem validade de 5 minutos. Caso no seja feito nenhum acesso ao Webservice Comunika neste tempo, o token ser expirado e haver a necessidade de gerar um novo token atravs de nova chamada ao mtodo WSManager.getAutentication(String login, String senha).

3.4 Importao das interfaces do Webservice Comunika

A utilizao do Webservice Comunika para integrao de sistemas e envio de mensagens, deve iniciar com a importao das interfaces disponveis (contratos) no ambiente de desenvolvimento do cliente atravs 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

Aps a importao bem sucedida das interfaces, o ambiente de desenvolvimento utilizado deve gerar automaticamente uma srie de classes e mtodos que faro a comunio entre a aplicao cliente e a plataforma Comunika.

3.5 Tempo de Intervalo entre Requisies de Retorno de Status e MOs no Webservice Comunika
O tempo de Intervalo entre Requisies de Retorno de Status e MOs atravs dos mtodos do WebService Comunika de um minuto. Caso esse tempo no seja respeitado a aplicao ir retornar o status 94 - TIME_OUT - Tempo mnimo entre requisies excedido.

4. Interfaces
As interfaces disponveis no Webservice Comunika so as seguintes: Interface WSManager WSSend WSReceive Descrio Classe de gerenciamento de mensagens e de administrao geral Classe de envio de mensagens Classe de recebimento de mensagens

4.1 Classe WSManager

4.1.1 Mtodo cancelScheduleMessageByBatch
Possibilita cancelar as mensagens de um determinado lote. Parmetros Entrada Retorno Exemplo de Requisio XML: Nome token batchname Tipo String String ResponseCancelMessage Descrio Token de autenticao Identificador do lote a ser cancelado

<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 Mtodo cancelScheduleMessageByPeriod

Possibilita cancelar as mensagens por horrio ou perodo. Parmetros Entrada Nome Token Begin End Retorno Exemplo de Requisio: Tipo String String String ResponseCancelMessage Descrio Token de autenticao Incio do perodo no formato Fim do perodo

<web:cancelScheduleMessageByPeriod> <token>token</token> <begin>2010-12-01 00:00:00</begin> <end>2010-12-31 12:59:59</end> </web:cancelScheduleMessageByPeriod>

Manual Webservice
5

INTERFACES

INTERFACES

Retornos:

Results.ERROR Results.OK Results.OK_WITH_ERROR Results.IN_CANCEL

4.1.3 Mtodo cancelScheduleMessageByIds

Possibilita cancelar as mensagens por ids. Parmetros Entrada Retorno Exemplo de Requisio: Nome Token Ids Tipo String String ResponseCancelMessage Descrio Token de autenticao Identificadores de mensagens a serem canceladas

<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 Mtodo getAuthentication

Cria Token de autenticao de usurio. Parmetros Entrada Retorno Nome Login Pass Tipo String String WSToken Descrio Login do usurio Comunika Senha do usurio Comunika

Manual Webservice

Exemplo de Requisio:

<web:getAuthentication> <login>user_comunika</login> <pass>senhacomunika</pass> </web:getAuthentication>

Resultados:

Results.OK Results.ERROR

4.2 Classe WSSend

4.2.1 Mtodo sendMessage
Envia uma nica mensagem:

Parmetros Entrada

Nome token sender target id sched periodFirst periodLast expireTime message

Tipo string String String String String Int Int String String ResponseSendMessage

Descrio Token de autenticao Identificao de remetente Destinatrio ID da mensagem do usurio Agendamento da Mensagem Incio da janela de envio Fim da janela de envio Expirao da mensagem Mensagem

Retorno Exemplo de Requisio:

<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 Mtodo sendBatch

Replica uma mesma mensagem (com as mesmas configuraes de agendamento, expirao, etc.) para vrios destinatrios: Parmetros Entrada Nome token sender targets sched periodFirst periodLast expireTime message Retorno Tipo String String TargetResult[] String Int Int String String ResponseSendBatch Descrio Token de autenticao Identificao de remetente Destinatrios Agendamento da Mensagem Incio da janela de envio Fim da janela de envio Expirao da mensagem Mensagem Nome do lote

batchName String

Manual Webservice
7

INTERFACES

INTERFACES

Exemplo de Requisio: <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 Mtodo sendSeveral

Mtodo que envia diversas mensagens completamente distintas (configuraes de agendamento, expirao, etc.) para vrios destinatros. Parmetros Nome token Tipo String ResponseSendSeveral Descrio Token de autenticao Mensagem

Manual Webservice

Entrada Retorno

MessageResult Message

Exemplo de Requisio:

<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>

 <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 Mtodo sendScheduleBatch

Mtodo que gera lotes com base na passagem de parmetros para o inicio e fim do envio e o intervalo de tempo para cada lote que ser gerado. Parmetros Entrada Nome token sender targets startBatch endBatch sendInterval periodFirst periodLast expireTime message batchName Retorno Exemplo de Requisio XML: Tipo String String TargetResult[] String String Int Int Int String String String ResponseSendBatch Descrio Token de autenticao Mensagem Destinatrios Data para inicio da gerao do Lote Data para o fim da gerao do Lote Intervalo em minutos para definir cada lote Incio da janela de envio Fim da janela de envio Mensagem Nome do lote

<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>

Manual Webservice
9

Expirao da mensagem

INTERFACES

 <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:

INTERFACES

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 Mtodo getCredit
Verifica os crditos restantes na conta do usurio. Parmetros Entrada Retorno Exemplo de Requisio: Nome Token Tipo String ResponseGetCredit Descrio Token de autenticao

Manual Webservice

<web:getCredit> <token>token</token> </web:getCredit>

Resultados:

Results.OK Results.ERROR

4.3.2 Mtodo getMessageStatusByBatch

Verifica o status de entrega de mensagens enviadas previamente em um mesmo grupo. Parmetros Entrada Nome token batch offSet Retorno Tipo String String Long ResponseGetMessageStatus Descrio Token de autenticao Lote pelo qual mensagens foram enviadas Limite de registros retornados

10

 <web:getMessageStatusByBatch> <token>token</token> <batch>LoteNatal</batch> <offSet>10</offSet> </web:getMessageStatusByBatch>

Resultados: Results.OK

Results.ERROR Results.TIME_OUT

4.3.3 Mtodo getMessageStatusById

Verifica o status de entrega de mensagens enviadas previamente. Parmetros Entrada Nome token ids Tipo String String Descrio Token de autenticao Ids de mensagens para busca Obs.: Para buscar o status de mais de um ID, informe todos os IDs desejados separados por vrgula.

Retorno

ResponseGetMessageStatus

Exemplo de Requisio: <web:getMessageStatusById>

<token>token</token> <ids>01,02</ids> </web:getMessageStatusById>

Resultados: Results.OK

Results.ERROR Results.TIME_OUT

Verifica o status de entrega de mensagens enviadas previamente pela data de envio. Parmetros Entrada Nome token begin end offSet Retorno Tipo String String String Long ResponseGetMessageStatus Descrio Token de autenticao Data no formato yyyy-mm-dd hh:mm:ss Data no formato yyyy-mm-dd hh:mm:ss Limite de registros retornados

Exemplo de Requisio: <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>

11

Manual Webservice

4.3.4 Mtodo getMessageStatusByPeriod

INTERFACES

Exemplo de Requisio:

INTERFACES

Resultados: Results.OK Results.ERROR Results.TIME_OUT

4.3.5 Mtodo messageReceive

O mtodo messageReceive tambm retornar a propriedade la indicando o nmero do LA e operadora que originaram MO. Parmetros Entrada Retorno Exemplo de Requisio: Nome token limit Tipo String Long ResponseGetMessageStatus Descrio Token de autenticao Quantidade mxima de MOs a serem retornados

<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 Mtodo messageReceiveByDate

Manual Webservice

O mtodo messageReceiveByDate tambm retornar a propriedade la indicando o nmero do LA e operadora que originaram MO. Parmetros Entrada Nome token begin end limit Retorno Exemplo de Requisio: Tipo String String String Long ResponseGetMessageStatus Descrio Token de autenticao Incio do Perodo Fim do Perodo Quantidade mxima de MOs a serem retornados

12

<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>

<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 Mtodo messageReceiveCount

Retorna a quantidade de MOs recebidos que no lidos. Parmetros Entrada Retorno Exemplo de Requisio: Nome token Tipo String ResponseMessageCount Descrio Token de autenticao

<web:messageReceiveCount> <token> token </token> </web:messageReceiveCount>

Resultados:

Results.OK Results.ERROR

4.3.8 Mtodo messageReceiveCountByDate

Retorna quantidade de MOs recebidos e no lidos no perodo informado. Parmetros Entrada Nome token begin end Retorno Exemplo de Requisio: Tipo String String String ResponseMessageCount Descrio Incio do Perodo Fim do Perodo

<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

13

Manual Webservice

Token de autenticao

INTERFACES

Resultados:

CLASSES (OBJETOS)

5. Classes (Objetos)
A aplicao Webservice Comunika utiliza as classes (objetos) abaixo para seu funcionamento. Abaixo as descrevemos em maiores detalhes.

5.1 CancelReturn
Classe utilizada para armazenar resultados de cancelamento de mensagens: Propriedade ID result Tipo string int Descrio Identificador da mensagem Resultado de cancelamento da mensagem

5.2 MessageResult
Classe que armazena os dados relativos a uma mensagem a ser enviada a um destinatrio. Propriedade ID message sched sender targed periodFirst periodLast expireTime Tipo string string string string string int int string Descrio Identificao do cliente Comunika Contedo da mensagem Agendamento no formato yyyy-mm-dd HH:mm:ss Remetente Destinatrio Incio da janela de envio Fim da janela de envio Expirao da mensagem, no formato yyyy-mm-dd HH:mm:ss ou quantidade de horas aps postagem

5.3 MessageReturn
Classe que armazena os resultados de envios de mensagem. Propriedade ID result Tipo string int Descrio Identificador da mensagem Resultado do envio da mensagem

Manual Webservice

5.4 MOResult
Classe que armazena o retorno de MOs. Propriedade sender msg datetime la Tipo string string string string Descrio Nmero que originou o MO Texto da mensagem Data de recebimento da mensagem Retorna LA e operadora que originou MO

5.5 ResponseCancelMessage
Classe que armazena a resposta de um cancelamento de envio via WebService. Propriedade Tipo Descrio Array de mensagens a serem canceladas

14

ArrayList<CancelReturn>msgs array

result resultDesc token

int string string

Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.6 ResponseGeneric
Classe que abriga parmetros base para recebimento de retorno de mtodo Webservice. Propriedade result resultDesc token Tipo int string string Descrio Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.7 ResponseGetCredit
Classe que armazena resposta de uma requisio de crditos. Propriedade credit result resultDesc token Tipo float int string string Descrio Quantidade de crditos Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.8 ResponseGetMessageStatus
Classe que armazena resposta de uma requisio de quantidade de crditos. Propriedade offset result resultDesc token Tipo long int string string Descrio Array de status StatusPartResult Offset Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

ArrayList<SMSStatus> status array

5.9 ResponseMessageCount
Propriedade MOsCount result resultDesc token Tipo long int string string Descrio Quantidade de MOs Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.10 ResponseMessageReceive
Classe que armazena os MOs recebidos. Propriedade ArrayList<MOResult> mos result resultDesc token Tipo array int string string Descrio Array de MOs. Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

15

Manual Webservice

Classe que armazena a resposta de uma requisio WebService de quantidade de MOs recebidos.

CLASSES (OBJETOS)

CLASSES (OBJETOS)

5.11 ResponseSendBatch
Classe que armazena resposta de um envio de Lote. Propriedade result resultDesc token Tipo int string string Descrio Array de status de envio das mensagens. Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

ArrayList<MessageReturn> messageReturn array

5.12 ResponseSendMessage
Classe que armazena resposta de um envio de Mensagem. Propriedade result resultDesc token Tipo int string string Descrio Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.13 ResponseSendSeveral
Classe que armazena resposta de um envio de diversas mensagens. Propriedade result resultDesc token Tipo int string string Descrio Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

5.14 TargetResult
Classe que armazena os dados de destinatrio para envio de mensagens atravs do mtodo SendBatch. Propriedade ID target Tipo string string Descrio Identificao do cliente Comunika Nmero do destinatrio da mensagem

Manual Webservice

5.15 WSToken
Objeto de resposta de uma autenticao Webservice. Propriedade lastupdate result resultDesc token Tipo date int string string Descrio Data da ltima atualizao do Token Resultado da operao Descrio do resultado da operao Token de autenticao Comunika

16

6. Testando o Webservice Comunika

O Webservice Comunika disponibiliza uma classe para envio de testes da funcionalidade. O teste para simulao 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 parmetros, formato de datas, etc. esto sendo passados corretamente. A url para utilizao da classe de testes :

http://webservice.comunika.com.br/WSComunika/WSSendTest?wsdl

As caractersticas da utilizao desta classe de teste so as seguintes: O Webservice Comunika realiza a operao normalmente, retornando o devido resultado de processamento da requisio; As mensagens no so enviadas, aps o processamento e o retorno do mtodo, elas so descartadas e nada fica registrado no Painel de Controle; Nenhum crdito descontado.

17

Manual Webservice

TESTANDO

APNDICES

Apndice A Parmetros
Nome sender Tipo String Descrio Sender o remetente da mensagem, informao que adicionada no incio da mensagem. Se por exemplo, tivermos uma mensagem: Mensagem de Teste e o usurio coloque como valor deste parmetro Cliente o destinatrio 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. TargetResult o objeto de destinatrio da mensagem. Este objeto formado por String id e String target. Este id um identificador interno do cliente e deve ser nico para que seja possvel identificar unicamente as mensagens. Caso seja repetido o identificador da mensagem, quando for feita uma consulta por aquele cdigo, ser retornado mais de um resultado, tornado a informao invlida para acompanhamento. O mais usual que se utilize um valor incremental, gerado automaticamente pela base de dados do cliente. Target o destinatrio do telefone. Deve ser informado DDI, DDD e o nmero de celular, como por exemplo: 555199000000. Este campo utilizado para definir o agendamento de envio da mensagem e deve seguir o formato yyyy-mm-dd hh:mm:ss. Caso a mensagem deva ser enviada imediatamente o valor deste parmetro deve ser nulo. Caso o agendamento enviado seja anterior postagem, a mensagem ser enviada imediatamente. Estes valores indicam respectivamente o incio e o trmino da janela de envio. Eles permitem que o cliente determine limites de horrio em que mensagem deve ser enviada. Um exemplo: O agendamento da mensagem deve estar dentro do perodo 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 mtodo. Caso o cliente no queira utiliz-las, ou seja, enviar mensagem em qualquer perodo, ele deve enviar periodFirst=0 e periodLast=23, que indicaro que mensagem deve ser enviada entre as 0 horas e 23 horas do dia. Define um horrio em que a mensagem deixa de ser vlida. Esta definio til para casos onde a mensagem no deva ser enviada aps determinado horrio. Caso este horrio seja atingido e a mensagem ainda no tenha sido enviada, ela expirada e os respectivos crditos so estornados. Tal situao pode acontecer devido instabilidades ou indisponibilidades das operadoras, que so situaes onde o Comunika realiza vrias tentativas de entrega at obter sucesso. Este parmetro pode assumir trs tipos de valores: -Data e hora no formato yyyy-mm-dd hh:mm:ss -Nmero inteiro de horas -Nulo caso a mensagem no deva conter regra de expirao O exemplo a seguir ilustra a relao entre os dois tipos de valores: Caso seja enviada uma mensagem s 2010-12-25 08:00:00 que deva ser enviada no mixmo at s 10:00, o cliente poder definir sua expirao como 2010-12-25 10:00:00 ou como 2.

targets id

List<TargetResult> String

target sched

String String

periodFirst peridoLast

Int

Manual Webservice

expireTime

String

18

message

String

Informa o contedo 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. Nome do lote o qual mensagens sero agrupadas, estes podero ser utilizados posteriormente para relatrios, cancelamentos e administrao de grupos de mensagens.

batchName

String

targets

List<MessageResult> MessageResult o objeto de destinatrio 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 Int Ids so os cdigos identificadores enviados pelo cliente Comunika no momento da postagem, este poder ser usado na extrao de relatrios no formato: Id1,Id2,Id3,... Define perodo de pesquisa em mtodos, estes devem seguir o formato yyyy-mm-dd hh:mm:ss Login e pass so utilizados para autenticao no ambiente comunika, estes devem ser utilizados para criao do token de acesso atravs do mtodo WSManager.getAuthentication() OffSet um parmetro para realizao de busca de status/MOs, este funciona como um limitador para consultas que retornem muitos registros. Para auxiliar integraes visando melhorar performance foi criado este parmetro no qual uma consulta que contenha mais que 1000 registros possa ser dividida em diversas requisies. Exemplo: WSReceive.get MessageStatusByBatch(token,LoteNatal,0) tem 5100 MOs, estes sero divididos em 6 requisies 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 registros de 1001 a 2000 e assim sucessivamente.

ids

begin end login pass offset

String String

Long

limit

Long

Limit o parmetro utilizado para limitar quantos registros devero ser retornados em uma determinada requisio. Exemplo: WSReceive.messageReceive(token,10) retorna no mximo 10 registros. Este campo utilizado para definir a data de inicio da gerao de lotes e deve seguir o formato yyyy-mm-dd hh:mm:ss. No aceita valor nulo.

startBatch endBatch sendInterval la

String String Int string

Este campo utilizado para definir o intervalo em minutos entre cada lote. No aceita valor nulo. Este parmetro retorna o nmero do LA (Large Account) e o nome da operadora que enviou a mensagem. LA ou Short Code o nmero curto, geralmente disposto em 5 caracteres, no qual usurio mvel pode interagir por SMS, enviando a mensagem para o respectivo nmero.Esse nmero mantido pelas operadoras e alocado ao cliente.

Apndice B Cdigos de Erro

Objeto de resposta de uma Requisio Webservice Valores de Result.

19

Manual Webservice

Este campo utilizado para definir a data final da gerao de lotes e deve seguir o formato yyyy-mm-dd hh:mm:ss. No aceita valor nulo.

APNDICES

Os cdigos de erro retornados pelo sistema so os seguintes: 90 - Mensagem no Processada 91 Erro genrico 92 Erro de falha de autenticao 93 Parmetro(s) invlido(s) ou faltando 94 - Tempo mnimo entre requisies excedido 95 Operadora no encontrada 96 Usurio sem crditos 97 Erro de Agendamento 98 Quantidade de caracteres excedidos 99 Cliente est cancelando uma mensagem 100 Operao realizada com sucesso 101 - Operao realizada com sucesso porm com restries

APNDICES Manual Webservice

20

Apndice C Cdigos de Status de Mensagens

Objeto de resposta de uma Requisio Webservice Valores de Status de Mensagem. Os cdigos de status para mensagens postadas so: 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

Apndice D Tamanho de Mensagens

As mensagens para todas as operadoras devem ser consideradas como Remetente + Mensagem < 150 caracteres.

Apndice E Resultados
Valores de resultados: 91 - int ERROR - Erro Genrico 92 - int AUTH_FAIL - Falha na Autenticao 93 - int INCORRECT_PARAMETERS - Parmetros incorretos 94 - int TIME_OUT - Tempo minimo entre requisies excedido 95 - int CARRIER_NOT_FOUND - Operadora no encontrada 96 - int OUTOFCREDITS_USER - Usurio sem crditos 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 Restries

21

Manual Webservice

WEBSERVICE COMUNIKA