SMS e Easy RCS - Integração API

Esta documentação tem o objetivo de explicar as configurações relacionadas a nossa API de SMS. Nela veremos as requisições necessários para possam realizar os envios ou consultas diretamente pela API.

Utilidade da API 

• Agilidade e compatibilidade na integração entre sistemas e aplicações.

• Redução de trabalho manual.

• Automatização dos disparos.

Documentação: https://docs.pontaltech.com.br/pointer-sms-api/#!/

Menu API

Na tela do menu API você pode acompanhar a quantidade e as mensagens enviadas pelo seu CRM filtradas por período.

Acesso as credenciais API

Para realizar a conexão com a API, é necessário ter acesso as credenciais, de acordo com a conta de utilização. Essas credenciais estão disponíveis para o usuário master da conta, acessando o menu abaixo: 

Autenticação:

• Método de Conexão: basicAuth
• Autenticação:  basicAuth (HTTP Basic Authentication - base64 usuario:token)
• Content-Type: application/jason

Atenção: Apenas o usuário Master tem acesso às credenciais da API na conta Pointer.

Como gerar um token (base 64)?   

A conversão pode ser realizada acessando o site: https://www.base64encode.org/.

Exemplo de conexão (postman)

Há duas formas de conexão dependendo da ferramenta de integração que está sendo utilizada. 

A primeira é a conexão via token. O token gerado pode ser inserido diretamente na aba Headers adicionando o campo “Authorization”.

Há segunda forma é a inserção do Username e Password conforme exemplo abaixo: 

Envio de SMS convencional

São mensagens que contêm até 160 caracteres. 

Requisitos para envio via API

Para realizar um envio via API, são necessários os seguintes requisitos:

• Credenciais.

• Endpoint (de acordo com o tipo de envio).

• Body (corpo da requisição). 

• Para envios de conteúdos idênticos para o mesmo destinatário (mesmo texto e telefone) com período inferior à uma hora, há uma prevenção sistêmica para evitar erros de looping e/ou logicas de programação podendo fazer com que mensagens com estas características sejam canceladas pelo sistema. Para casos de uso que necessitem de liberação desta condição, orientamos que a área de atendimento ou gerente comercial seja acionado. 

Endpoint

O Endpoint é composto por: https://sms-api-pointer.pontaltech.com.br/v1 + Complementar de acordo com o tipo de envio.

Segue na sequência os tipos de envios múltiplo ou unitário.

Endpoint multilpleSms

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/multiple-sms

Utilizamos o método Post para essa integração que permite a configuração de um Array de mensagens (o envio de várias mensagens simultaneamente). 

Visão da disposição dos campos na Documentação API - multipleSms: 

Endpoint singleSms

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/single-sms

Utilizamos o método Post para essa integração que permite a configuração de uma única mensagem (não sendo possível a inclusão de Array ou várias mensagens).

Visão da disposição dos campos na Documentação API - singleSms:


Corpo da Requisição/Parâmetros

Para envio Single, a requisição segue o exemplo abaixo, presente na DOC:

{

  "to": 0,  

  "message": "string",  

  "schedule": "2023-06-23T 13:11:44.935Z", 

  "reference": "string",  

  "account": 0,  

  "accountReference": "string",  

  "from": "string", 

  "urlCallback": "string", 

  "flashSms": true  

}

Para envio Multiple, a requisição segue o exemplo abaixo, presente na DOC:

{

  "urlCallback": "string", 

  "flashSms": true, 

  "messages": [

    {

      "to": 0, 

      "message": "string", 

      "schedule": "2023-06-23T 13:11:44.933Z", 

      "reference": "string", 

      "account": 0, 

      "accountReference": "string", 

      "from": "string", 

      "urlCallback": "string" 

    }

  ]

}

Envio de SMS concatenado 

São mensagens que contêm acima de 160 caracteres, porém a tarifação ocorre a partir de 152 caracteres (se desejar habilitar está função, basta solicitar ao seu executivo de contas). 

Requisitos para envio via API

Para realizar um envio via API, são necessários os seguintes requisitos:

• Credenciais.

• Endpoint (de acordo com o tipo de envio).

• Body (corpo da requisição). 

• Para envios de conteúdos idênticos para o mesmo destinatário (mesmo texto e telefone) com período inferior à uma hora, há uma prevenção sistêmica para evitar erros de looping e/ou logicas de programação podendo fazer com que mensagens com estas características sejam canceladas pelo sistema. Para casos de uso que necessitem de liberação desta condição, orientamos que a área de atendimento ou gerente comercial seja acionado. 

