Como enviar SMS usando o Padrão JSON

Porque escolher a Facilita Móvel?

Há mais de 15 anos entregando milhões de SMS para mais de 3.500 clientes de todo o Brasil, a Facilita está entre as maiores empresas do segmento de mensagens móveis. Daí vem o nome, Facilita Móvel, mensagens móveis.

Criando sua Conta Gratuita

Crie agora mesmo sua conta gratuita na Facilita SMS e ganhe até 15 SMS para testar nossa ferramenta. Você irá precisar de um usuário e senha para seguir neste manual. Crie a conta e obtenha um.

Bem vindo a Integração por HTTP / URL

A Integração usando o formato JSON é um modelo para envio de SMS destinado à utilização por empresas desejam ter uma integração dos seus sistemas com a plataforma de envio de SMS da Facilita Móvel.

Vantagens da Integração por JSON

Usando este tipo de integração da Facilita Móvel, é possível que qualquer sistema que possua acesso à internet possa enviar um ou múltiplos SMS. Através de uma simples adaptação ao sistema já existente você estará apto para enviar SMS a partir do seu sistema, não importa a linguagem de programação que foi construído o sistema, qualquer que seja a linguagem ou tecnologia pode acessar a integração JSON. Para que seja feito o acesso, basta acessar a URL descrita neste manual, que um SMS será disparado através de sua conta e enviado diretamente ao canal de Mensagens de Texto da Operadora.

Funcionamento

A troca de informações (envio de SMS, consulta de créditos, consulta de status, etc.) é realizada através de requisições HTTP para o endereço:

http://api.facilitamovel.com.br/api/< função > (as funções disponíveis são explicadas mais abaixo)

Para cada uma das funções previstas, deverá ser passado um objeto JSON por HTTP, cujos conteúdos devem estar codificados seguindo o padrão descrito em cada um dos métodos abaixo. Clique aqui, caso queira saber mais sobre o padrão JSON.

O resultado destas requisições retornará com o Content-Type igual a text/plain com código Status 200. Devolveremos o retorno da sua chamada em um objeto JSON no corpo da resposta.
Atenção: Mesmo que seja retornado um Erro de Login Inválido, o retorno do request será 200, mas dentro do corpo da requisição você irá ver um JSON com a variável "result": "erro" em casos de que a Facilita encontoru algum erro, ou "result": "success" para requests que foram executados com sucesso.

Acentuação

As operadoras não aceitam acentuações nem emojis neste canal de comunicação. Retire todos caracteres especiais e acentuações da sua mensagem antes de enviar o SMS para a Facilita.
Se por um acaso você enviar um SMS usando um destes caracteres, sua mensagem corre o risco de chegar desconfigurada, ou em alguns casos, não chegar ao celular de destino.

Quebra de Linha

Para utilizar quebra de linha ou ENTER na mensagem, utilize o caractere <br> na string que compõe a sua mensagem.

								{
									"phone": "51999430558",
									"message": "Mensagem de Teste<br>Vammos enviar com Enter",
									"externalkey": "111",
									"flashsms": "1"
								}
							
							

Resultado das requisições

Você irá controlar se foi erro ou não utilizando o atributo ("result": "erro") ou ("result": "success"). Perceba também que todas requisições irão devolver um atributo com o código do retorno, represetantado no no atributo ("code": "106"). Todas requisições que retornarem algum erro, os códigos sempre irão ser acima de 100, abaixo de 100 são os atributos considerado sucesso.

Usando seu usuário e senha

Para fazer a autenticação dos métodos abaixo, você só vai precisar setar no header da sua requisição as variáveis user and password. Veja como ficaria um exemplo em Java setando o header da sua aplicação

Atenção: Quando sua conta vir a ser uma conta ativa em nossa plataforma, você deverá autorizar os Ips dos seus servidores para somente esses IPs fazerem requisições usando seu usuário e senha. Caso você tenha IPs dinâmicos, entre em contato com o nosso suporte e solicite orientação para uma autenticação alternativa.

								public void doPost(HttpServletRequest request, HttpServletResponse response)
									throws ServletException, IOException
									{
										response.addHeader("user", "xx");
										response.addHeader("password", "xx");
										RequestDispatcher view = request.getRequestDispatcher("http://api.facilitamovel.com.br/api/simpleSendJson.ft");
										view.forward(request, response);
									}
							
							

Exemplo usando XMLHttpRequest

								xmlhttp=new XMLHttpRequest();
								var formData = new FormData();
								xmlhttp.open("POST", url);
								xmlhttp.setRequestHeader("user", "xx");
								xmlhttp.setRequestHeader("password", "xx");
								xmlhttp.send(formData);
							
							

Usando o Postman para testar a integração

Toda essa construção de métodos foi devidamente testada usando a ferramenta Postman versão v10.15.2 (Collection v2.1). Deixamos aqui um link que contém o nosso projeto para você entender melhor as funcionalidades, antes de desenvolver seu projeto.

Como setar o HEADER usando o Postman

Envio Simples

Função: simpleSendJson

Method Type: POST

