Envio de SMS utilizando a API Zenvia

No CRM One disponibilizamos mediante a contratação de um serviço adicional o envio de SMS, em caso de dúvidas sobre a contratação, enviar e-mail para comercial@dwu.com.br

Além da contratação da funcionalidade no CRM One, a sua empresa necessita contratar os serviços da Zenvia.

Pré requisito é o Addon estar na versão CRM One 10 release 2021.09.6.001 ou superior.

Contratação Zenvia

Para acessar as informações de contratação poderá faze-lo através do link abaixo:

SMS

* Link válido em 25/11/2021 momento da publicação deste artigo, podendo ter sofrido alterações.

Criar uma conta na Zenvia e assinar um plano.

Com a sua conta criada, acessar o painel de administração

Zenvia – API SMS

Para integração com a Zenvia, foram seguidas as orientações contidas no manual: https://zenviasms.docs.apiary.io/#reference/servicos-da-api/envio-de-um-unico-sms

Foi escolhido o formato REST de uso da API, desta forma a comunicação ocorre no endereço:

https://api-rest.zenvia.com/services/send-sms

Para o correto funcionamento é importante observar as orientações da documentação Zenvia, que inclui as informações sobre liberação de portas e endereços de internet.

Arquitetura de funcionamento

No banco de dados do SAP Business One é criado pelo CRM One uma tabela, chamada [@DWU_MSG_SMS], nesta tabela deverão ser inseridos registros correspondentes as mensagens de SMS, cada registro representa apenas uma mensagem.

Os registros podem ser inseridos através de comandos SQL diretamente no banco de dados, ou através de um formulário padrão no SAP Business One, disponível através do menu “Ferramentas > Janelas definidas pelo usuário > DWU_MSG_SMS – CRM One – Mensagem SMS”

Através do caminho acima, será aberto o formulário onde as mensagens de SMS podem ser inseridas manualmente pelo usuário.

Embora, exista a opção de utilização de um formulário no SAP Business One, a forma mais prática de utilização da ferramenta é a criação de comandos de banco de dados, que realizem o processamento e a inserção de registros de forma automatizada na tabela [@DWU_MSG_SMS], podendo para tanto o desenvolvimento de uma função e sua chamada através de gatilhos, via [SBO_SP_TransactionNotification] ou [SBO_SP_PostTransactionNotice].

Tabela [@DWU_MSG_SMS]

A tabela [@DWU_MSG_SMS] possui a relação de campos a seguir, onde cada campo possui uma característica para funcionamento do sistema.

Nesta tabela poderão ser adicionados campos extras pela empresa usuária do SAP Business One, que podem ser usados para controles internos, porém os campos adicionais serão ignorados pelo serviço de envio de SMS.

Na coluna Aplicação, as opções são:

• “Leitura” é um campo que durante o processamento do serviço ele será apenas lido pelo serviço seus dados processados e enviados.
• “Leitura e escrita” é um campo que durante o processamento do serviço poderá ter seus dados lidos, dependendo de na configuração de envio ele ser um campo utilizado e após o envio, dependendo da configuração de retorno poderá ter alguma informação gravada no campo com algum retorno da API.

