Como enviar SMS por WebServices

O que é Flash SMS?

O Flash SMS é um produto da Facilita Móvel muito utilizado por operadoras de telefonia, para informar coisas importantes como saldo e algumas promoções. Com o Flash SMS a pessoa não precisa ir até a caixa de SMS para ler o conteúdo do SMS, ele pisca na tela do usuário como se fosse uma mensagem vinda de uma operadora.
Observe a imagem abaixo:

Seja cauteloso

Diferente do SMS convencional, o Flash SMS é exibido de diferentes formas no celular do destinatário, cada modelo de celular exibe da forma como foi projetado. Não compete a Facilita decidir como será exibido na tela do usuário. Alguns celulares possuem o botão aceitar, outros Salvar, é opção do fabricante do celular decidir.
O Flash SMS por padrão não fica salvo no aparelho do destinatário, alguns modelos possuem o botão "salvar", que envia para caixa de SMS Convencional, mas não necessariamente todos terão este botão, ou salvarão seus SMS.
Teste bem antes de fazer uma campanha envolvendo Flash SMS, você é o único responsável por seus envios. (leia mais em nosso blog)

Diferentes tipos de envio

Para uma integração eficiente com os nossos clientes, disponibilizamos diferentes tipos de envio. O WebServices da Facilita está em constante evolução, portanto novos tipos poderão ser acrescentados, dependendo do interesse mútuo das empresas.

Envio Simples

O envio simples é o envio mais comum e mais utilizado de nossa plataforma, ele consiste em enviar uma única mensagem para um único destinatário.

Função: sendSimpleMessage

URL desta função:

						http://www.facilitamovel.com.br/SendMessage
					
					

Parâmetros usados nesta requisição

Leia em nosso blog sobre o FlashSMS.

Exemplo do XML da requisição:

					
					<?xml version="1.0" encoding="utf-8"?> 
					<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
						<soap:Body> 
							<sendSimpleMessage  xmlns="http://ws.action.fadmin.com.br/"> 
								<user xmlns="">xptouser</user> 
								<password xmlns="">xxpadw</password> 
								<externalkey xmlns="">2345</externalkey> 
								<message xmlns="">Mensagem teste</message> 
								<phone xmlns="">5199950448</phone> 
							</sendSimpleMessage> 
						</soap:Body> 
					</soap:Envelope>
					
					

Códigos de retorno da integração

SMS_ID é um Id único que a plataforma devolve para o usuário. A função de se ter um Id único devolvido na requisição, é para o armazenamento no sistema do usuário para posteriormente consultar o status da Mensagem (Ver “Consultar Status da Mensagem”)

Exemplo de um XML de retorno caso a mensagem seja aceita pela Facilita:

					
					<?xml version="1.0" encoding="UTF-8"?> 
					<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> 
						<S:Body> 
							<ns2:sendMultipleMessageResponse xmlns:ns2="http://ws.action.fadmin.com.br/"> 
								<return> 
									<code>7</code> 
									<externalKey>124</externalKey> 
									<msg>Accepted Message</msg> 
									<smsId>228009965</smsId> 
								</return> 
							</ns2:sendMultipleMessageResponse> 
						</S:Body> 
					</S:Envelope>
					
					

Envio Múltiplo

Envio destinado para enviar a vários SMS para vários números diferentes.

Função: sendMultipleMessage

URL desta função:

						http://api.facilitamovel.com.br/SendMessage
					
					

Parâmetros usados nesta requisição

Leia em nosso blog sobre o FlashSMS.

Atenção: Na tabela acima temos a observação "lista contendo", pois como você poderá enviar vários SMS para vários números na mesma requisição, os parâmetros phone, message e externalkey serão enviados em forma de lista, como no XML abaixo.

