Como enviar SMS por integração HTTP / URL

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 HTTP é um componente 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 HTTP

Através da Integração HTTP 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 HTTP. 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 conjunto de parâmetros HTTP, cujos conteúdos devem estar codificados seguindo o padrão URLEncode (ver abaixo Formatos e Padrões).

O resultado destas requisições retornará com o Content-Type igual a text/plain. As diversas informações recebidas serão dividas em linhas onde, na primeira linha, obrigatoriamente existirá um código de retorno.

Autenticação somente por IPs previamente cadastrados

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.

Quebra de Linha

Para utilizar quebra de linha ou ENTER na mensagem, utilize o caractere <br> na string que compõe a sua mensagem.
Exemplo: http://api.facilitamovel.com.br/api/simpleSend.ft?user=xxx&password=xxx&destinatario=5191561100&externalkey=123&msg=Ola%20Facilita<br>Atenciosamente Facilita SMS

Envio Simples

Função: simpleSend

URL:

							http://api.facilitamovel.com.br/api/simpleSend.ft?user=xxx&password=xxx&destinatario=5191561100&externalkey=123&msg=Ola%20Facilita
							
							

Leia em nosso blog sobre o FlashSMS.

Observação: Caso os parâmetros day, month, year, formHour ou formMinute 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.

Exemplo de como codificar o campo mensagem usando a linguagem Java:

String mensagem = URLEncoder.encode(mensagem, "UTF-8");

Status de Retorno(após a URL ser invocada/chamada)

* Id Mensagem é 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: multipleSend

URL:

							http://api.facilitamovel.com.br/api/multipleSend.ft?user=xxx&password=xxx&destinatario=5191561100;5199340668&msg=Ola%20Facilita&externalkey=123;124
							
							

Observe que a diferença do envio múltiplo para o simples, é a função a ser chamada (multipleSend) e a variável destinatário neste caso, recebe celulares separados por ponto e vírgula.

É estritamente recomendado fazer a chamada do envio múltiplo usando o método POST do HTTP.

Leia em nosso blog sobre o FlashSMS.

Exemplo de como codificar o campo mensagem usando a linguagem Java:

String mensagem = URLEncoder.encode(mensagem, "UTF-8");

Status de Retorno(após a URL ser invocada/chamada)

Envio de Múltiplas Mensagens para Múltiplos Telefones

Função: messagesPhonesMultipleSend

URL:

							http://api.facilitamovel.com.br/api/messagesPhonesMultipleSend.ft?user=xx&password=xx&destinatario=5199999999/n11999999999&msg=teste/nteste2&externalkey=xx/nxx1
							
							

Esta função se diferencia da Envio Múltiplo pelo fato de que com esta função você irá poder enviar diversas mensagens para diversos números de celulares. Ao invés de você fazer uma chamada para cada mensagem, use essa função para enviar “em lote” diversos envios. Essa função não devolve Status de Entrega na operadora, portanto, é recomendável você passar o parâmetro “externalKey” com sua chave interna, para posteriormente você recuperar o status.

É estritamente recomendado fazer a chamada do envio múltiplo usando o método POST do HTTP.

Observação: Caso os parâmetros day, month, year, formHour ou formMinute 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.

Exemplo de como codificar o campo mensagem usando a linguagem Java:

String mensagem = URLEncoder.encode(mensagem, "UTF-8");

Status de Retorno(após a URL ser invocada/chamada)

Envio por Campanha

Função:sendToCampaign

URL:

							http://api.facilitamovel.com.br/api/sendToCampaign.ft?user=xx&password=xx&destinatario=xx&id=xx
							
							

Campanha é uma ferramenta que a Facilita Móvel dispõe para seus usuários realizarem diversas ações. Entre as maiores usabilidades de campanha podemos destacar uma pesquisa de satisfação, enquetes, etc. Toda manutenção da campanha deve ser feita através do painel do usuário, entretanto depois de criar uma campanha, você poderá continuar enviando SMS para seus usuários através desta mesma campanha. (Com um único detalhe, não é necessário adicionar a mensagem nessa requisição, o sistema irá utilizar a mensagem que foi usada na criação da campanha). Imagine que você crie uma pesquisa de satisfação para o mês de março. Após os clientes saírem da Loja, seu sistema continuará usando essa mesma campanha, correto? Então você utilizará essa integração para continuar enviando SMS conforme a campanha criada no painel do usuário.

