Manual de Integração SOAP. Solução para integração de sistemas e comunicação entre aplicações diferentes.

(1)

Manual de Integração

SOAP

Solução para integração de sistemas e comunicação entre aplicações diferentes.

(2)

Índice

1. Web Service SOAP – Definições

3 2. Integração WebService com Plataforma Virtual Target

5

2.1. Sincronização 5

2.2. Limitações 5

2.3. Usuário de Integração 6

2.4. Identificação de Lista de Contatos 6

2.6. Definição dos métodos WSDL 7

3. Métodos

8

3.1. Assuntos co-relacionados 8

3.2. Especificação dos Métodos 10

3.2.1. Método “AdicionaAtualizaContato” 11 3.2.2. Método “AdicionaAtualizaContatos” 12 3.2.3. Método “AdicionaBlackList” 13 3.2.4. Método “AdicionaBlackListPorEmail” 13 3.2.5. Método “CancelarEnvio” 14 3.2.6. Método “CriarNovaCampanha” 14 3.2.7. Método “CriarNovaLista” 15 3.2.8. Método “CriarNovoEnvio” 15 3.2.9. Método “EncaminharEnvio” 17 3.2.10. Método “ImportaContatos” 18 3.2.11. Método “RemoveArquivos” 19 3.2.12. Método “RemoveContato” 20 3.2.13. Método “RemoveLista” 20 3.2.14. Método “RemoveSuspensao” 21 3.2.15. Método “RetornaArquivos” 21 3.2.16. Método “RetornaCampos” 22 3.2.17. Método “RetornaCliques” 22 3.2.18. Método “RetornaContatosBlackList” 23 3.2.19. Método “RetornaDadosContato” 24 3.2.20. Método “RetornaDadosEnvio” 25 3.2.21. Método “RetornaDadosLista” 26 3.2.22. Método “RetornaEmailsBlackListEnvio” 27 3.2.23. Método “RetornaEmailsDevolvidos” 28 3.2.24. Método “RetornaEmailsEnvio” 29 3.2.25. Método “RetornaEnvios” 30 3.2.26. Método “RetornaEstatisticasDeEnvio” 31 3.2.27. Método “RetornaEstatisticasDeEnviosCampanha” 32 3.2.28. Método “RetornaHistoricoContato” 33 3.2.29. Método “RetornaListas” 34 3.2.30. Método “RetornaMotivosOptOut” 35 3.2.31. Método “RetornaQuantidadeListas” 35

(3)

3.2.32. Método “RetornaQuantidadeEnvios” 36 3.2.33. Método “RetornaRegrasDicionario” 36 3.2.34. Método “RetornaVisualizacoes” 37 3.2.35. Método “SuspendeContato” 38 3.2.36. Método “ConviteReativacaoBlackList” 38

4. Exemplos de Programação

39

4.1. Case 1 – Adicionar ou atualizar informações de um único contato 39 4.2. Case 2 – Adicionar ou atualizar informações através de uma lista de contatos 40

4.3. Case 3 – Importação de uma pilha de contatos 40

4.4. Case 4 – Retornar dados sobre um único contato 41

4.5. Case 5 – Criar novo envio 41

(4)

Web Service SOAP – Definições

Este manual é destinado àqueles que possuem conhecimentos em linguagem de programação para integração SOAP (Simple Object Access Protocol).

O que é SOAP?

SOAP é um protocolo para troca de informações estruturadas em uma plataforma descentralizada e distribuída, onde se baseia na Linguagem de Marcação Extensível (XML) para seu formato de mensagem e em outros protocolos da Camada de aplicação, mais notavelmente em Chamada de Procedimento Remoto (RPC) e Protocolo de Transferência de Hipertexto (HTTP) para negociação e transmissão de mensagens. Sua concepção é de simplicidade, tanto quanto da linguagem de programação como do modelo de objetos e do transporte além de independência de vendedor.

A plataforma Virtual Target dispõe da plataforma SOAP para integração com sistemas externos independentemente do banco de dados ou linguagem de programação utilizada.

Os serviços (operações, mensagens, parâmetros, etc.) são descritos usando a linguagem WSDL (Web Services Description Language) onde fica disponibilizada na web através de uma semântica XML, este providencia a documentação necessária para se chamar um sistema distribuído e o procedimento necessário para que esta comunicação se estabeleça.

Referências

SOAP

http://en.wikipedia.org/wiki/SOAP http://www.w3schools.com/soap/default.asp

XML

http://en.wikipedia.org/wiki/XML http://www.w3schools.com/xml/default.asp

WSDL

http://en.wikipedia.org/wiki/WSDL http://www.w3schools.com/wsdl/default.asp

(5)

Integração WebService com Plataforma

Virtual Target

Especificações da plataforma Virtual Target:

1.

Protocolo de comunicação SOAP