URL:

							http://api.facilitamovel.com.br/api/simpleSendJson.ft
							
							

Leia em nosso blog sobre o FlashSMS.

Observação: Caso os parâmetros day, month, year, hour ou minute não forem especificados, ele irá assumir os parâmetros conforme horário de Brasília, entretanto, caso você queira, poderá especificar apenas alguns deles, pois os outros permanecerão no horário de Brasília. Exemplo, você quer agendar uma mensagem para o mês de março, não precisará preencher todos parâmetros, basta preencher o parâmetro month que os outros parâmetros serão assumidos com a data corrente.

Observação 2: Caso seja enviado o código do Brasil 55 + DDD+ celular, o sistema irá tratar retirando o 55 automaticamente, esse tratamento funciona apenas para esse método.

							
								 {
									"phone": "11999654008",
									"message": "Exemplo de Mensagem",
									"externalkey": "4577"
								}
							
						

							
								{
									"result": "erro",
									"code": "106",
									"description": "Celular [519919430558] Invalido"
								}
							
						

							
								{
									"result": "success",
									"code": "1",
									"smsid": "68158362",
									"description": "Mensagem Aceita com Sucesso!"
								}
							
						

* smsid é 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”)

Envio Múltiplo

Função: multipleSendJson

Method Type: POST

URL:

							http://api.facilitamovel.com.br/api/multipleSendJson.ft
							
							

Leia em nosso blog sobre o FlashSMS.

Observação: Caso os parâmetros day, month, year, hour ou minute não forem especificados, ele irá assumir os parâmetros conforme horário de Brasília, entretanto, caso você queira, poderá especificar apenas alguns deles, pois os outros permanecerão no horário de Brasília. Exemplo, você quer agendar uma mensagem para o mês de março, não precisará preencher todos parâmetros, basta preencher o parâmetro month que os outros parâmetros serão assumidos com a data corrente.

Observação 2: Caso seja enviado o código do Brasil 55 + DDD+ celular, o sistema irá tratar retirando o 55 automaticamente, esse tratamento funciona apenas para esse método.

							
								 {
									"day": "19",
									"month": "12",
									"year": "2023",
									"hour": "11",
									"minute": "10",
									"messages": [
										{
											"phone": "51999460558",
											"message": "mensagem inválida",
											"externalkey": "1",
											"flashsms": "0"
										 }, 
										  {
											"phone": "11999654448",
											"message": "mensagem de teste",
											"externalkey": "111",
											"flashsms": "1"
										 }, 
										  {
											"phone": "12999654441",
											"message": "mensagem de teste",
											"externalkey": "123",
											"flashsms": "1"
										 }
									]
								}
							
						

							
								{
									"result": "erro",
									"code": "106",
									"description": "Parametro [messages] nao pode ser nulo"
								}
							
						

							
								{
									"result": "success",
									"numeros-invalidos": [
										"151999654448"
									],
									"code": "1",
									"total-invalidos": 1,
									"total-sms-aceitos": 2,
									"sms-ids-aceitos": [
										"68158363",
										"68158364"
									],
									"description": "Mensagens Agendada com Sucesso!"
								}
							
						

* smsid é 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”)

Consultar Status da Mensagem

Função: dlrStatusJson

Method Type: POST

URL:

							http://api.facilitamovel.com.br/api/dlrStatusJson.ft
							
							

							
								{
									"smsid": "68158313"
								}
							
						

							
								{
									"result": "erro",
									"code": "106",
									"description": "[smsid] nao encontrado na base"
								}
							
						

							
								{
									"result": "success",
									"code": "1",
									"description": "Mensagem na fila para envio",
									"status": 1
								}
							
						

Consultar Status da Mensagem pela Chave do Cliente

Função: dlrByExternalKeyJson

Method Type: POST

URL:

							http://api.facilitamovel.com.br/api/dlrByExternalKeyJson.ft
							
							

							
								{
									"externalkeys": [
										{
											"key": "321"
										}, 
										{
											"key": "111"
										}, 
										{
											"key": "111222"
										} 
									]
								}
							
						

							
								{
									"result": "erro",
									"code": "105",
									"description": "Parametro [externalkeys] nao pode ser nulo"
								}
							
						

							
								[
									{
										"result": "success",
										"code": "1",
										"description": "Mensagem Agendada",
										"key": "111",
										"status": 2
									},
									{
										"result": "success",
										"code": "1",
										"description": "Mensagem Agendada",
										"key": "321",
										"status": 2
									},
									{
										"result": "success",
										"code": "1",
										"description": "Mensagem sendo enviada",
										"key": "111222",
										"status": 3
									}
								]
							
						

Verificando créditos em sua conta

Função: checkCreditJson

Method Type: POST

URL:

							http://api.facilitamovel.com.br/api/checkCreditJson.ft
							
							

									
										{
											"result": "erro",
											"code": "104",
											"description": "Login Invalido"
										}
									
								

									
										{
											"result": "success",
											"code": "1",
											"credits": 15400,
											"date-expires": "23-06-2023"
										}