SMS API

IntroduçãoLast update: 2021-04-27

Serviço responsável pelo envio de mensagens por SMS. Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como configurar e realizar o envio de mensagens.

Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como realizar o envio de mensagens.

URL API:
  • URL Externa:https://api.flexcontact.com.br/Messaging
  • URL Interna:https://10.10.2.164/Messaging

API

Documentação de Uso da API de SMS.

Login

Token de Acesso - Metodo de Login


Para utilizar os Micro Serviços Flex, é necessário um Login/ Senha fornecido pela equipa de TI. Ao realizar a validação de Login, em caso de positivo o mesmo gera um token de acesso, os login são de uso restrito e podem ser usados para todos os Micro Serviços na qual ele tem acesso.

Todas as requisições POST - Json para o API devem conter o campo de token no primeiro campo do JSON (com exceção dos métodos de Login/ Consulta Token). Todas as requisições GET - Json para o API devem conter o campo de token na URL de solicitação (com exceção dos métodos de Login/ Consulta Token).

Warning

O token de acesso tem validade de no máximo 6 horas, após este periodo, deve-se logar novamente para gerar um novo Token.


Método de utilização:

POST - https://api.flexcontact.com.br/Messaging/Login


JSON:

Exemplo de JSON de Login, substitua as informações abaixo por suas credenciais.


                                

                                    {

                                        "login": "flex.flex",

                                        "password": "12345678"

                                    }

                                

                            

Envio de Mensagem – Post

Metodo de Send


Método genérico de envio de mensagens para SMS. Todos os envios estarão atrelados a uma campanha. Estes envios serão realizados pelo método Send.

Método utilizado para enviar mensagens de SMS.


Método de utilização:

POST - https://api.flexcontact.com.br/Messaging/Send

Orientação de Uso

Para envios em massa, utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de envio em duas ou mais postagens de 1000 conforme a quantidade que deseja enviar.


Dicionário de dados:
Campo Tipo Descrição Parâmetro Obrigatório
token string Token de retorno obtido após o Login na Api. Json
codCampaign integer Código da campanha relacionado ao envio das mensagens. Json
ID string Id de envio de mensagem enviado para identificação, caso não será enviado, será gerado um id randômico. Json
Telephone string Número do telefone que receberá a mensagem. Json
Message string Texto da mensagem simples. Json
JSON:

Exemplo de Json de Envio para SMS, substitua as informações abaixo de token pelo token obtido no Login.


                            

                                        [

                                            {

                            "token": "token",

                            "codCampaign": "1",

                            "Telephone": "5511980125654",

                            "Message": "Envio Teste"

                                            }

                                        ]

                                    

                                

Consulta de Status em Lote

Metodo de Consulta


Método de Consulta do Status dos SMS.

Para cada SMS enviado é possível consultar o status da mensagen, se deu sucesso ou erro ao enviar.


Método de utilização:

POST - https://apiwp02.code7.com/Consultas/Status/


Orientação de Uso

Utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de consulta em duas ou mais postagens de 1000 conforme a quantidade que deseja consultar.


Dicionário de dados:
Campo Tipo Descrição Parâmetro Obrigatório
Token string Token de retorno obtido após o Login na Api. Json
IdCampanha string ID da Campanha consultada. Json
TipoRetorno integer Flag de definição do tipo de retorno dos status. Json
URLCallBack string URL para efetuarmos o post de retorno do json dos status Json
EmailCallBack string E-Mail para efetuarmos o post de retorno do json dos status Json
ListaIDsEnvio string Identificador do Envio. Json
Tipo de Retorno:

Dependendo do tipo de retorno informado, disponibilizaremos o JSon em um canal diferente seguindo a lista abaixo:

ID Tipo Descrição
1 HTTP Retornaremos o JSon na mesma requisição.
2 Post URL Faremos o post do JSon em uma URL informada no parametro URLCallBack
3 Email Enviaremos o JSon no E-Mail informado no parametro EmailCallBack

Warning

Os status somente ficam disponíveis para consulta no período de 90 dias.

Código dos Status:

Lista de possíveis Status retornados:

Status Status Message Descrição
00 Received SMS Recebido e em processamento
02 Sent SMS Enviado para o destinatário
03 Delivered SMS Entregue no celular do destinatário
04 Not Received SMS não entregue - Possível falha no envio
05 Blocked SMS bloqueado
08 Blocked SMS bloqueado
09 Blocked SMS bloqueado
JSON:

Exemplo de Json, substitua as informações abaixo de token pelo token obtido no Login.


            

		{

		"token": "token",

		"IdCampanha": "2564",

		"TipoRetorno": "1",

		"URLCallBack": "",

		"EmailCallBack": "",

		"ListaIDsEnvio": [

					{

						"IdEnvio": "123456"

					},

					{

						"IdEnvio": "1234567"

					},

					{

						"IdEnvio": "1234568"

					}

					]

		 }

                                    

                                
Retorno POST:

            

                [

                    {

                        "id": "123456",

                        "codCampaign": "2564",

                        "Telephone": "55119574852136",

                        "Date": "2021-07-22 08:00:25",

                        "status": "03",

                        "statusDetail": "Delivered",

                        "type": "SMSStatus",                        

                    },

					{

                        "id": "1234567",

                        "codCampaign": "2564",

                        "Telephone": "5511963294856",

                        "Date": "2021-07-22 08:01:12",

                        "status": "04",

                        "statusDetail": "Not Received",

                        "type": "SMSStatus",                        

                    },

					{

                        "id": "1234568",

                        "codCampaign": "2564",

                        "Telephone": "5511996548123",

                        "Date": "2021-07-22 08:01:21",

                        "status": "02",

                        "statusDetail": "Sent",

                        "type": "SMSStatus",                        

                    }					

                ]

            

        

Consulta de Respostas

Metodo de Consulta


Método de Consulta das respostas dos SMS.

É possível consultar as respostas de uma determinada campanha dentro de um período.


Método de utilização:

POST - https://apiwp02.code7.com/Consultas/Resposta/


Orientação de Uso

A consulta somente será possível dentro do período de 90 dias.


Dicionário de dados:
Campo Tipo Descrição Parâmetro Obrigatório
Token string Token de retorno obtido após o Login na Api. Json
IdCampanha string ID da Campanha consultada. Json
TipoRetorno integer Flag de definição do tipo de retorno das respostas. Json
URLCallBack string URL para efetuarmos o post de retorno do json das respostas Json
EmailCallBack string E-Mail para efetuarmos o post de retorno do json das respostas Json
dataInicio string Data de início do período da consulta. Json
dataFinal string Data final do período da consulta. Json
Tipo de Retorno:

Dependendo do tipo de retorno informado, disponibilizaremos o JSon em um canal diferente seguindo a lista abaixo:

ID Tipo Descrição
1 HTTP Retornaremos o JSon na mesma requisição.
2 Post URL Faremos o post do JSon em uma URL informada no parametro URLCallBack
3 Email Enviaremos o JSon no E-Mail informado no parametro EmailCallBack
JSON:

Exemplo de Json, substitua as informações abaixo de token pelo token obtido no Login.


            

		{

		"token": "token",

		"IdCampanha": "2564",

		"TipoRetorno": "1",

		"URLCallBack": "",

		"EmailCallBack": "",

		"dataInicio": "2021-08-24 16:00",

		"dataFinal": "2021-08-24 16:30"

		 }

                                    

                                
Retorno POST:

            

                [

                    {

                        "IdCampanha": "2564",

                        "Telefone": "55119574852136",

                        "DataRecebimento": "2021-08-24 16:15:25",

                        "Mensagem": "OK",

                        "DataDisparo": "2021-08-24 16:00:25"                     

                    },

					{

                        "IdCampanha": "2564",

                        "Telefone": "5511986452485",

                        "DataRecebimento": "2021-08-24 16:15:25",

                        "Mensagem": "Quero Acordo",

                        "DataDisparo": "2021-08-24 16:00:25"                          

                    },

					{

                        "IdCampanha": "2564",

                        "Telefone": "55119574852136",

                        "DataRecebimento": "2021-08-24 16:15:25",

                        "Mensagem": "1",

                        "DataDisparo": "2021-08-24 16:00:25"                           

                    }					

                ]

            

        

Webhook

As atualizações são enviadas através de Webhook.

Após criar o hook e enviar sua URL de Webhook as funcionalidades de callback estão ativas.

Webhook Mensagem

Callback Mensagem