Nome	Descrição	Aplicação	Utilização
Code	Code	Leitura	Inserir um número inteiro sequencial crescente.
Name	Name	Leitura	Inserir um número inteiro sequencial crescente.
U_IdConfig	IdConfig	Leitura	Deverá ser informado o código do cadastro com os dados de integração do formulário “Configuração de envio de SMS” no CRM One, tipicamente o primeiro cadastro de configuração é o 1, mas poderá ser outro número caso mais de uma conta de envio de SMS esteja configurada.
U_ObjType	ObjType	Leitura	Uso livre, como sugestão registrar o ObjType de um documento ou registro do SAP Business One, se por exemplo o SMS corresponde a alguma informação de um documento do tipo “Nota fiscal de saída” tabela OINV o ObjType deste documento no SAP é 13, então neste cenário preencher este campo com o valor 13.
U_ObjEntry	ObjEntry	Leitura	Uso livre, como sugestão registrar o DocEntry de um documento ou registro do SAP Business One, se por exemplo o SMS corresponde a alguma informação de um documento do tipo “Nota fiscal de saída” tabela OINV o DocEntry.
U_Assunto	Assunto	Leitura	Uso livre, como sugestão registrar a descrição para uso interno sobre a mensagem enviada.
U_Destinatario	Destinatario	Leitura	Colocar o telefone do destinatário do SMS, lembrando que para a Zenvia este campo deve ser no formato: [Código de pais][DDD com 2 dígitos][Numero do celular com 9 dígitos] Caso o destinatário é do Brasil, com telefone DDD 011 de São Paulo e número de telefone 9.8765.4321, considerando o exemplo registrar: 5511987654321
U_TextoSMS	Texto SMS	Leitura	Mensagem do SMS que deverá ser enviado, lembrando que mensagens não acentuadas podem ser 160 caracteres, ou até 70 caracteres para mensagens acentuadas.
U_Status	Status	Leitura	Preencher com ‘N’ as opções para este campo é N ou Y, onde N significa que a mensagem ainda não foi enviada e Y significa que a mensagem foi enviada para a API da Zenvia, se houve sucesso deve ser verificado nos campos “Status Code” e “Detail Code” observando os retornos de acordo com a tabela da Zenvia.
U_StatusCode	Status Code	Leitura e escrita	Uso livre, sugestão deixar em branco, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_DetailCode	Detail Code	Leitura e escrita	Uso livre, sugestão deixar em branco, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_MensagemRetorno	Mensagem Retorno	Leitura e escrita	Uso livre, sugestão deixar em branco, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_DataMsg	DataMsg	Leitura e escrita	Uso livre, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_HoraMsg	HoraMsg	Leitura e escrita	Uso livre, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_DataEnv	DataEnv	Leitura	Deixar em branco, este campo independente de configuração receberá a data em que o serviço obteve êxito em comunicar com a API.
U_HoraEnv	HoraEnv	Leitura	Deixar em branco, este campo independente de configuração receberá a hora em que o serviço obteve êxito em comunicar com a API.
U_Usuario	Usuario	Leitura	Uso livre.
U_Obs1	Obs1	Leitura e escrita	Uso livre, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_Obs2	Obs2	Leitura e escrita	Uso livre, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_Obs3	Obs3	Leitura e escrita	Uso livre, poderá ser atualizado de acordo com a configuração no retorno do envio.
U_DataProg	DataProg	Leitura	Uso livre
U_HoraProg	HoraProg	Leitura	Uso livre
U_ResponderPara	Resposta Para	Leitura	Uso livre
U_TentativasEnvio	Tentativas Envio	Leitura	Uso livre, deixar em branco ou informar um número inteiro maior que zero, para representar quantas tentativas de envio devem ser processadas.
U_Falhas	Falhas	Leitura	Deixar em branco, campo utilizado para registrar o número de tentativas de envio em caso de fahas de comunicação
U_Remetente	Remetente	Leitura	Uso livre
U_Bool	Bool	Leitura	Uso livre, mas poderá ser usado com as strings ‘true’ ou ‘false’ de acordo com a necessidade

Função para inserir registros na tabela de SMS em SQL para SAP HANA

CREATE PROCEDURE CRMONE_ENVIOSMS
(
Filtro INT      -- Ao realizar a chamada para função, passar como parâmetro o número inteiro da última mensagem enviada e armazenada no campo "@DWU_MSG_SMS"."Code"
)
LANGUAGE SQLSCRIPT
AS
BEGIN
	DECLARE CONTADOR INTEGER = :Filtro;      -- Declara uma variável para servir como contador

	---------------------------------------------------------------------------------------------
	-- Declaração de um cursor que receberá e armazena o resultado de uma consulta
	DECLARE CURSOR _cursor FOR
		SELECT 
		'1' as "IdConfig",
		'13' as "ObjType",
		'123' as "ObjEntry",
		'SMSNF' as "Assunto",
		'5511987654321' as "Destinatario",
		'Emitida a NF número 123' as "TextoSMS",
		'N' as "Status",
		CONCAT(CONCAT(CONCAT(CONCAT(CAST(EXTRACT(YEAR FROM NOW()) AS VARCHAR(4)),'-'),CONCAT(CAST(EXTRACT(month FROM NOW()) AS VARCHAR(4)),'-')),RIGHT(CONCAT('0',CAST(EXTRACT(DAY FROM NOW()) AS VARCHAR(4))),2)),'T09:00:00') AS "Obs1",
		CAST(NOW() as date) as "DataProg",
		'CRM One' as "Remetente",
		'false' as "Bool"
		FROM "DUMMY"					

	-- Abre cursor
	FOR _cursorRow AS _cursor
		DO
		----------------------------------------------------------------------------------------------------------------------------------
		-- Insere linhas da tabela
		----------------------------------------------------------------------------------------------------------------------------------
		CONTADOR = CONTADOR + 1;
		INSERT INTO "@DWU_MSG_SMS"
			(
			"Code",
			"Name",
			"U_IdConfig",
			"U_ObjType",
			"U_ObjEntry",
			"U_Assunto",
			"U_Destinatario",
			"U_TextoSMS",
			"U_Status",
			"U_Obs1",
			"U_Obs2",
			"U_DataProg",
			"U_Remetente",
			"U_Bool"
			 )
			VALUES
			(
			CONTADOR
			,CONTADOR
			,_cursorRow."IdConfig"
			,_cursorRow."ObjType"
			,_cursorRow."ObjEntry"
			,_cursorRow."Assunto"
			,_cursorRow."Destinatario"
			,_cursorRow."TextoSMS"
			,_cursorRow."Status"
			,_cursorRow."Obs1"
			,'NONE'
			,_cursorRow."DataProg"
			,_cursorRow."Remetente"
			,_cursorRow."Bool"
			);
								
								
	END FOR;
	
	CLOSE _cursor;
	