Exemplo do XML da requisição:

					
					<?xml version="1.0" encoding="utf-8"?> 
						<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
							<soap:Body> 
								<sendMultipleMessage xmlns="http://ws.action.fadmin.com.br/"> 
									<user xmlns="">xxptouser</user> 
									<password xmlns="">xptopwd</password> 
									<multiples xmlns=""> 
										<externalKey>123</externalKey> 
										<message>teste 1</message> 
										<phone>51999650441</phone> 
										<externalKey>124</externalKey>
										<message>teste 2</message> 
										<phone>51999450889</phone> 
									</multiples> 
									<multiples xmlns=""> 
										<externalKey>124</externalKey>
										<message>teste 2</message> 
										<phone>51999450889</phone> 
									</multiples> 
								</sendMultipleMessage> 
							</soap:Body> 
						</soap:Envelope>
					
					

Códigos de retorno da integração

SMS_ID é um Id único que a plataforma devolve para o usuário. A função de se ter um Id único devolvido na requisição, é para o armazenamento no sistema do usuário para posteriormente consultar o status da Mensagem (Ver “Consultar Status da Mensagem”)

Exemplo de um XML de retorno caso a mensagem seja aceita pela Facilita:

					
					<S:Envelope> 
						<S:Body> 
							<ns2:sendSimpleMessageResponse> 
								<return> 
								<code>5</code> 
								<msg>Accepted Message</msg> 
								<smsId>227969381</smsId> 
								</return> 
							</ns2:sendSimpleMessageResponse> 
						</S:Body> 
					</S:Envelope>
					
					

Envio Multiplo com Agendamento e FlashSMS

Envio destinado para enviar a vários SMS para vários números diferentes, com a opção agora adicionada de poder fazer agendamentos e enviar FlashSMS.

Função: sendMultipleMessageScheduled

URL desta função:

						http://api.facilitamovel.com.br/SendMessage
					
					

Parâmetros usados nesta requisição

Atenção: Na tabela acima temos a observação "lista contendo", pois como você poderá enviar vários SMS para vários números na mesma requisição, os parâmetros phone, message e externalkey serão enviados em forma de lista, como no XML abaixo.

Atenção 2: Os parâmetros day, month, year, formHour e formMinute são opcionais, você não precisa passar todos estes parâmetros para agendar uma mensagem, caso você queira um dia específico deste mês, passe apenas o day, que os outros parâmetros ele vai entender que são do mês, ano, hora e minuto atual.

Exemplo do XML da requisição:

					
						<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
							<soap:Body> 
								<sendMultipleMessageScheduled xmlns="http://ws.action.fadmin.com.br/"> 
									<user xmlns="">userxpto</user> 
									<password xmlns="">senhaxpto</password> 
									<day xmlns="">23</day> 
									<month xmlns="">05</month> 
									<year xmlns="">2020</year> 
									<formHour xmlns="">10</formHour> 
									<formMinute xmlns="">12</formMinute> 
									<flashsms xmlns="">1</flashsms> 
									<multiples xmlns=""> 
									<externalKey>123</externalKey> 
									<message>teste menagem</message> 
									<phone>51999460559</phone> 
									</multiples> 
								</sendMultipleMessageScheduled> 
							</soap:Body> 
						</soap:Envelope>
					
					

Códigos de retorno da integração

SMS_ID é um Id único que a plataforma devolve para o usuário. Guarde este ID único que devolvemos para para posteriormente consultar o status da Mensagem (Ver “Consultar Status da Mensagem”)

Exemplo de um XML de retorno caso a mensagem seja aceita pela Facilita:

					
						<?xml version="1.0" encoding="UTF-8"?> 
						<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
							<S:Body> 
								<ns2:sendMultipleMessageScheduledResponse xmlns:ns2="http://ws.action.fadmin.com.br/"> 
									<return> 
									<code>7</code> 
									<externalKey>123</externalKey> 
									<msg>Accepted Message</msg> 
									<smsId>228051254</smsId> 
									</return> 
								</ns2:sendMultipleMessageScheduledResponse> 
							</S:Body> 
						</S:Envelope>
					
					

