WebService – Envio de Mensagens
Documentação
Enviando mensagens através do Web Service Mótum
SOAP é um protocolo baseado em XML para troca de informações em ambientes
descentralizados. Por sua flexibilidade e farta documentação é uma forma
amplamente utilizada pelo mercado.
Nossa API SOAP é muito simples e direta, objetivando atender ao maior número
possível de diferentes aplicações clientes. Por exemplo, todos os campos são do tipo
"xsd:string". Veja o WSDL (Web Service Definition Language ) de cada servidor nos
endereços citados abaixo.
O propósito deste documento é esclarecer um pouco mais o uso do serviço.
Servidor de Produção:
URL do serviço
http://server.motum.com.br/services/msgs.php
URL do WSDL http://server.motum.com.br/services/msgs.php?wsdl
A mensagem é entregue ao celular e entra na
cobrança do mês corrente
Comportamento
Servidor de Homologação:
URL do serviço
http://teste.motum.com.br/services/msgs.php
URL do WSDL
http://teste.motum.com.br/services/msgs.php?wsdl
Comportamento
A mensagem é entregue à Mótum, o tratamento de
erro é exatamente como na produção, mas a
mensagem não é enviada ao celular e
consequentemente, não cobrada.
Revisão 1.0 de abril de 2011 - Este documento contém informação confidencial e/ou privilegiada. Você
não deverá reproduzir, copiar, alterar ou divulgar por qualquer meio a informação nela contida.
WebService – Envio de Mensagens
Documentação
Use o método EnviarMensagem usando os parâmetros abaixo. Todos os parâmetros
são simples strings.
Chamada à EnviarMensagem
Parâmetro Opcional Descrição
usuario
Não
Identificador informado pela Mótum
senha
Não
Senha fornecida pela Mótum
Telefone ou telefones dos destinatários da mensagem.
fones
Não
Todo telefone deve ter 10 posições (ex. “3199999999”) e caso se
queira enviar a mesma mensagem para mais de um número, eles
devem estar separados por vírgula
(ex.“3199999999,2199999999”).
Os números informados devem ser de celulares e se houver
algum número inválido (telefone fixo por exemplo), esse número
será descartado sem prejuízo para o envio da mensagem para os
demais números válidos. A Mótum não cobrará por números não
processados.
Texto da mensagem a ser enviada.
texto
Não
Esse texto deve ter no máximo 160 caracteres e já deve incluir a
assinatura da mensagem. Os caracteres válidos são
a-z A-Z0-9 !@#$%*():;”<>,./?
dataenvio
Sim
Data em que se deseja que a mensagem seja enviada. Se
informada, deve estar no formato YYYYMMDDhhmmss.
seunumero
Sim
Campo que identifica a mensagem no seu sistema
cc
Sim
Centro de custo.
Revisão 1.0 de abril de 2011 - Este documento contém informação confidencial e/ou privilegiada. Você
não deverá reproduzir, copiar, alterar ou divulgar por qualquer meio a informação nela contida.
WebService – Envio de Mensagens
Documentação
Retorno de EnviarMensagem
Parâmetro Tipo
Descrição
Código do retorno.
0 – Entrega do lote com sucesso. Significa que todos os números
foram aceitos e inseridos na base da Mótum para entrega às
respectivas operadoras. A entrega ocorrerá na data de envio
informada ou imediatamente se “dataenvio” tiver sido omitida na
chamada da função.
codretorno
Inteiro
2 – Entrega parcialmente bem sucedida. Significa que um ou mais
números da relação entregue não foram aceitos. Quando isso
acontece, o campo “fones” do retorno é preenchido com os telefones
válidos.
3 – Falha na entrega – Não foi encontrado nenhum telefone válido na
lista informada.
5 – Falha na entrega – A mensagem está vazia.
10 – Falha na entrega – Usuário, senha ou IP inválidos. Para
segurança de todos, ainda que a URL seja “aberta” ao público, o envio
das mensagens propriamente só é possível com a prévia inclusão do
IP de chegada em nossos servidores.
Este campo tem um descritivo que varia segundo o “codretorno”
acima:
codretorno
status
status
0
OK
2
PARCIAL
3
FALHA
5
SEM MSG
10
Usuario (XX), senha(YY) ou IP(ZZ) invalidos
Ocorrendo o erro 10, XX, YY e ZZ trarão textualmente qual usuário,
senha e IP, respectivamente, o sistema considerou na sua validação.
Certifique-se de que o usuário e senha estejam corretos e verifique se
o IP que está chegando à Mótum é o mesmo que nos foi informado.
Máquinas de teste e de produção costumam ter IPs de saída
diferentes. É possível informar tantos IPs quanto sejam necessários.
fones
Ocorrendo o erro 2, o sistema retorna aqui a relação de números que
foram considerados válidos e inseridos no sistema.
Revisão 1.0 de abril de 2011 - Este documento contém informação confidencial e/ou privilegiada. Você
não deverá reproduzir, copiar, alterar ou divulgar por qualquer meio a informação nela contida.
WebService – Envio de Mensagens
Documentação
A eficiência do sistema
Não há limite para a quantidade de números informados numa única requisição. No
entanto o modelo de entrega e recebimento por XML é relativamente caro em termos
de bytes e um erro por timeout é esperado dependendo da quantidade de celulares e
da velocidade da conexão entre sua máquina e a nossa. Nossa implementação do Web
Service não prevê chunks ou compactação.
Recomendamos portanto, que seja implementado uma séries de requisições com não
mais que 5.000 números a cada chamada.
Certifique-se de usar UTF-8 na codificação dos caracteres.
Exemplos de requisição
POST /services/msgs.php HTTP/1.0
Host: server.motum.com.br
User-Agent: NuSOAP/0.9.5 (1.123)
Content-Type: text/xml; charset=UTF-8
SOAPAction: ""
Content-Length: 790
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1595:EnviarMensagem xmlns:ns1595="http://tempuri.org">
<fones xsi:type="xsd:string">3184955560</fones>
<usuario xsi:type="xsd:string">motum</usuario>
<senha xsi:type="xsd:string">senha</senha>
<texto xsi:type="xsd:string">Mensagem qualquer</texto>
<dataenvio xsi:type="xsd:string">20150501121305</dataenvio>
<seunumero xsi:type="xsd:string">123</seunumero>
<cc xsi:type="xsd:string">LAB001</cc>
</ns1595:EnviarMensagem>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ATENÇÃO: esse XML exemplo foi formatado unicamente para uma melhor visualização
Revisão 1.0 de abril de 2011 - Este documento contém informação confidencial e/ou privilegiada. Você
não deverá reproduzir, copiar, alterar ou divulgar por qualquer meio a informação nela contida.
WebService – Envio de Mensagens
Documentação
Exemplo de resposta
HTTP/1.1 200 OK
Date: Tue, 26 Apr 2011 22:30:20 GMT
Server: Apache/2.2.8
X-Powered-By: PHP/5.2.6
X-SOAP-Server: NuSOAP/0.9.5 (1.123)
Content-Length: 555
Vary: Accept-Encoding
Connection: close
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<codretorno xsi:type="xsd:int">5</codretorno>
<status xsi:type="xsd:string">SEM MSG</status>
<fones xsi:type="xsd:string" />
<count xsi:type="xsd:int">0</count>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ATENÇÃO: esse XML exemplo foi formatado unicamente para uma melhor visualização
Ativação do serviço
Solicite a inclusão do IP ou IPs a serem utilizados pelo seu sistema através do e-mail
[email protected] ou [email protected].
Crie a sua aplicação cliente e aponte para o servidor de homologação até testar suas
funções de tratamento de envio e erro, só então mude para o servidor de produção.
Revisão 1.0 de abril de 2011 - Este documento contém informação confidencial e/ou privilegiada. Você
não deverá reproduzir, copiar, alterar ou divulgar por qualquer meio a informação nela contida.