- A função exercida pela plataforma Virtual Target é de SOAPServer, portanto, é necessário que seja disponibilizado um serviço SOAPClient na sua linguagem de programação para fornecer os dados à plataforma. Requisições feitas por PHP 4 necessita da biblioteca NuSOAP (http://nusoap.sourceforge.net/ ).

2.

Usuário de Integração

– Criar um usuário de uso exclusivo para integração na conta em questão pelo administrador.

3.

Configurações na plataforma

– Lista e campos adicionais existente na plataforma Virtual Target a que estes contatos deverão ser sincronização.

4.

Método a ser chamado

– Indicação da função a ser utilizada;

5.

Parâmetro(s) a ser(em) enviado(s)

– Indicação das informações necessárias, utilizadas nos métodos;

Sincronização

Os contatos fornecidos pelo SOAPClient serão analisados pelo SOAPServer a fim de definir, comparando o campo e-mail, se o contato deve ser adicionado ou atualizado na base de dados da plataforma Virtual Target.

A ligação entre os dados cadastrais de contatos fornecidos pelo SOAPClient e analisados pelo SOAPServer está nas TAGs de campos adicionais (incluindo @NOME, @EMAIL, @NASCIMENTO e @CELULAR que são estáticos) configurados na plataforma Virtual Target de forma que não deve-se utilizar o sinal @.

Limitações

A sincronização é realizada atendendo as orientações por parte da área técnica responsável pela plataforma Virtual Target.

Para obter maior performance recomendamos que somente os novos registros e os que foram atualizados nas últimas 24 horas sejam fornecidos.

(6)

Usuário de Integração

A plataforma SOAP é muito útil para agregar recursos às Intranets, Extranets, Websites e até mesmo sistemas para Windows, proporcionando a troca de dados em tempo real. Um bom exemplo é a integração do Virtual Target com um CRM para leitura de histórico de relacionamento.

Para utilizar o webservice, o administrador da conta será o responsável pela criação ou determinação de um usuário para integração, pois por medida de segurança, o “Usuário de Integração” utilizará seu próprio login e senha para efetuar a manipulação. Caso a senha seja trocada na plataforma Virtual Target, a mesma deverá ser atualizada na programação feita pelo cliente.

Para indicar o “Usuário de Integração”, deve-se acessar a plataforma, acessar o menu “Usuário” localizado no topo do site, escolher se designará um usuário novo ou selecionar um pré-existente. Em seguida selecione aba “Dados Gerais”, marque a opção de “Usuário de Integração” e clique no botão “gravar mudanças”. Veja a imagem a seguir:

Identificação de Lista de Contatos

Para identificar o “ID” de uma ou mais listas de contatos existem duas formas:

1. WebService

Através de uma requisição SOAP com o usuário de integração, utilize o método “RetornaListas” para obter o resultado XML com a relação de todas as listas cadastradas e seus dados como: nome, descrição e data de criação.

2. Plataforma Virtual Target

Visualmente através da plataforma Virtual Target, acesse o menu superior “Listas” e em seguida a sessão “Cadastro de Listas”. Cada lista possui em seus links o parâmetro de identificação “ID”.

(7)

URL: http://painel2.virtualtarget.com.br/index.dma/ContatosGrupos?act=edit&id=503

Definição dos métodos WSDL

A definição dos métodos se localiza no seguinte endereço: http://webservices2.virtualtarget.com.br/index.php?wsdl

Neste mesmo endereço, é possível listar todas as funcionalidades existentes via navegador. Ao clicar no nome do método, uma caixa de informação se abrirá descrevendo todas as informações pertinentes para sua execução. Logo mais, descreveremos os métodos, os tipos de dados e suas particularidades de como se utilizar.

Dica: Para validar uma requisição XML via SOAP, pode-se utilizar o programa SOAPUI (versão gratuita para download) localizada nos endereços http://www.soapui.org ou http://smartbear.com. Através deste programa, requisições são efetuadas em tempo real e irreversível.

(8)

Métodos

Atualmente, esta é a relação de métodos disponíveis para uso de integração webservice SOAP. Cada método possui particularidades que podem ser observadas pelo link da biblioteca WSDL.

AdicionaAtualizaContato RemoveLista RetornaEnvios

AdicionaAtualizaContatos RemoveSuspensao RetornaEstatisticasDeEnvio

AdicionaBlackList RetornaArquivos RetornaEstatisticasDeEnviosCampanha

AdicionaBlackListPorEmail RetornaCampos RetornaHistoricoContato

CancelarEnvio RetornaCliques RetornaListas

CriaNovaCampanha RetornaContatosBlackList RetornaMotivosOptOut

CriaNovaLista RetornaDadosContato RetornaQualidadeListas

CriaNovoEnvio RetornaDadosEnvio RetornaQuantidadeEnvios

EncaminharEnvio RetornaDadosLista RetornaRegrasDicionario

ImportaContatos RetornaEmailsBlackListEnvio RetornaVisualizacoes

RemoveArquivos RetornaEmailsDevolvidos SuspendeContato

RemoveContato RetornaEmailsEnvio ConviteReativacaoBlackList

Assuntos co-relacionados

Configurações

• RetornaCampos: campos adicionais existentes na plataforma para uso de personalização ou cadastramento de dados dos contatos;

• RetornaRegrasDicionario: regras para validação via expressão regular sobre a sintaxe dos domínios de e-mails

(9)

Contatos

• AdicionaAtualizaContato: até 30 requisições – 1 contatos por requisição;

• AdicionaAtualizaContatos: até 50 contatos por requisição com limite de 5 requisições simultâneas. Validar o parâmetro “manter” para adicionar contatos em outras listas ou alterar indicação das listas;

• AdicionaBlackList: adiciona contato em blacklist como optout, informando os motivos;

• AdicionaBlackListPorEmail: adiciona o e-mail do contato diretamente em blacklist sem motivo; • RetornaDadosContato: retorna todos os dados relacionado a 1 contato. Dados de listas vem por

ID e status como ativo, erro permanente e afins; • RemoveContato: exclui contato da plataforma;

• RemoveSuspensao: reativa o contato para utilização em envios.

• ConviteReativacaoBlackList: Solicita ao contato com status de blacklist a reativação de seu cadastro.

Arquivos

• ImportaContatos: utilização de arquivo CSV importado previamente na plataforma para cadastrar/atualizar mais de 500 contatos, associando informações de listas e campos adicionais do arquivo e da plataforma;

• RetornaArquivos: informa todos os arquivos existentes na sessão de upload de arquivos; • RemoveArquivos: exclui arquivos da sessão de upload de arquivos.

Listas

• CriaNovaLista: cadastra uma nova lista na qual poderá receber novos contatos através dos métodos relacionados a contatos;

• RetornaListas: retorna todas as listas e suas informações (ID, nome, descrição, data de criação); • RetornaDadosLista: retorna informações sobre uma lista especificada pelo ID (nome, descrição,

status e data de criação);

• RemoveLista: exclui lista, mas mantém os contatos na plataforma, caso ele não possua ne nenhuma associação de lista, o valor ficará nulo;

Campanhas

• CriaNovaCampanha: organizar os tipos de envios por “categorias” para retornar os envios de forma classificada;

(10)

Envio

• CriaNovoEnvio: estipula um novo envio com todos os parâmetros necessários e executa diretamente. Caso não possua créditos suficientes, o envio não ocorre;

• CancelarEnvio: barra o processamento do envio no status atual, o que foi efetuado não tem retorno;

• EncaminharEnvio: reenvia um disparo para um único remetente;

Relatório

• RetornaDadosEnvio: retorna todos os dados gerais e o template do envio; • RetornaCliques: retorna dados de cliques de um envio específico;

• RetornaContatosBlackList: retorna todos os contatos existentes na base que solicitaram opt-out; • RetornaEmailsBlackListEnvio: retorna contatos que solicitaram opt-out de um envio específico; • RetornaEmailsDevolvidos: Retorna os e-mails devolvidos de um determinado envio;

• RetornaEmailsEnvio: Retorna e-mails utilizados em um determinado envio;

• RetornaEnvios: Retorna dados de envio de uma determinada campanha. Se o ID da campanha for 0 (zero), irá retornar todos os envios;

• RetornaEstatisticasDeEnvio: Retorna informações estatísticas sobre o envio concluído;

Especificação dos Métodos

Cada método tem suas particularidades, por conta disto, vamos descrever de forma analítica as informações de cada um deles e em seguida um exemplo de como deverá ser composto a execução do seu código de programação (ASP, PHP, C++, C#, dentre outros) para XML.

Observação1: A plataforma possui por padrão o campo “Email” como chave primária. Este campo não permite duplicidade, portanto quaisquer indicações do mesmo além dos campos adicionais propiciarão atualização do mesmo.

Caso necessário, a chave primária poderá ser alterada mediante solicitação via HelpDesk junto a equipe de atendimento, porém sua alteração ocorrerá após validação prévia dos dados. Caso utilize um campo adicional como chave primária, o mesmo deverá ser referenciado sempre para manter a integridade das informações.

Observação2: Exemplos XML para requisição SOAP se encontram a parte deste manual para auxiliar em desenvolvimento de rotinas independente de sua linguagem de programação. Alguns casos possuem códigos na linguagem PHP para os métodos mais utilizados.

(11)

Método “AdicionaAtualizaContato”

Objetivo: Adiciona e/ou atualiza os dados cadastrais de um único contato.

Parâmetros Tipo Fluxo Descrição

login String

Request

Login do usuário de integração

senha String Senha do usuário de integração

email String E-mail do contato a ser adicionado/atualizado

nome String Nome do contato a ser adicionado/atualizado

nascimento String Data de nascimento no formato 99/99/9999 (dia/mês/ano)

celular Integer Número de celular sem formatação, apenas números 9999999999999 (DDI + DDD + Número)

listas Array Listas para adicionar o contato (obrigatório)

˪ listaid Integer ID da lista

camposadicionais Array Lista dos campos adicionais já existentes na conta

˪ tag String Nome do campo adicional e/ou Chave primária da plataforma

˪ valor String Valor a ser atribuído ao campo adicional

(12)

Método “AdicionaAtualizaContatos”

Objetivo: Adiciona e/ou atualiza dados cadastrais de vários contatos simultaneamente. Limite de 15 contatos por requisição.

login String

Request

contatos Array Lista com todas as informações pertinentes aos contatos

˪

manterLista Bool

Se verdadeiro, a informação de listas pré-existentes

permanecerão, caso contrário, será substituída pelas informações declaradas no parâmetro “listas”

listas Array Relação de listas (informação obrigatória)

˪ listaid Integer Indicação de IDs existentes na plataforma

campos Array Relação de campos adicionais (campos pré-existentes na plataforma)

˪ tag String

Nome do campo adicional e/ou Chave primária da plataforma. Tag E-MAIL e chave primária (caso não seja o e-mail) são obrigatórios para cada contato.

˪ valor String Valor a ser atribuído ao campo adicional

(13)

Método “AdicionaBlackList”

Objetivo: Adiciona um contato a Blacklist, informando o id do contato, id do envio e os motivos de solicitação.

login String

Request

contatoId Integer ID do contato

envioId Integer Número do envio relacionado a inclusão na BlackList

motivos Array Relação de motivos para inclusão

˪ descricao Integer Descrição do(s) motivo(s)

- Bool Response Resposta da requisição executada

Método “AdicionaBlackListPorEmail”

Objetivo: Adiciona um e-mail diretamente ao BlackList, sem informar os motivos do opt-out.

login String

Request

email String E-mail do contato

(14)

Método “CancelarEnvio”

Objetivo: Cancela a execução do envio requisitado.

login String

Request

envioId Integer Número (ID) do envio requisitado

- Bool Response Resposta da requisição executada

Método “CriaNovaCampanha”

Objetivo: Criar uma nova campanha para classificar os envios em forma de agrupamentos.

login String

Request

nome String Nome da campanha

descricao String Descrição da campanha

(15)

Método “CriaNovaLista”

Objetivo: Criar uma nova lista para classificar os contatos em forma de agrupamentos.

login String

Request

nome String Nome da lista

descricao String Descrição da lista

- Integer Response Retorna o ID da lista requisitada

Método “CriaNovoEnvio”

Objetivo: Elabora uma requisição de envio real utilizando todas as informações pertinentes, da mesma forma que é feito visualmente via plataforma.

login String

Request

campanhaId Integer Código da campanha a ser associada ao envio

rementente_nome String Nome do remetente

rementente_email String E-mail do remetente

(16)

assunto String Assunto da mensagem

mensagem String

Informe a mensagem HTML ou utilize comando basic @CMD_INCLUDE (ID). Comando para utilizar um

template pré-cadastrado na sessão de template usando o ID como referência

datahora_programada String Data programada com formatação dd/mm/aaaaa hh:ii

notificacao_email String Notificação de conclusão através de e-mail de contato

notificacao_sms String Notificação de conclusão através de mensagem SMS para um número de celular

filtro Array Relação de filtros. Por definição, os filtros ocorrem com _{parâmetros “seja igual a” e parênteses “OU”}

˪ id Integer Indicação do ID da lista de contatos

˪ campo Integer Indicação dos campos adicionais

˪ valores Array Relação de valores

˪ String Textos para comparação

- Array

Response

Resposta da requisição executada

˪ codigo Integer Código ID do envio criado

˪ total Integer Total de contatos ativos utilizados no envio

(17)

Método “EncaminharEnvio”

Objetivo: Efetua requisição de envio real reutilizando um envio já existente.

login String

Request

envioId Integer Código do envio original a ser utilizado

campanhaId Integer Código da campanha a ser associada ao envio

rementente_nome String Nome do remetente

rementente_email String E-mail do remetente

rementente_reply String E-mail de resposta

assunto String Assunto da mensagem

mensagemAdicional String Esta mensagem será colocada automaticamente acima da mensagem original

datahora_programada String Data programada com formatação dd/mm/aaaaa hh:ii

notificacao_email String Notificação de conclusão através de e-mail de contato

notificacao_sms String Notificação de conclusão através de mensagem SMS para um número de celular

filtro Array Relação de filtros. Por definição, os filtros ocorrem com _{parâmetros “seja igual a” e parênteses “OU”}

˪ id Integer Indicação do ID da lista de contatos

(18)

˪ String Textos para comparação

- Array

Response

Resposta da requisição executada

˪ codigo Integer Código ID do envio criado

˪ total Integer Total de contatos ativos utilizados no envio

˪ total_inativos Integer Total de contatos inativos utilizados no envio

Método “ImportaContatos”

Objetivo: Adiciona e/ou atualiza dados cadastrais para uma pilha de contatos.

login String

Request

listaId Integer Código da lista para associação

nomeArquivo String Nome do arquivo CSV contido dentro do arquivo ZIP

dadosArquivo String Arquivo ZIP criptografado em base 64 com até 5mb

colunas Array Lista de informações

˪ campo String Nome do campo para associação

˪ coluna String Posicionamento referenciado por tabulação do arquivo,

(19)

incluirNovosContatos Bool Indicação para inclusão ou não de contatos que não constam na plataforma Virtual Target

atualizarExistentes Bool Indicação para atualização de dados cadastrais para contatos já existentes na plataforma Virtual Target

chavePrimaria String

Indicação da chave primária de sua base de contatos. Por definição, o campo EMAIL é a chave primária da plataforma, mas caso sua conta possui outro campo, o nome do mesmo deverá ser indicado

- Bool Response Resposta da requisição executada

Observação1: O arquivo zip deverá ser encodado (criptografado) em base 64 e com limite de até 5mb. Observação2: A confirmação desta requisição indica apenas que o arquivo foi disponibilizado dentro da plataforma e que o processo de importação foi iniciado. Não é uma confirmação de término da rotina. Para tanto, utilize o método “RetornaDadosLista” para checar o status da lista de contatos, onde se indicado como: “Disponível”, “Importando Contatos” e “Excluindo Contatos”.

Observação3: O arquivo indicado no parâmetro “nomeArquivo” deve ser o nome do próprio arquivo CSV contido dentro do zip e o mesmo deverá ser único, não poderá já existir na plataforma Virtual Target. Iniciada a rotina, o mesmo ficará disponível no menu “Listas”, na sessão “Upload de Arquivos”.

Método “RemoveArquivos”

Objetivo: Exclusão de arquivos indicados, arquivos que constam na sessão de “Upload de Arquivos”.

login String

Request

arquivos Array Requisição de arquivos

˪ nome String Nome dos arquivos para exclusão, escrito da mesma forma

que constam na plataforma

(20)

Método “RemoveContato”

Objetivo: Exclusão do contato indicado.

login String

Request

email String Requisição de arquivos

Método “RemoveLista”

Objetivo: Exclusão do contato indicado.

login String

Request

listaId Integer ID da lista a ser excluida

(21)

Método “RemoveSuspensao”

Objetivo: Remove a suspensão de um determinado contato.

login String

Request

email String E-mail do contato a ser reativado

Método “RetornaArquivos”

Objetivo: Remove a suspensão de um determinado contato.

login String

Request

- Array

Response

Retorna lista com todos os arquivos encontrados

˪ nome Bool Nome do arquivo

˪ tamanho_bytes Array Tamanho em bytes do arquivo

(22)

Método “RetornaCampos”

Objetivo: Retorna informações dos campos padrões e adicionais existentes na plataforma.

login String

Request

- Array

Response

Retorna lista com todos os campos encontrados

˪ descricao String Descrição do campo

˪ tag String Nome do campo (tag)

Método “RetornaCliques”

Objetivo: Retorna informações sobre cliques realizados em um determinado envio.

login String

Request

envioId Integer Código do envio

porPagina Integer Quantidade de registros por página

- Array

Response

Retorna lista com dados diversos

(23)

˪ email String E-mail do contato que efetuou a ação

˪ IP String IP do contato que efetuou a ação

˪ descricao String Valor do campo descritivo existente na validação de URL

˪ url String Endereço de URL

Método “RetornaContatosBlackList”

Objetivo: Retorna todos os contatos que estão solicitaram alteração para BlackList em um período pré-determinado.

login String

Request

data_de String Data no formato dd/mm/aaaa

data_ate String Data no formato dd/mm/aaaa

- Array

Response

˪ codigo String Código (ID) de identificação do contato

˪ email String E-mail do contato que efetuou a ação

˪ nome String IP do contato que efetuou a ação

˪ celular String Número de celular do contato

(24)

˪ campoX String Campo adicional X (1 a 60) do cadastro do contato

˪ datahoraBlackList String Data de cadastro no formato dd/mm/aaaa

Método “RetornaDadosContato”

Objetivo: Retorna dados cadastrais de um determinado contato, inclusive os campos adicionais.

login String

Request

- Array

Response

˪ codigo Integer Código (ID) de identificação do contato

˪ dados Array Lista de campos adicionais já existentes

˪ tag String Nome do campo adicional em maiúscula, exceto o campo _{“status” (informação como ativo,blacklist,reporte spam...)}

˪ valor String Valor atribuído ao campo adicional

˪ listas Array Relação de listas ao qual o contato pertence

(25)

Método “RetornaDadosEnvio”

Objetivo: Retorna dados gerais de um determinado envio.

login String

Request

envioId Integer Código (ID) do envio

- Array

Response

˪ campanhaId Integer Código (ID) de identificação do contato

˪ remetente_nome String Nome do remetente

˪ remetente_email String E-mail do remetente

˪ remetente_replay String E-mail de resposta

˪ assunto String Assunto da mensagem

˪ html String Código HTML da mensagem

˪ datahora_programada String Data e hora programada do envio no formato

(26)

Método “RetornaDadosLista”

Objetivo: Retorna dados de uma lista determinada pelo seu ID contendo os seguintes dados: nome, descrição, status e data de criação.

login String

Request

listaId Integer Código (ID) da lista de contatos

- Array

Response

˪ nome Integer Nome da lista

˪ descricao String Descrição da lista

˪ status String Status da lista (Opções: Disponível,

Importando contatos e Excluindo contatos)

˪ datahora String Data e hora de criação da lista no formato

(27)

Método “RetornaEmailsBlackListEnvio”

Objetivo: Retorna os contatos que fizeram opt-out em um determinado envio.

login String

Request

porPagina Integer Quantidade de registros de amostra por página

pagina Integer Número da pagina para a pesquisa

- Array

Response

˪ codigo Integer Código (ID) do contato

˪ email String E-mail do contato

˪ datahora_blacklist String Data e hora da solicitação de opt-out no

formato dd/mm/aaaa hh:ii

˪ motivos String Lista de motivos

(28)

Método “RetornaEmailsDevolvidos”

Objetivo: Retorna e-mails de determinado envio que foram devolvidos pelo servidor do cliente.

login String

Request

pagina Integer Número da página para a pesquisa

- Array

Response

˪ datahora String Data e hora da solicitação de opt-out no

(29)

Método “RetornaEmailsEnvio”

Objetivo: Retorna e-mails de determinado envio que foram devolvidos pelo servidor do cliente.

login String

Request

retornaEntregues Bool

True - retorna os e-mails com sucesso de

entrega

False - retorna os e-mails com erros de

entrega

- Array

Response

˪ codigo String Código (ID) do envio

˪ status_codigo Integer Código do status

˪ status_descricao String Descrição do status

˪ datahora String Data e hora do envio ou retorno de erro no

˪ chaveprimaria String Indicação da chave primária estipulada na

(30)

Método “RetornaEnvios”

Objetivo: Retorna dados de um envio indicado.

login String

Request

campanhaId Integer Código (ID) da campanha associada

- Array

Response

˪ codigo Integer Código (ID) do envio

˪ campanhaId Integer Código (ID) da campanha

˪ remetente_nome String Nome do remetente

˪ remetente_email String E-mail do remetente

˪ remetente_reply String E-mail de resposta

˪ html String Código HTML da mensagem

˪ datahora_programada String Data e hora programada no formato

dd/mm/aaaa hh:ii

Observação: Se o código (ID) da campanha for 0 (zero), serão retornados dados de todos os envios. Caso contrário, serão retornados todos os envios associados ao código informado.

(31)

Método “RetornaEstatisticasDeEnvio”

Objetivo: Retorna dados de um envio indicado.

login String

Request

- Array

Response

˪ status_codigo String Status de classificação: "1" = em edição "2" = aguardando "3" = aguardando aprovação "4" = aprovado "5" = pausado "6" = cancelado "7" = processando "8" = concluído "9" = bloqueado "10" = transacional

˪ quantidade_total Integer Quantidade total de contatos

˪ recebidos Integer Quantidade de contatos que receberam o

envio

˪ processados Integer Quantidade de e-mails processados

˪ duracao String Duração do envio no formato hh:ii:ss

˪ quantidade_conexoes Integer Quantidade de conexões para realizar o

(32)

˪ quantidade_optout Integer Quantidade de solicitações de opt-out

˪ visualizados Integer Quantidade de contatos únicos que

visualizaram o envio

˪ visualizados_total Integer Quantidade total de visualizações

˪ clicados Integer Quantidade de cliques únicos

˪ clicados_total Integer Quantidade total de cliques

Método “RetornaEstatisticasDeEnviosCampanha”

Objetivo: Retorna a estatística de envios associados a uma determinada campanha.

login String

Request

campanhaId Integer Código (ID) da campanha

- Array

Response

˪ quantidade_total Integer Quantidade total de contatos

˪ recebidos Integer Quantidade de contatos que receberam o

envio

(33)

˪ duracao String Duração do envio no formato hh:ii:ss

˪ quantidade_conexoes Integer Quantidade de conexões para realizar o

envio

˪ quantidade_optout Integer Quantidade de solicitações de opt-out

˪ visualizados Integer Quantidade de contatos únicos que

visualizaram o envio

˪ visualizados_total Integer Quantidade total de visualizações

˪ clicados Integer Quantidade de cliques únicos

˪ clicados_total Integer Quantidade total de cliques

Método “RetornaHistoricoContato”

Objetivo: Retorna o histórico de interações de um determinado contato.

login String

Request

contatoEmail String E-mail do contato

- Array

Response

˪ datahora Integer Data e hora da interação no formato

dd/mm/aaaa hh:ii

˪ envEnvios_codigo String Código do envio

(34)

˪ ocorrencia Integer Ocorrência

˪ assunto Integer Assunto da mensagem

Método “RetornaListas”

Objetivo: Retorna relação de listas cadastradas (com excessão da lista de testes), contendo suas informações cadastrais: ID, nome, descrição e data de criação.

login String

Request

- Array

Response

˪ codigo Integer Código (ID) da lista

˪ nome String Nome da lista

˪ descricao Integer Descrição da lista

˪ datahora Integer Data e hora da criação no formato

(35)

Método “RetornaMotivosOptOut”

Objetivo: Retorna os motivos de opt-out configurados pelo cliente na plataforma.

login String

Request

- Array

Response

˪ codigo Integer Código do motivo

˪ descricao String Descrição do motivo

Método “RetornaQuantidadeListas”

Objetivo: Retorna quantidade de contatos por status.

login String

Request

- Array

Response

˪ total Integer Quantidade de contatos

(36)

Método “RetornaQuantidadeEnvios”

Objetivo: Retorna quantidade total de envios.

login String

Request

- Integer Response Retorna total de envios

Método “RetornaRegrasDicionario”

Objetivo: Retorna as expressões regulares para validação de domínios.

login String

Request

- Array

Response

˪ regra String

Expressão regular para validação do domínio. Se aplicada, o retorno verdadeiro deve considerar a necessidade de correção, caso falso, o domínio é válido.

˪ dominio String Domínio com sintaxe correta correspondente

(37)

Método “RetornaVisualizacoes”

Objetivo: Retorna as visualizações realizadas de um determinado envio por cada contato.

login String

Request

porPagina Integer Quantidade de registros por página (máximo de 200 registros)

pagina Integer Indicação da página a ser pesquisada

- Array

Response

˪ datahora String Data e hora da visualização no formato

dd/mm/aaaa hh:ii

˪ ip String IP do contato

˪ chaveprimaria String Indicação da chave primária estipulada na

(38)

Método “SuspendeContato”

Objetivo: Suspende o contato informado por um determinado período contabilizado em dias a partir da data atual.

login String

Request

dias Integer Quantidade em dias para suspensão

Método “ConviteReativacaoBlackList”

Objetivo: Reativação do contato de BlackList.

login String

Request

emailContato String E-mail do contato

nomeRemetente String Nome do remetente da solicitação

emailRemetente String E-mail do remetente da solicitação

(39)

Observação: Limitação diária de 50 convites. Feito um convite a um contato, um novo convite poderá ser feito apenas após 7 dias da data de solicitação.

Exemplos de Programação

Junto com este manual, exemplos codificados em XML e php ajudarão no entendimento da elaboração de rotinas em sua linguagem de programação. A seguir, cases dos principais métodos utilizados para manipulação via webservice.

Cada campo de requisição possui uma especificação de tipo que pode ser: texto/alfanumérico (string), números (integer), vetor (array) e “verdadeiro/falso” (boleanos). Nestes casos, deve-se respeitar a determinação indicada na biblioteca WSDL, pois sua interpretação determinará o tipo de retorno (informações requisitadas) ou mensagens de erro (erros de parse ou com resposta false/0). Tome cuidado com espaços entre os valores. No caso de login e senha, poderá ocorrer erro de autenticação. Toda requisição possui um tipo de resposta, que pode ser tanto positivo (true), como negativo (false) ou um conjunto de informações conforme indicado método e explanado anteriormente. Todos os métodos possuem a mesma introdução, modificando apenas a função conforme a necessidade.

Case 1 – Adicionar e/ou atualizar informações de um único contato

O método “AdicionaAtualizaContato” tem o intuito de adicionar e/ou atualizar informações de um único contato através da integração webservice de forma esporádica, pontual.

Será requisitado para que o contato (email – chave primária que não se repete) pertença a uma ou mais listas de contatos e que também possua suas informações adicionais cadastradas em seus respectivos campos adicionais. A informação de Lista alterará a associação pré-existente. No caso do contato pertencer a mais de uma lista e sua indicação na requisição for de apenas uma, o mesmo será desassociado as listas anteriores e associado ao código informado.

Observação 1: Para inserir informações em campos adicionais, os mesmos já deverão existir na plataforma, caso contrário uma mensagem de erro ou false será retornada. O mesmo para campos de chave primária.

Observação 2: A quantidade de requisição deste método interfere diretamente no processamento do mesmo. Execute até 15 requisições por minuto no máximo. Caso deseje cadastrar mais contatos, utilize outros métodos como “AdicionaAtualizaContatos” ou “importaContatos”.

(40)

Observação 3: Tanto este método com em outros que executam a função de cadastramento de contatos, o status dos contatos pré-existentes não se alteram, seja ele um opt-out (blacklist), um erro permanente (hardbounce) ou qualquer outro status que não seja como ativo.

Case 2

– Adicionar e/ou atualizar informações de uma lista de

contatos

O método “AdicionaAtualizaContatos” tem o intuito de adicionar e/ou atualizar informações de uma lista de contatos. Em uma requisição apenas, é possível cadastrar e/ou atualizar até 15 contatos com seus devidos campos adicionais.

Além de ser uma boa prática, agiliza o tempo de execução e minimiza a demanda de processamento que possa prejudicar o desempenho e gerar lentidão no webservice.

Caso a opção “manterlista” não estiver marcada como verdadeiro, a nova informação de lista substituirá os dados pré-existentes ao invés de acrescentá-los.

Se executado com sucesso todos os contatos, um retorno verdadeiro (true) será passado. Caso contrário, uma excessão será informada com a indicação do problema. Normalmente o problema se restringe a sintaxe do e-mail.

Observação: Lembrando que para inserir informações em campos adicionais, os mesmos já deverão existir na plataforma, caso contrário uma mensagem de erro ou false será retornada. O mesmo para campos de chave primária.

Case 3 – Importação de Contatos

O método “ImportaContatos” tem o intuito de adicionar e/ou atualizar informações de uma pilha de registros, através de um arquivo do tipo CSV, onde será compactado no formato ZIP de até 5mb e encodado (criptografado) como base 64. Este método completa as funções dos cases anteriores em apenas uma requisição. Indicado para carregamento de grande quantidade de contatos.

A indicação dos campos serve para associar os campos adicionais da plataforma com as colunas existentes no arquivo CSV. Processo este feito pela indicação do nome do campo adicional em maiúscula e o posicionamento por números da coluna do arquivo CSV iniciado por 1.

Observação 1: Arquivo ZIP não poderá ultrapassar a capacidade de 5mb. Observação 2: Arquivo ZIP deverá ser criptografado apenas como base 64.

Observação 3: A associação de campos adicionais e colunas deverá ocorrer de forma precisa, pois o erro de posicionamento gerará uma lista sem contatos cadastrados/atualizados.

Observação 4: No processo de importação, o retorno via webservice é verdadeiro (true), porém neste mesmo instante uma rotina interna a plataforma foi iniciada para captação das informações. Para checar o processo de importação, utilize o método “RetornaDadosLista” onde o campo status indica o status real da importação da lista indicada. Se for necessário, utilize em sua rotina esta validação para que em sua conclusão possa executar outros métodos como “CriaNovoEnvio” para efetuar um disparo utilizando esta lista como base de contatos.

(41)

Case 4 – Retornar dados e status de um único contato

Para obter informações de um contato em específico, recomenda-se usar o método “RetornaDadosContato”. Este método tem como retorno todas as informações pertinentes ao contato e seus campos adicionais, como também seu status e em que lista se encontra através de sua identificação pelo campo principal de “e-mail”.

Observação: Evite efetuar múltiplas requisições via webservice pois, além de ser uma boa prática, agiliza o tempo de execução e minimiza a demanda de processamento que possa prejudicar o desempenho e gerar lentidão no webservice.

Case 5 – Criar novo envio

Para efetuar um envio dinamicamente, um com junto de informações deverão constar na programação quando chamado o método “CriarNovoEnvio”.

Observação 1: Quando executado este método, uma validação sobre os filtros de segmentação ocorrerá. Caso não se encontre contatos ativos, o envios ficará com o status de “em edição” e o retorno será que foi retornado 0 (zero) contatos para este envio.

Observação 2: O envio não será executado caso não haja créditos em sua conta, pois sua execução é imediata (disparo no mesmo momento e/ou programada).

Case 6 – Convite de Reativação de contato de BlackList

Método que solicita ao contato bloqueado a oportunidade de sua reativação por meio de sua intervenção manual, optando pela confirmação ou não do mesmo.

Observação: Quando executado, um e-mail será encaminhado ao e-mail do contato. Os dados de nome e email de remetente deverão ser verídicos para a execução pela plataforma e o recebimento correto pelo provedor do cliente, na qual valida o tráfego dos e-mails pelas boas práticas de e-mail marketing (certificações/autenticações – SPF dentre outros).

(42)

Rua Bandeira Paulista, 275 - 12º andar

04532-010 São Paulo SP Brasil

Fale com a gente

+55 11 3708-4000 contato@virtualtarget.com.br

Descubra tudo sobre a Experian Virtual Target

virtualtarget.com.br

Acompanhe-nos no Facebook

facebook.com/ExperianVirtualTarget

Siga-nos no Twitter

twitter.com/virtualtarget

Experian Marketing Services

A Experian Marketing Services oferece ao mercado um portfólio de soluções completas para entendimento, prospecção, rentabilização e fidelização de clientes. Entre elas, as melhores práticas e ferramentas tecnológicas para marketing direto, marketing analítico e marketing digital.