Consultar Status da Mensagem

Quando um SMS é enviado, o sistema retorna o SMSID, que é nossa chave primária em nossa tabela de SMS, esse SMSID poderá ser usado neste método para obter o status do SMS.

Função: dlrStatus

URL desta função:

						http://api.facilitamovel.com.br/SendMessage
					
					

Parâmetros usados nesta requisição

Exemplo do XML da requisição:

					
						<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
							<soap:Body> 
								<dlrStatus xmlns="http://ws.action.fadmin.com.br/"> 
									<user xmlns="">userxpto</user> 
									<password xmlns="">userxpto</password> 
									<smsId xmlns="">228051254</smsId> 
									</dlrStatus> 
								</soap:Body> 
							</soap:Envelope>
					
					

Códigos de retorno da integração

Exemplo de um XML de retorno de uma mensagem com o status agendada, status com código 2:

					
						<?xml version="1.0" encoding="UTF-8"?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> 
							<S:Body> 
								<ns2:dlrStatusResponse xmlns:ns2="http://ws.action.fadmin.com.br/"> 
									<return> 
										<code>2</code> 
										<msg> 
										</msg> 
									</return> 
								</ns2:dlrStatusResponse> 
							</S:Body> 
						</S:Envelope>
					
					

Consultar Mensagens Respondidas

Quando um celular responde para algum SMS que você enviou, essas respostas ficam todas em nossa plataforma, você poderá ler elas entrando em nosso painel, ou consultando via integração.

Função: readMO

URL desta função:

						http://api.facilitamovel.com.br/ReceiveMessage?wsdl
					
					

Parâmetros usados nesta requisição

Exemplo do XML da requisição:

					
							<?xml version="1.0" encoding="utf-8"?> 
								<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
									<soap:Body> 
										<readMO xmlns="http://ws.action.fadmin.com.br/"> 
											<user xmlns="">usuarioxpto</user> 
											<password xmlns="">usuarioxpto</password> 
										</readMO> 
									</soap:Body> 
								</soap:Envelope>
					
					

Atenção para a leitura das mensagens

Perceba que o XML é um simples XML passando usuário e senha, e o sistema vai pesquisar todas respostas, que estejam com o flagh lida setado para 0, ou seja, não estão lidas ainda. E na sua próxima requisição, essas mensagens não vão aparecer no corpo do XML de resposta, pois já foram lidas.

Códigos de retorno da integração

Exemplo de um XML de retorno de uma requsição com duas respostas marcadas como não lidas

					
							<?xml version="1.0" encoding="UTF-8"?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> 
								<S:Body> 
									<ns2:readMOResponse xmlns:ns2="http://ws.action.fadmin.com.br/"> 
										<return> 
										<code>2</code> 
										<mos> 
											<dataHora>2017-12-19T08:37:28-02:00</dataHora> 
											<mensagem>Obrigado e bom dia!</mensagem> 
											<smsId>157467149</smsId> 
											<telefone>5198335238</telefone> 
										</mos> 
										<mos> 
											<dataHora>2017-12-18T17:32:03-02:00</dataHora> 
											<mensagem>Obrigado pela lembrana!</mensagem> 
											<smsId>157434258</smsId> 
											<telefone>51982353528</telefone> 
										</mos> 
										<msg>Existem MOs</msg> 
										</return> 
									</ns2:readMOResponse> 
								</S:Body> 
							</S:Envelope>
					
					

Para fins de desenvolvimento, marque suas respostas como não lida:

Quando o WebService de Leitura de mensagens for acionado, automaticamente as mensagens que retornarem para a requisição serão marcadas como lida = 1 (que indica que você já as leu) com paginação de 50 em 50 mensagens. (A requisição apenas retorna 50 mensagens por vez). Para você continuar consultando se existem mensagens não lida, faça várias requisições.
Para testes, você pode entrar no painel da Facilita Móvel ir em Listar
Mensagens/Recebidas e marcar todas como Não Lida.