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:
* 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 |