Leia em nosso blog sobre o FlashSMS.

Verificando Créditos de sua Conta

Função:CheckCredit

URL:

							http://api.facilitamovel.com.br/api/checkCredit.ft?user=xxx&password=xxx
							
							

Exemplo de retorno de uma chamada com sucesso: 2;40000

Verificando Créditos de sua Conta e sua data de validade

Função:checkCreditExpires

URL:

							http://api.facilitamovel.com.br/api/checkCreditExpires.ft?user=xxx&password=xxx 
							
							

Exemplo de retorno de uma chamada com sucesso: 2;40000;31/12/2017

Verificando Previsão de Créditos

Função: checkConsolidatedCredits

URL:

							http://api.facilitamovel.com.br/api/checkConsolidatedCredits.ft?user=xxx&password=xxx
							
							

Descrição: Como os créditos em sua conta só são debitados após as mensagens serem enviadas, as mensagens agendadas não contam como créditos debitados ainda, mas para algumas situações, você precisa de uma real previsão dos créditos já descontados e dos créditos que você precisa ainda ter para que estas mensagens sejam disparadas.

Exemplo de retorno de uma chamada com sucesso: 2;29999

Verificando Quantidade de Mensagens Agendadas

Função: checkSchedMessages

URL:

							http://api.facilitamovel.com.br/api/checkSchedMessages.ft?user=xxx&password=xxx 
							
							

Descrição: Retorna a quantidade de mensagens agendadas

Exemplo de retorno de uma chamada com sucesso: 2;29999

Consultar Status da Mensagem

Função: dlrStatus

URL:

							http://api.facilitamovel.com.br/api/dlrStatus.ft?user=xxx&password=xxx&id=xx
							
							

Descrição: Retorna o status da mensagem

Exemplo de retorno de uma chamada com sucesso: 4

Consultar Status da Mensagem pela chave fornecida pelo cliente

Função: dlrByExternalKey

URL:

							http://api.facilitamovel.com.br/api/dlrByExternalKey.ft?user=xxx&password=xxx&externalkey=123;111
							
							

Descrição: Retorna o/os status da/s mensagem/s

Caso você passe mais de um Id separado por ponto e vírgula, a resposta terá como separador o hífem, exemplo:

Supondo que você passe a seguinte requisição:

						
							http://api.facilitamovel.com.br/api/dlrByExternalKey.ft?user=xxx&password=xxx&externalkey=123;111
						
						

A sua resposta será: 123;4-111;5

Entregamos o status para você

Para que possamos entregar o status de entrega da Mensagem na Operadora, você precisa se logar no painel da Facilita, e no menu da direita, clicar em Webhooks, e lá você vai configurar tanto a URL de entrega de Status, quanto a URL de entrega de Respostas (MO).

URL de Exemplo que você deverá fornecer:

							http://www.suaempresa.com/status.jsp?phone=xx&sms_id_facilita=xx&status_mensagem=xx
							
							

Descrição: Retorna o status de envio da Mensagem

É muito importante que você crie essa URL e na hora de alterar o status de sua plataforma conforme recebido através da Facilita, valide sempre o SMS ID Facilita + Número de Telefone que entregamos para você.

Não existe nomenclatura obrigatória nos parâmetros, basta você nos passar a sua URL que cadastremos em nosso sistema.

Lembrando, o ID SMS Facilita é capturado na requisição de envio do SMS usando o método simpleSend.

Entregamos as Mensagens Recebidas (MO) para você.

Para que possamos entregar a Resposta (Mensagens Respondidas pelos seus clientes) para você, você precisa se logar no painel da Facilita, e no menu da direita, clicar em Webhooks, e lá você vai configurar tanto a URL de entrega de Status, quanto a URL de entrega de Respostas (MO).

URL de Exemplo que você deverá fornecer:

							http://www.suaempresa.com/status.jsp?telefone=xx&datahora=xx&mensagem=xx
							
							

Para você vincular essa mensagem recebida com a mensagem que foi origanada para o número, recomendamos você realizar uma consulta em sua base pelo último numero enviado para este número celular. Isso é um padrão de mercado e é como as operadoras trabalham.

Não existe nomenclatura obrigatória nos parâmetros, basta você nos passar a sua URL que cadastremos em nosso sistema.

Consultando Mensagens Recebidas (MO)

