O objetivo do tutorial de integração é guiar os

Tutorial de
Integração
PYTHON
Sumário
Tutorial de Integração - Python ............................................................................................ 3
Configurando Envio .............................................................................................................. 4
Enviando Múltiplos SMS ........................................................................................................ 5
Enviando Múltiplos SMS a partir de um arquivo CSV ............................................................... 7
Enviando SMS Individuais ..................................................................................................... 8
Cancelamento de envio de SMS .......................................................................................... 10
Consulta de SMS recebidos ................................................................................................. 11
Consulta de status de SMS.................................................................................................. 12
Obtendo respostas das requisições ...................................................................................... 13
Glossário ........................................................................................................................... 14
2
Tutorial de Integração - Python
Objetivo
O objetivo do tutorial de integração é guiar os desenvolvedores que desejam integrar suas aplicações ao
gateway de SMS da Zenvia, automatizando assim seus envios de SMS conforme sua necessidade.
Mostraremos em simples passos como fazer suas aplicações Python enviarem SMS por meio da
biblioteca de integração que disponibilizamos para facilitar os envios.
Pré-requisitos
Para executar a biblioteca de integração Python, basta ter instalada a versão 2.0 ou superior do Python.
Visite http://www.python.org/.
Entendendo a biblioteca Python
A biblioteca Python é um conjunto de classes que tem como principal função fazer requisições HTTP da
forma mais organizada e simplificada possível, fazendo com que poucas informações sejam passadas
por sua aplicação.
3
Configurando Envio
1º Passo
Faça o download da biblioteca de integração por meio do link
http://www.zenvia.com.br/desenvolvedores/bibliotecas/Python.zip descompacte o conteúdo do arquivo
dentro da pasta onde se encontrão os códigos-fontes de sua aplicação (p. ex., dentro da pasta src).
2º Passo
Para manipulação de mensagens (envios e consultas), importe em seu código Python a biblioteca
HumanClientMain do package HUMANSMS.
Exemplo:
from humansms.HumanClientMain import *
3º Passo
Para qualquer operação do gateway de SMS, é preciso identificar-se com sua conta e código de acesso.
Trabalharemos com a instância da classe MultipleMessageService para envio múltiplo de SMS; com a
instância da classe SimpleMessageService para envio de mensagens simples; e com a instância da classe
QueryService para consultas de status de SMS, sempre passando por parâmetros de seus construtores a
sua conta e o código de acesso. Tais dados são cedidos pela Zenvia juntamente com a negociação do
contrato firmado com a empresa.
Exemplo:
send = SimpleMessageService('human.fake.hc', 'ABC132')
send = MultipleMessageService('human.fake.hc', 'ABC132')
send = QueryService('human.fake.hc', 'ABC132')
4
Enviando Múltiplos SMS
1º Passo
Crie uma instância de objeto da classe MultipleMessageService.
Exemplo:
send = MultipleMessageService('human.fake.hc', 'ABC132')
2ºPasso
Escolheremos um layout de mensagem que será passado ao gateway, pois essa configuração influencia
no formato da string que passaremos por parâmetro para o envio. Esse será passado como o segundo
parâmetro, podendo ser uma constante da classe MultipleMessage. Esse parâmetro é opcional, pois
por padrão será estabelecido o tipo C.
Exemplo:
tipo = MultipleMessage.TYPE_C
3ºPasso
Em nosso exemplo, escolheremos o layout C, que é padrão da API e que consiste em “to;message;id”.
Para adicionar mais de um SMS, inclua o caractere \n entre as strings.
Exemplo:
msg_list = "550099999999;teste0;004\n"
msg_list = "550099999998;teste1;005\n"
msg_list = "550099999997;teste2;006"
4ºPasso
Configuraremos o Retorno de Status por Callback, que, por padrão, será inativo, ou seja, igual a zero
(esse parâmetro não é obrigatório). Ele pode ser passado como uma constante da classe Message.
Exemplo:
callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS
5º Passo:
Para enviar o SMS, basta chamar o método sendMultipleList da classe MultipleMessageService e
passar os parâmetros que acabamos de definir.
Exemplo:
5
responses = send.sendMultipleListMsg(msg_list, tipo, callBack)
6ºPasso:
Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições”.
6
Enviando Múltiplos SMS a partir de um arquivo CSV
1º Passo
Crie uma instância de objeto da classe MultipleMessageService.
2ºPasso
O envio de múltiplos SMS a partir de um arquivo CSV é muito semelhante ao envio de SMS múltiplos a
partir de uma string.
Passaremos por parâmetro o caminho do arquivo, respeitando os layouts de mensagens. Utilizaremos o
layout C como exemplo.
Exemplo:
550092167288;teste0;004
550095650122;teste1;005
550097745821;teste2;005
Exemplo:
path = “C:\arquivo.csv”;
tipo = MultipleMessage.TYPE_C
3º Passo
Configuraremos o Retorno de Status por Callback, que, por padrão, será inativo, ou seja, igual a zero
(esse parâmetro não é obrigatório). Ele pode ser passado como uma constante da classe Message.
Exemplo:
callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS
4º Passo
Basta chamar o método sendMultipleFileCSV da classe MultipleMessageService e passar os
parâmetros que acabamos de definir.
Exemplo:
responses = send.sendMultipleFileCSV(path, tipo, callBack);
5ºPasso
Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições”.
7
Enviando SMS Individuais
1º Passo
Crie uma instância de objeto da classe SimpleMessageService.
Exemplo:
send = SimpleMessageService('human.fake.hc', 'ABC132')
2º Passo
Vamos informar qual SMS será enviado. O número de caracteres não deve ultrapassar 150 por
mensagem.
Exemplo:
msg= “Olá mundo da Mensagem de Texto!!”
3º Passo
Definiremos o número de celular do destinatário, sempre iniciando com o DDI 55, por se tratar de uma
mensagem nacional, e seguido do DDD da localidade de destino.
Exemplo:
to= “551199554455”
4ºPasso
Podemos também informar o número do remetente do SMS, seguindo as mesmas regras de numeração
do destinatário. Esse parâmetro é opcional.
Exemplo:
from = “555181183663”
5º Passo
Informaremos o id do SMS a ser enviado. Esse id deve ser gerado e informado por sua aplicação. Essa
informação é opcional, mas de muita importância caso você deseje cancelar ou consultar status dos
SMS.
Exemplo:
id = “002”
8
6º Passo
Para agendarmos o envio de um SMS passaremos por parâmetro a data em que queremos que o SMS
seja enviado. Esse parâmetro é opcional; se não for informado, o SMS será enviado imediatamente.
Exemplo:
schedule= “dd/mm/aaaa hh:mm:ss”
7º Passo
Configuraremos o Retorno de Status por Callback, que, por padrão, será inativo, ou seja, igual a zero
(esse parâmetro não é obrigatório). Ele pode ser passado como uma constante da classe Message.
Exemplo:
callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS
8º Passo
Agora basta chamar o método sendSimpleMsg.
responses = send.sendSimpleMsg(msg, to, from, id, schedule, callBack );
9º Passo
Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições”.
9
Cancelamento de envio de SMS
1º Passo
Para cancelarmos um SMS agendado que ainda não foi enviado, precisamos ter em mãos o id do SMS
(isso ressalta a importância de termos um controle de ids de SMS enviados em nossa aplicação).
Crie uma instância de objeto da classe SimpleMessageService.
Exemplo:
send = SimpleMessageService('human.fake.hc', 'ABC132')
2ºPasso
Agora basta invocarmos o método cancelSMS, passando por parâmetro o id do SMS que queremos
cancelar.
Exemplo:
responses = send.cancelSMS(“002”)
10
Consulta de SMS recebidos
1º Passo
Para consultar textos SMS enviados para a sua aplicação (por exemplo, quando um SMS é enviado por
sua aplicação e você espera que seu cliente a responda), sua aplicação deve estar habilitada a receber
SMS (veja mais informações na área dos desenvolvedores da Zenvia Desenvolvedores >> Consulta de
SMS Recebido)
Crie uma instância de objeto da classe QueryService.
Exemplo:
send = QueryService('human.fake.hc', 'ABC132')
2º Passo
Invoque o método listReceivedSMS, para obter a lista de SMS recebidos.
Exemplo:
responses = send.listReceivedSMS()
11
Consulta de status de SMS
1º Passo
Para consultar o status dos SMS enviados, crie uma instância de objeto da classe QueryService.
Exemplo:
send = QueryService('human.fake.hc', 'ABC132')
2º Passo
Agora basta passarmos por parâmetro uma lista com os ids dos SMS enviados.
Exemplo:
msg_list = {};
msg_list = {"001","002","003","004","005","006","007","008","009","010"}
Obs.: Fica a cargo de sua aplicação salvar os ids dos SMS ao serem enviados com o layout C
(lembrando que nesse layout o id dos SMS é passado por sua aplicação), pois assim será possível fazer
a consulta de status de cada SMS.
3º Passo
Vamos chamar o método queryMultipleStatus, passando por parâmetro a nossa lista de ids de SMS
enviados.
Exemplo:
responses = send.queryMultipleStatus(msg_list)
Podemos também fazer uma consulta individual do status de um SMS. Para isso, chamaremos o método
querySimpleStatus(), passando o id do SMS.
Exemplo:
responses = send.querySimpleStatus(“001”)
12
Obtendo respostas das requisições
Todas as requisições feitas pela API retornaram um array de objetos Response
com seus respectivos códigos e descrições da mensagem de resposta.
Exemplo:
for msgResponse in response:
print msgResponse.getCode()
print msgResponse.getDescription()
13
Glossário
Item Propriedade Descrição
1
To
Número de telefone do SMS no formato DDI + DDD + Telefone (Exemplo:
555199990101).
2
Message
Mensagem que será enviada ao telefone. Terá no máximo 150 caracteres (sem o
campo From).
3
From
Identificação do remetente que será atribuído à mensagem. O campo “Message”
+ o campo “From” devem ter tamanho máximo de 150 caracteres.
4
Id
Sua identificação do SMS para fins de consulta.
5
Schedule
Data de agendamento de envio do SMS.
6
Tipos de
INACTIVE(0) (Padrão): Não será enviada mensagem de callback para a
sua aplicação.
● FINAL(1): Será enviada a mensagem de callback com somente o estado
final de cada mensagem enviada.
● FULL(2): Será enviada a mensagem de callback com os estados
intermediários e o estado final de cada mensagem enviada.
Observação: Para os callbacks Final e Full, deverá ser cadastrado no
atendimento da Zenvia um host ao qual serão enviadas as requisições.
7
String
Conjunto de caracteres.
8
Tipos de
Tipo A: to;message
callback
layout
●
Tipo B: to;message;from
Tipo C: to;message;id
Tipo D: to;message;id;from
Tipo E: to;message;from;id;schedule
14