Endpoint multilple-concat-sms 

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/multiple-concat-sms 

Corpo da requisição/Parâmetros

O corpo da requisição é similar ao Multiple, mudando apenas o Endpoint:

{

  "urlCallback": "string", 

  "flashSms": true, 

  "messages": [

    {

      "to": 0, 

      "message": "string", 

      "schedule": "2023-06-23T 13:11:44.933Z", 

      "reference": "string", 

      "account": 0, 

      "accountReference": "string", 

      "from": "string", 

      "urlCallback": "string" 

    }

  ] }

Definição dos campos da requisição

Abaixo temos a explicação detalhada de cada campo da requisição: 

"to": DDD+Número sem o DDI [OBRIGATÓRIO]; 

"message": Mensagem Texto [OBRIGATÓRIO];

No caso do envio utilizando o Endpoint do Multiple, será adicionado o parâmetro “messages” logo no início da requisição indicando que mais de uma mensagem será enviada simultaneamente. 

"schedule": "2023-06-23T 13:11:44.935Z" (data e hora do envio da mensagem de acordo com o Fuso horário GMT)

"reference": Identificador único do lado cliente, seu preenchimento não é obrigatório.

"account": [OBRIGATÓRIO PARA ENVIOS EASY RCS] Sub conta que será vinculada a ação. Dessa forma, os disparos ficarão apartados por centro de custos. O ID a ser inserido nesse campo pode ser visualizado no Menu -> Gerenciar -> Contas conforme exemplo abaixo:

"accountReference": É uma referência que é cadastrada na sub conta criada no pointer. Conforme imagem abaixo:

Caso já esteja inserindo o ID da conta no parâmetro account não é necessário inserir também a Referência.  

"from": Campo adicional para inserção do remetente, seu preenchimento não é obrigatório.

"flashSms": Para envio de SMS do tipo Flash, a ausência de preenchimento ou false envia como convencional (se desejar habilitar está função, basta solicitar ao seu executivo de contas).

"urlCallback": Webhook que receberá os retornos dos SMS. Utilizando a estrutura de Callback é possível receber os status dos disparos efetuados via API. Existem três formas de utilizar a Url de Callback:

1. Passando como parâmetro na requisição no campo "urlCallback" (não é possível em envios superfast).

2. “Gerenciar" e "Contas” (uma URL para uma conta em específico).

   
3. Ou “Gerenciar" e "Preferências” (uma URL de Callback para todas as contas).
   
   

Consulta de Status 

Utilizamos o método Post para essa integração que permite a consulta dos status recebidos referentes aos disparos realizados através da API. 

Para realizar a consulta dos envios, são necessários os seguintes requisitos:

• Credenciais.

• Endpoint (de acordo com o tipo de consulta). 

• Body (corpo da requisição). 

Endpoint Multiple-sms-report

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/multiple-sms-report  

Utilizando o multiple-sms-report é possível realizar a consulta dos retornos de status pelos IDs gerados no momento do envio da requisição. Para realizar a consulta de mais de uma mensagem basta separar os IDs por vírgula.

Exemplo:

{

  "ids": [

    0

  ]

}

Endpoint sms-report

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/sms-report

Utilizando o sms-report é possível realizar a consulta dos retornos de status pelos buscando por um intervalo de data e hora (início e fim).

Exemplo:

{

  "startDate": "2023-07-03T18:11:44.220Z",

  "endDate": "2023-07-03T18:11:44.220Z"

}

Consulta de Respostas 

Utilizamos o método Post para essa integração permite a consulta respostas recebidas das mensagens enviadas via API. 

Requisitos para captura de Respostas

Para realizar a consulta das respostas, são necessários os seguintes requisitos:

• Credenciais.

• Endpoint (de acordo com o tipo de consulta).

• Body (corpo da requisição). 

Endpoint multiple-sms-replies

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/multiple-sms-replies

Utilizando o multiple-sms-replies é possível realizar a consulta das respostas das mensagens buscando pelos IDs gerados no momento do envio da requisição. Para realizar a consulta de mais de uma mensagem basta separar os IDs por vírgula.

Exemplo:

 

{

  "ids": [

    0

  ]

}

Endpoint multiple-sms-replies

Endpoint: https://sms-api-pointer.pontaltech.com.br/v1/sms-replies

Utilizando o sms-replies é possível realizar a consulta das respostas das mensagens buscando por um intervalo de data e hora (início e fim).

Exemplo:

{

  "startDate": "2023-07-03T18:11:44.219Z", - Início do período que deseja pegar os status

  "endDate": "2023-07-03T18:11:44.219Z", - Fim do período que deseja pegar os status

  "reported": true

}