END

---------------------------------------------------------------------------------------------------------------------------

Configuração

Acessar no SAP Business One, menu “Módulos > CRM One > Configurações > Serviços > Configuração de envio de SMS”

No formulário “Configuração de envio de SMS”, deverão ser realizadas as configurações:

• Usuário: informar o nome de usuário disponibilizado pela Zenvia para consumo da API
• Senha: respectiva senha do usuário disponibilizado pela Zenvia para consumo da API
• Endereço: informar o endereço da API para envio de SMS, como por exemplo https://api-rest.zenvia.com/services/send-sms
• Tempo Sinc: deverá selecionar a frequência que o serviço de envios deverá verificar e enviar novos SMS’s, recomendamos 5 minutos ou mais, para casos onde há apenas uma rotina de envios diários sugestão de usar 60 minutos.
• Limite diário de envios: informar um valor inteiro maior que 1, esta informação é obrigatória, pode ser usada para controle de volume de envios evitando surpresas nos custos com envios, caso sejam inseridas para envio mais mensagens que o definido por dia, ao atingir o limite de mensagens os envios do dia serão interrompidos.
• Envio: Neste campo deverá ser configurado o formato para geração de Json de envio dos SMS’s, a seguir será explicado com detalhes a configuração deste campo.
• Retorno: Neste campo deverá ser configurado o formato de retorno de Json com a resposta de envio e resultará na atualização do registro do SMS com o status de processamento, a seguir será explicado com detalhes a configuração deste campo.

Apêndice de tabelas com informações de retorno

As tabelas abaixo representam os retornos da API Zenvia, conforme encontrados no manual disponível em https://zenviasms.docs.apiary.io/# consulta realizada em 25/11/2021.

statusCode

Code	Description
00	Ok
01	Scheduled
02	Sent
03	Delivered
04	Not Received
05	Blocked – No Coverage
06	Blocked – Black listed
07	Blocked – Invalid Number
08	Blocked – Content not allowed
08	Blocked – Message Expired
09	Blocked
10	Error
11	Verified

detailCode

Code	Description
000	Message Sent
002	Message successfully canceled
010	Empty message content
011	Message body invalid
012	Message content overflow
013	Incorrect or incomplete ‘to’ mobile number
014	Empty ‘to’ mobile number
015	Scheduling date invalid or incorrect
016	ID overflow
017	Parameter ‘url’ is invalid or incorrect
018	Field ‘from’ invalid
021	‘id’ fieldismandatory
080	Message with same ID already sent
100	Message Queued
110	Message sent to operator
111	Message confirmation unavailable
120	Message received by mobile
121	Message Verified by Google
130	Message blocked
131	Message blocked by predictive cleansing
132	Message already canceled
133	Message content in analysis
134	Message blocked by forbidden content
135	Aggregate is Invalid or Inactive
136	Message expired
140	Mobile number not covered
141	International sending not allowed
145	Inactive mobile number
150	Message expired in operator
160	Operator network error
161	Message rejected by operator
162	Message cancelled or blocked by operator
170	Bad message
171	Bad number
172	Missing parameter
180	Message ID notfound
190	Unknown error
200	Messages Sent
210	Messages scheduled but Account Limit Reached
240	File empty or not sent
241	File too large
242	File readerror
300	Received messages found
301	No received messages found
400	Entity saved
900	Authentication error
901	Account type not support this operation.
990	Account Limit Reached – Please contact support
998	Wrong operation requested
999	Unknown Error

Esse artigo foi útil?

4.5 out Of 5 Stars

5 Stars		0%
4 Stars		100%
3 Stars		0%
2 Stars		0%
1 Stars		0%

Como podemos melhorar este artigo?

Precisa de ajuda?

Enviar