loading-img

Bem vindo a Integração por WebServices

Antes de começarmos, é importante você já ter sua conta criada em nosso sistema, ao criar sua conta, você recebe de brinde, 15 SMS para testar gratuitamente. Crie agora sua conta.

A Integração por WebServices da Facilita SMS, oferece aos desenvolvedores uma forma simples e fácil de integrar qualquer sistema com a nossa plataforma, possibilitando que qualquer sistema possa enviar SMS Marketings e SMS Corporativo.

Esse modelo de integração é recomendado para empresas ou negócios com necessidades específicas, que exijam desenvolvimento personalizado e controle sobre o código de integração. Ou seja, se você precisa disparar SMS através de sua própria plataforma, esse material irá fornecer todas as informações que você necessita.



Vantagens

Integração entre aplicações construídas em diferentes tecnologias;

Criada baseada nos padrões de mercados, sendo facilmente implementada por qualquer desenvolvedor.

De fácil manutenção, pois é um padrão aberto.



Para que haja compatibilidade com todos aparelhos e dispositivos móveis, as operadoras de telefonia celular não permitem o envio de SMS Corporativo utilizando acentuação.
Veja na imagem abaixo, um caso de incompatibilidade de um SMS que foi enviado usando acentuação.




O imite de caracteres é 160, podendo ter sua campanha cortada ou modificada se você fizer uma requisição enviando caracteres acima do permitido.



Endereço do nosso WSDL


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

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

Nome do Parâmetro Obrigatoriedade Descrição
user Obrigatório Usuário de Login na plataforma Facilita
password Obrigatório Senha de Login na plataforma Facilita
destinatario Obrigatório Destinatário que receberá a mensagem (sempre considerando o DDD)
message Obrigatório Mensagem a ser enviada, sempre considerando a Codificação de URL Encode
externalkey Opcional Qualquer chave fornecida pelo cliente: para pós utilização para consulta de status pela chave fornecida pelo próprio cliente. Uma primary key da sua tabela, por exemplo.

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

Código Descrição do código
551 Usuário ou Senha enviados na URL estão inválidos, ou a conta pode estar inativa/cancelada.
2 Usuário não possúi créditos na plataforma
3 Número de Celular enviado por parâmetro, está inválido
4 O parâmetro message (mensagem) enviado está vazio, ou possui características de uma mensagem inválida
5 Mensagem aceita pela plataforma e jogada para a fila de envio. Verifique que no caso a mensagem for aceita pela plataforma, também será devolvido no XML um SMS ID. Trata-se do ID do SMS dentro da plataforma Facilita, e deve ser usado para consultas de status.

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://www.facilitamovel.com.br/SendMessage
					
					


Parâmetros usados nesta requisição

Nome do Parâmetro Obrigatoriedade Descrição
user Obrigatório Usuário de Login na plataforma Facilita
password Obrigatório Senha de Login na plataforma Facilita
Lista Contendo: phone Obrigatório Destinatário que receberá a mensagem (sempre considerando o DDD)
Lista Contendo: message Obrigatório Mensagem a ser enviada, sempre considerando a Codificação de URL Encode
Lista Contendo: externalkey Opcional Qualquer chave fornecida pelo cliente: para pós utilização para consulta de status pela chave fornecida pelo próprio cliente. Uma primary key da sua tabela, por exemplo.

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> 
								</sendMultipleMessage> 
							</soap:Body> 
						</soap:Envelope>
					
					


Códigos de retorno da integração

Código Descrição do código
551 Usuário ou Senha enviados na URL estão inválidos, ou a conta pode estar inativa/cancelada.
2 Usuário não possúi créditos na plataforma
3 A Lista contendo os parâmetros de mensagem e telefone está nula
4 A Lista contendo os parâmetros de mensagem e telefone está vazia
5 Celular inválido
6 Campo mensagem está vazio
7 Mensagem aceita pela plataforma e jogada para a fila de envio. Verifique que no caso a mensagem for aceita pela plataforma, também será devolvido no XML um SMS ID. Trata-se do ID do SMS dentro da plataforma Facilita, e deve ser usado para consultas de status.

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://www.facilitamovel.com.br/SendMessage
					
					


Parâmetros usados nesta requisição

Nome do Parâmetro Obrigatoriedade Descrição
user Obrigatório Usuário de Login na plataforma Facilita
password Obrigatório Senha de Login na plataforma Facilita
Lista Contendo: phone Obrigatório Destinatário que receberá a mensagem (sempre considerando o DDD)
Lista Contendo: message Obrigatório Mensagem a ser enviada, sempre considerando a Codificação de URL Encode
Lista Contendo: externalkey Opcional Qualquer chave fornecida pelo cliente: para pós utilização para consulta de status pela chave fornecida pelo próprio cliente. Uma primary key da sua tabela, por exemplo.
day Opcional Agenda a Mensagem para determinado dia
month Opcional Agenda a Mensagem para determinado mês
year Opcional Agenda a Mensagem para determinado ano
formHour Opcional Agenda a Mensagem para determinada hora
formMinute Opcional Agenda a Mensagem para determinado minuto
flashsms Opcional Envie 1 quando quiser enviar 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.

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

Código Descrição do código
551 Usuário ou Senha enviados na URL estão inválidos, ou a conta pode estar inativa/cancelada.
2 Usuário não possúi créditos na plataforma
3 A Lista contendo os parâmetros de mensagem e telefone está nula
4 A Lista contendo os parâmetros de mensagem e telefone está vazia
5 Celular inválido
6 Campo mensagem está vazio
7 Mensagem aceita pela plataforma e jogada para a fila de envio. Verifique que no caso a mensagem for aceita pela plataforma, também será devolvido no XML um SMS ID. Trata-se do ID do SMS dentro da plataforma Facilita, e deve ser usado para consultas de status.

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://www.facilitamovel.com.br/SendMessage
					
					


Parâmetros usados nesta requisição

Nome do Parâmetro Obrigatoriedade Descrição
user Obrigatório Usuário de Login na plataforma Facilita
password Obrigatório Senha de Login na plataforma Facilita
smsId Obrigatório ID do SMS da Facilita fornecido no envio da mensagem.

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

Código Descrição do código
551 Usuário ou Senha enviados na URL estão inválidos, ou a conta pode estar inativa/cancelada.
550 SMSId fornecido é inválido, você deve informar um SMSID numérico apenas.
0 Status informado não existe.
1 Mensagem na fila para envio
2 Mensagem agendada
3 Mensagem sendo enviada
4 Mensagem entregue com sucesso na operadora
5 A mensagem não foi enviada por algum erro, celular inválido ou número inexistente.

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://www.facilitamovel.com.br/ReceiveMessage?wsdl
					
					


Parâmetros usados nesta requisição

Nome do Parâmetro Obrigatoriedade Descrição
user Obrigatório Usuário de Login na plataforma Facilita
password Obrigatório Senha de Login na plataforma Facilita

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

Código Descrição do código
1 Usuário ou Senha enviados na URL estão inválidos, ou a conta pode estar inativa/cancelada.
2 Existem MOs para serem Lidos (capturar de acordo com o XML de Resposta)
3 Não existem MOs não Lidos

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.