Callback

É utilizado para receber automaticamente os retornos e atualizações dos envios realizados. Callbacks são enviados via método POST para a url de callback, que pode ser atribuída nas requisições convencionais com o parâmetro urlCallback ou configurada na conta pointer (obrigatório para envios OTP). O campo classifyPremium só é enviado para clientes que possuem essa funcionalidade ativada (se desejar habilitar está função, basta solicitar ao seu executivo de contas). 

Para que o Callback funcione corretamente, é necessário que o IP de Origem 54.232.22.53 seja liberado pelo cliente. Por favor, ao realizar a solicitação para seu Executivo, providencie antecipadamente esta liberação.

Abaixo exemplos dos objetos enviados pelo callback:

Convencional: 

{ 

    "id":"1394547", 

    "type":"api_message", 

    "schedule":"2022-09-23T15:12:51.000Z", 

    "to":"11999999999", 

    "message":"mensagem", 

    "reference":"", 

    "status":"", 

    "received":"2022-09-23T15:12:53.000Z", 

    "statusDescription":""

    "bill_factor":"1", 

    "account_id":"",

    "account_reference": ""

}  

Resposta:

OTP

Transacional | Superfast

O envio do SMS ocorre imediatamente após ação. API Transacional: é a API que chamamos de SuperFast, só realiza o envio via GET (é um método de envio mais rápido, porém, menos seguro). Aconselhamos sempre usarem a rota Superfast se REALMENTE houver a necessidade de enviar o SMS e receber na hora, como por exemplo, o envio de tokens.

Requisitos para envio via API

Para realizar um envio via API, são necessários os seguintes requisitos:

• Credenciais.

• Url.

• Para envios de conteúdos idênticos para o mesmo destinatário (mesmo texto e telefone) com período inferior à uma hora, há uma prevenção sistêmica para evitar erros de looping e/ou logicas de programação podendo fazer com que mensagens com estas características sejam canceladas pelo sistema. Para casos de uso que necessitem de liberação desta condição, orientamos que a área de atendimento ou gerente comercial seja acionado. 

Endpoint

No caso do envio Superfast, toda a configuração dos parâmetros é feita diretamente na própria URL.

Url: https://sms-http-api-pointer.pontaltech.com.br/v1/message?to=11999999999&message=Mensagem&apikey=Token&account_id=ID

No envio transacional ao clicar em “Send” é gerado um ID que pode ser utilizado nas consultas de Status que será explicada no próximo tópico.

Definição dos campos da requisição

Abaixo temos a explicação detalhada de cada campo da requisição: 

"to": DDD+Número sem o DDI [OBRIGATÓRIO];

"apikey": Token [OBRIGATÓRIO]; 

"message": Mensagem Texto [OBRIGATÓRIO];

"account_id": [OBRIGATÓRIO PARA ENVIOS EASY RCS] Sub conta que será vinculada a ação. Dessa forma, os disparos ficarão apartados por centro de custos. O ID a ser inserido nesse campo pode ser visualizado no Menu -> Gerenciar -> Contas conforme exemplo abaixo:

Callback: Webhook que receberá os retornos dos SMS. Utilizando a estrutura de Callback é possível receber os status dos disparos efetuados via API. Existem duas formas de utilizar a Url de Callback:

1. “Gerenciar" e "Contas” (uma URL para uma conta em específico).
   
   
2. Ou “Gerenciar" e "Preferências” (uma URL de Callback para todas as contas).
   
   

Consulta de status

Para consultar os seus envios, basta preencher o campo "Authorization" (Basic Auth) e utilizar a url abaixo.

Consulta de status por um único ID
https://sms-api-pointer.pontaltech.com.br/v1/single-origin-sms/{id}

Consulta de status por múltiplos IDs
https://sms-api-pointer.pontaltech.com.br/v1/multiple-sms-origin-report

Consulta de Respostas

Consulta por reposta unitária
https://sms-api-pointer.pontaltech.com.br/v1/sms-origin-reply/{originId}

Consulta por múltiplas respostas
https://sms-api-pointer.pontaltech.com.br/v1/multiple-sms-origin-replies

Códigos de respostas HTTP

Ao tentar enviar uma requisição, de imediato retorna códigos, que confirmam se a requisição solicitada foi corretamente concluída ou não. Esses códigos são universais do protocolo de comunicação HTTP, onde são transmitidos os dados, e informam se houve sucesso na requisição (status 200), ou se houveram erros e quais. 

Abaixo estão definidas as classes dessas respostas:

• Respostas de informação (100-199)