Para identificar o retorno da mensagem, é necessário criar um webhook em um endereço configurado, assim o mesmo irá enviar o retorno da mensagem quando um evento acontece através de um JSon.


Dicionário de dados:
Campo Tipo Descrição
id string ID único de identificação.
codCampaign string cod. da campanha atrelada à mensagem enviada.
Telephone string Número do Telefone enviado.
Date string Data do evento.
message string Mensagem respondida pelo número enviado/ url de Media respondida pelo número.
type string Tipo da mensagem envida.
JSON:

Exemplo de Json de resposta SMS.


                                        

                                            {

                                                'id': '3AA05321A799714AADE8',

                                                'codCampaign': '1',

                                                'Telephone': '551199999999',

                                                'Date': '2018-05-17 19:38:26',

                                                'message': 'Teste',

                                                'type': 'SMSText'

                                            }

                                        

                                    

Webhook Status

Callback Status


Para identificar o retorno do status, é necessário criar um webhook em um endereço configurado, assim o mesmo iria enviar o retorno da mensagem quando um evento acontece através de um JSon.


Dicionário de dados:
Campo Tipo Descrição
id string ID único de identificação.
codCampaign string cod. da campanha atrelada à mensagem enviada.
Telephone string Número do Telefone enviado.
Date string Data do evento.
status string Status de envio.
type string Tipo do status envida.
JSON:

Exemplo de Json de status para SMS.


                                            

                                                {

                                                    'id': '3AA05321A799714AADE8',

                                                    'codCampaign': '1',

                                                    'Telephone': '551199999999',

                                                    'Date': '2018-05-17 19:38:26',

                                                    'status': 'delivered',

                                                    'type': 'SMSStatus'

                                                }

                                            

                                        

API Errors

Uma listagem de erros que podem ser retornados da API.

Error List


Ao realizar um POST com um JSON valido na API, o retorno será 200 contendo o Json de retorno do POST no Body. Em caso de Json inválido, a API vai retornar Status 400 (Bad Resquest) e no Body informar qual o possível erro do JSon, segue abaixo lista de erros e orientações para o mesmo.


Cod.Erro Erro Orientação
1 Invalid transference format Json fora do formato especificado na documentação, verifique o exemplo.
2 Login not found Login não encontrado, verifiquei o Login informado ou entre em contato com a Flex.
3 Invalid password Password invalido, verifiquei o Login informado ou entre em contato com a Flex.
4 Invalid Token Token informado é invalido ou já foi renovado, informe o token atual ou refaça o Login.
5 Expired Token Token informado expirou e é necessário nova validação no Login.
6 Enter the Token field Informe o Token obtido no Login dentro da assinatura Json.
7 Please report a valid campaign Campanha atual informada não existe, verifique.
8 Please report a valid date Campanha atual informada não existe, verifique.
10 Please report a valid Id ID no formato invalido.
11 Description of (Lote) already registered. Descrição do lote informado não esta registrado (Erro disponível somente para API MAIL).
12 Description of (html_pach) already registered. Descrição do template informado não esta registrado (Erro disponível somente para API MAIL).
13 Please report a valid namespace Namespace informada não existe, verifique. (Erro disponível somente para API MENSAGERIA - WHATSAPP).
14 Number of fields reported differently than expected for codNamespace Numero de fields informado, esta diferente do numero esperado pelo Namespace.
16 Please report a valid IdMedia IdMedia invalido ou não cadastrado no Upload.
17 Please report a valid NEW campaign Nova campanha informada não existe, verifique.
18 Informed campaign does not belong to a Whatsapp campaign Campanha atual informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp.
19 NEW Campaign reported does not belong to a Whatsapp campaign Nova Campanha informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp.
20 NEW Campaign with no registered callback url Nova campanha não tem Url de callback cadastrada.
21 Information not found on the number reported for transfer. Número de telefone informada não existe para a campanha atual..
22 Campaign download canceled due to error in new campaign webhook. Não foi possível concluir a transferência devido a problemas no webhook ao receber o histórico.
24 Invalid destination Destino de operação e Chat não informado (Erro disponível somente para envio de CHAT sem Whatsapp).
25 Destination without registered URL Destino de operação e Chat não cadastrado (Erro disponível somente para envio de CHAT sem Whatsapp).