Para consultar as mensagens Recebidas, o usuário poderá acessar a seguinte URL:

							http://api.facilitamovel.com.br/api/readMO.ft?user=xx&password=xx
							
							

Caso não conste Login inválido no retorno da chamada, duas possibilidades poderão acontecer aqui, ou o resultado vir vazio (“”), ou a chamada retornar as mensagens recebidas. Para trata-las você deverá seguir o seguinte padrão:

Separador de Mensagens Recebidas: /n/n

Separador de Campos de Cada Mensagem: /n;

Ordem dos Campos: Telefone, Data/Hora (Formato 2013-12-31 23:59:59 (ano-mês-dia hora:minuto:segundo), Mensagem

Veja um exemplo de requisição em Java chamando MOs:

							http://www.facilitamovel.com.br/manuais/ConsultarMo.java
						
						

IMPORTANTE

Lembre-se que, quando você ler através da URL as Mensagens Rebidas, apenas 50 mensagens irão voltar para você, e essas mensagens passarão a ter status de lida=1 em nossa plataforma, e para continuar lendo as próximas, você deverá fazer várias chamadas até obter o retorno vazio (“”); Caso você esteja testando a integração e queira marcar como não lida a mensagem novamente, vá até o painel da Facilita com seu usuário e senha, clique em Listar Mensagens -> Respostas -> Selecionar mensagens e marcar como não lida.

Consultando Mensagens Recebidas (MO) por ID do SMS devolvido na requisição do Envio

Mesma definição do método 14 (readMO), entretanto aqui se passa o ID da mensagem enviada.

							http://api.facilitamovel.com.br/api/readAllMOBySmsId.ft?user=xx&password=xx&id=xxxx 
							
							

Caso não conste Login inválido no retorno da chamada, duas possibilidades poderão acontecer aqui, ou o resultado vir vazio (“”), ou a chamada retornar as mensagens recebidas. Para trata-las você deverá seguir o seguinte padrão:

Separador de Mensagens Recebidas: /n/n

Separador de Campos de Cada Mensagem: /n;

Ordem dos Campos: Telefone, Data/Hora (Formato 2013-12-31 23:59:59 (ano-mês-dia hora:minuto:segundo), Mensagem

IMPORTANTE

Lembre-se que, quando você ler através da URL as Mensagens Rebidas, apenas 50 mensagens irão voltar para você, e essas mensagens passarão a ter status de lida=1 em nossa plataforma, e para continuar lendo as próximas, você deverá fazer várias chamadas até obter o retorno vazio (“”); Caso você esteja testando a integração e queira marcar como não lida a mensagem novamente, vá até o painel da Facilita com seu usuário e senha, clique em Listar Mensagens -> Respostas -> Selecionar mensagens e marcar como não lida

Excluindo Mensagens Agendadas

Função: deleteMsgSchedByPhones

URL:

							http://api.facilitamovel.com.br/api/deleteMsgSchedByPhones.ft?user=xxx&password=xxx&destinatario=5191561100;5193256654
							
							

Observação: Você pode poderá passar 1 ou vários telefones na URL destinatário, atente para o separador ponto e vírgula (;) que é o que indicará quais serão os telefones que terão suas mensagens excluídas do agendamento.

Excluindo Mensagens Agendadas por ID da Mensagem

Função: deleteMsgAgendadasPorId

URL:

							https://www.facilitamovel.com.br/api/deleteMsgAgendadasPorId.ft?user=xxx&password=xxx&ids=123;22
							
							

Observação: Você pode poderá passar 1 ou vários SMS Ids na URL através do parâmetro ids, atente para o separador ponto e vírgula (;) que é o que indicará quais serão os ids que terão suas mensagens excluídas do agendamento.

Formatos e Padrões

O servidor de Integração HTTP do Facilita Móvel utiliza alguns formatos e padrões de codificação para a transferência de dados.

Caso exista alguma dúvida, seguem abaixo os links nos quais é possível consultar suas definições.

URL Encoding

							http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1
							
							

Método HTTP

							http://www.w3.org/Protocols/
							
							

Método POST

							http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5
							
							

Exemplos de Retorno da Chamada de Integração por HTTP

O Retorno da mensagem será retornado na tela, da seguinte maneira:

6;Mensagem Enviada;

Ou para login inválido, como no exemplo abaixo:

1;Login Inválido