• Respostas de sucesso (200-299)

• Redirecionamentos (300-399)

• Erros do cliente (400-499)

• Erros do servidor (500-599)

Caso queira saber mais, recomendamos o site https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status.

Status das mensagens

Status e códigos tarifados:

• Código 3 - Confirmação de envio por parte da operadora.

• Código 5 - Confirmação de entrega por parte da operadora.

• Código 12 - Mensagem não entregue. 

• Código 13 -  Expirado. 

Observação: Código 30 com atualização de "Mensagem lida" (apenas para envios de Easy RCS), é um status complementar de "Entregue" e por este motivo é apresentado como tarifado. 

Presente na Documentação, há os status de retorno das mensagens enviadas. Esses status são internos do nosso servidor, baseado na devolutiva final que recebemos das operadoras. Segue descritivo:

Código	Descrição
0	Mensagem aceita. Aguardando agendamento.
1	Mensagem Agendada.
2	Mensagem enviada para operadora.
3	Confirmação de envio por parte da operadora.
4	Erro no envio por parte da operadora.
5	Confirmação de entrega por parte da operadora.
6	Erro na entrega por parte da operadora.
7	Mensagem bloqueada.
8	Mensagem invalida.
9	Mensagem cancelada.
10	Erro.
11	Sem crédito.
12	Mensagem não entregue.
13	Expirado
14	Mensagem bloqueada na base de inválidos.
18	Mensagem barrada na blacklist.
19	Mensagem em recência.
29	Mensagem pausada.
30	Mensagem lida (apenas Easy RCS)
99	Mensagem em preparação.
198	Mensagem em recência mensal.

Código dos Erros 

Código dos erros do nosso servido: conforme regra de negócio vigente, esse tipo de erro ocorre não devido a requisição estar inválida, mas sim quando algum objeto possui erro. 

Exemplo: (DDD Inválido, Mensagem vazia., Conta inválida entre outros).

Segue descritivo:

Código	Descrição
100	Número inválido.
101	Número de 11 dígitos inválido.
102	Número de 10 dígitos inválido.
103	DDD inválido.
104	Mensagem tem mais de 160 caracteres (No caso do envio short).
105	Mensagem vazia.
106	Conteúdo do objeto não é um array valido (Envio Multiplo).
107	Mensagem vazia.
108	Referência tem mais de 50 caracteres.
109	Data de agendamento inválida.
110	Data inválida.
111	Período invalido.
112	Identificador inválido.
113	Url Inválido.
114	Conta sem crédito suficiente.
115	Conta inválida.
116	Referência inválida.
118	Flash SMS não autorizado.
1000	Não foi possível registrar a requisição.
1001	Não foi possível criar a mensagem.
1002	Não foi possível retornar a mensagem.
1003	Não foi possível criar a mensagem.
1004	Não foi possível criar as mensagens.
1005	Não foi possível retornar as mensagens.
1006	Não foi possível criar as mensagens.
1007	Não foi possível retornar as respostas deste período.
1008	Não foi possível retornar a resposta.
1009	Não foi possível retornar a resposta.
1010	Não foi possível retornar múltiplas respostas.
1011	Requisição inválida.
1012	Não foi possível cancelar a mensagem.

Uso de acentuação e caracteres especiais

Acentuações podem ser removidas automaticamente, de acordo com o tipo de SMS escolhido. O uso de acentos e/ou caracteres especiais pode reduzir o tamanho máximo da mensagem para 70 caracteres. Isso significa que a mensagem poderá ser cobrada como dois SMS, ao invés de um.

Para garantir que sua mensagem seja enviada da forma correta e com o menor custo possível: Utilize apenas caracteres simples, sem acentos ou símbolos especiais, sempre que possível. Em caso de dúvidas ou para mais informações sobre os tipos de SMS disponíveis e as regras de codificação entre em contato com nossa área de atendimento.

Segue a relação abaixo de caracteres considerados normais dentro de uma mensagem SMS:

(Espaço)	!	"	#	$	%	&	'	(	)
*	+	,	-	.	/	0	1	2	3
4	5	6	7	8	9	:	;	<	=
>	?	@	A	B	C	D	E	F	G
H	I	J	K	L	M	N	O	P	Q
R	S	T	U	V	W	X	Y	Z	\
_	`	a	b	c	d	e	f	g	h
i	j	k	l	m	n	o	p	q	r
s	t	u	v	w	x	y	z	{	}
~

Caso tenha dúvidas sobre esse conteúdo, por favor, abra um chamado para o nosso time de Suporte, através do e-mail: apoio.ca@pontaltech.com.br.