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

Transcrição

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 Sincronização Limitações Usuário de Integração Identificação de Lista de Contatos Definição dos métodos WSDL 7 3. Métodos Assuntos co-relacionados Especificação dos Métodos Método AdicionaAtualizaContato Método AdicionaAtualizaContatos Método AdicionaBlackList Método AdicionaBlackListPor Método CancelarEnvio Método CriarNovaCampanha Método CriarNovaLista Método CriarNovoEnvio Método EncaminharEnvio Método ImportaContatos Método RemoveArquivos Método RemoveContato Método RemoveLista Método RemoveSuspensao Método RetornaArquivos Método RetornaCampos Método RetornaCliques Método RetornaContatosBlackList Método RetornaDadosContato Método RetornaDadosEnvio Método RetornaDadosLista Método Retorna sBlackListEnvio Método Retorna sDevolvidos Método Retorna sEnvio Método RetornaEnvios Método RetornaEstatisticasDeEnvio Método RetornaEstatisticasDeEnviosCampanha Método RetornaHistoricoContato Método RetornaListas Método RetornaMotivosOptOut Método RetornaQuantidadeListas 35

3 Método RetornaQuantidadeEnvios Método RetornaRegrasDicionario Método RetornaVisualizacoes Método SuspendeContato Método ConviteReativacaoBlackList Exemplos de Programação Case 1 Adicionar ou atualizar informações de um único contato Case 2 Adicionar ou atualizar informações através de uma lista de contatos Case 3 Importação de uma pilha de contatos Case 4 Retornar dados sobre um único contato Case 5 Criar novo envio Case 6 ConviteReativacaoBlackList 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 XML WSDL

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 ( ). 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 , 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 @NASCIMENTO que são estáticos) configurados na plataforma Virtual Target de forma que não deve-se utilizar o 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 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: Definição dos métodos WSDL A definição dos métodos se localiza no seguinte endereço: 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 ou 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 AdicionaBlackListPor RetornaCampos RetornaHistoricoContato CancelarEnvio RetornaCliques RetornaListas CriaNovaCampanha RetornaContatosBlackList RetornaMotivosOptOut CriaNovaLista RetornaDadosContato RetornaQualidadeListas CriaNovoEnvio RetornaDadosEnvio RetornaQuantidadeEnvios EncaminharEnvio RetornaDadosLista RetornaRegrasDicionario ImportaContatos Retorna sBlackListEnvio RetornaVisualizacoes RemoveArquivos Retorna sDevolvidos SuspendeContato RemoveContato Retorna sEnvio 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 s

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; AdicionaBlackListPor adiciona o 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; Retorna sBlackListEnvio: retorna contatos que solicitaram opt-out de um envio específico; Retorna sDevolvidos: Retorna os s devolvidos de um determinado envio; Retorna sEnvio: Retorna s 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 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. senha Senha do usuário de integração do contato a ser adicionado/atualizado nome Nome do contato a ser adicionado/atualizado nascimento Data de nascimento no formato 99/99/9999 (dia/mês/ano) celular Integer Request Número de celular sem formatação, apenas números (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 Nome do campo adicional e/ou Chave primária da plataforma valor Valor a ser atribuído ao campo adicional - Bool Response Resposta da requisição executada

12 Método AdicionaAtualizaContatos Objetivo: Adiciona e/ou atualiza dados cadastrais de vários contatos simultaneamente. Limite de 15 contatos por requisição. senha Senha do usuário de integração 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 Request Relação de listas (informação obrigatória) listaid Integer Indicação de IDs existentes na plataforma campos tag Array Relação de campos adicionais (campos pré-existentes na plataforma) Nome do campo adicional e/ou Chave primária da plataforma. Tag e chave primária (caso não seja o ) são obrigatórios para cada contato. valor Valor a ser atribuído ao campo adicional - Bool Response Resposta da requisição executada

13 Método AdicionaBlackList Objetivo: Adiciona um contato a Blacklist, informando o id do contato, id do envio e os motivos de solicitação. senha Senha do usuário de integração contatoid Integer ID do contato Request 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 AdicionaBlackListPor Objetivo: Adiciona um diretamente ao BlackList, sem informar os motivos do opt-out. senha Request Senha do usuário de integração do contato - Bool Response Resposta da requisição executada

14 Método CancelarEnvio Objetivo: Cancela a execução do envio requisitado. senha Request Senha do usuário de integração 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. senha Senha do usuário de integração Request nome Nome da campanha descricao Descrição da campanha - Integer Response Retorna o ID da campanha requisitada

15 Método CriaNovaLista Objetivo: Criar uma nova lista para classificar os contatos em forma de agrupamentos. senha Senha do usuário de integração Request nome Nome da lista descricao 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. senha Senha do usuário de integração campanhaid Integer Código da campanha a ser associada ao envio Request rementente_nome Nome do remetente rementente_ do remetente rementente_reply de resposta

16 assunto Assunto da mensagem mensagem Informe a mensagem HTML ou utilize comando (ID). Comando para utilizar um template pré-cadastrado na sessão de template usando o ID como referência datahora_programada Data programada com formatação dd/mm/aaaaa hh:ii notificacao_ Notificação de conclusão através de de contato notificacao_sms filtro Array Notificação de conclusão através de mensagem SMS para um número de celular 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 Textos para comparação valores Array Relação de valores - Array Resposta da requisição executada codigo Integer Código ID do envio criado Response total Integer Total de contatos ativos utilizados no envio total_inativos Integer Total de contatos inativos utilizados no envio

17 Método EncaminharEnvio Objetivo: Efetua requisição de envio real reutilizando um envio já existente. senha Senha do usuário de integração envioid Integer Código do envio original a ser utilizado campanhaid Integer Código da campanha a ser associada ao envio rementente_nome Nome do remetente rementente_ do remetente rementente_reply de resposta assunto Request Assunto da mensagem mensagemadicional Esta mensagem será colocada automaticamente acima da mensagem original datahora_programada Data programada com formatação dd/mm/aaaaa hh:ii notificacao_ Notificação de conclusão através de de contato notificacao_sms filtro Array Notificação de conclusão através de mensagem SMS para um número de celular 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

18 valores Array Relação de valores Textos para comparação - Array Resposta da requisição executada codigo Integer Código ID do envio criado Response 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. senha Senha do usuário de integração listaid Integer Código da lista para associação nomearquivo Nome do arquivo CSV contido dentro do arquivo ZIP Request dadosarquivo Arquivo ZIP criptografado em base 64 com até 5mb colunas Array Lista de informações campo Nome do campo para associação coluna Posicionamento referenciado por tabulação do arquivo, iniciando pela numeração 1

19 incluirnovoscontatos atualizarexistentes chaveprimaria Bool Bool Indicação para inclusão ou não de contatos que não constam na plataforma Virtual Target Indicação para atualização de dados cadastrais para contatos já existentes na plataforma Virtual Target Indicação da chave primária de sua base de contatos. Por definição, o campo é 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. senha Senha do usuário de integração Request arquivos Array Requisição de arquivos nome Nome dos arquivos para exclusão, escrito da mesma forma que constam na plataforma - Bool Response Resposta da requisição executada

20 Método RemoveContato Objetivo: Exclusão do contato indicado. senha Request Senha do usuário de integração Requisição de arquivos - Bool Response Resposta da requisição executada Método RemoveLista Objetivo: Exclusão do contato indicado. senha Request Senha do usuário de integração listaid Integer ID da lista a ser excluida - Bool Response Resposta da requisição executada

21 Método RemoveSuspensao Objetivo: Remove a suspensão de um determinado contato. senha Request Senha do usuário de integração do contato a ser reativado - Bool Response Resposta da requisição executada Método RetornaArquivos Objetivo: Remove a suspensão de um determinado contato. Request senha Senha do usuário de integração - Array Retorna lista com todos os arquivos encontrados nome Bool Nome do arquivo Response tamanho_bytes Array Tamanho em bytes do arquivo datahora_modificacao Bool Data e hora de modificação do arquivo

22 Método RetornaCampos Objetivo: Retorna informações dos campos padrões e adicionais existentes na plataforma. Request senha Senha do usuário de integração - Array Retorna lista com todos os campos encontrados descricao Response Descrição do campo tag Nome do campo (tag) Método RetornaCliques Objetivo: Retorna informações sobre cliques realizados em um determinado envio. senha Senha do usuário de integração Request envioid Integer Código do envio porpagina Integer Quantidade de registros por página - Array Retorna lista com dados diversos Response datahora Data e hora do clique no formato dd/mm/aaaa hh:ii

23 do contato que efetuou a ação IP IP do contato que efetuou a ação descricao Valor do campo descritivo existente na validação de URL url 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. senha Senha do usuário de integração Request data_de Data no formato dd/mm/aaaa data_ate Data no formato dd/mm/aaaa - Array Retorna lista com dados diversos codigo Código (ID) de identificação do contato do contato que efetuou a ação Response nome IP do contato que efetuou a ação celular Número de celular do contato nascimento Data de nascimento do contato no formato dd/mm/aaaa

24 campox Campo adicional X (1 a 60) do cadastro do contato datahorablacklist Data de cadastro no formato dd/mm/aaaa Método RetornaDadosContato Objetivo: Retorna dados cadastrais de um determinado contato, inclusive os campos adicionais. senha Request Senha do usuário de integração do contato - Array Retorna lista com dados diversos codigo Integer Código (ID) de identificação do contato dados Array Lista de campos adicionais já existentes tag Response Nome do campo adicional em maiúscula, exceto o campo status (informação como ativo,blacklist,reporte spam...) valor Valor atribuído ao campo adicional listas Array Relação de listas ao qual o contato pertence listaid Integer ID da lista

25 Método RetornaDadosEnvio Objetivo: Retorna dados gerais de um determinado envio. senha Request Senha do usuário de integração envioid Integer Código (ID) do envio - Array Retorna lista com dados diversos campanhaid Integer Código (ID) de identificação do contato remetente_nome Nome do remetente remetente_ do remetente Response remetente_replay de resposta assunto Assunto da mensagem html Código HTML da mensagem datahora_programada Data e hora programada do envio no formato dd/mm/aaaa hh:ii

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. senha Request Senha do usuário de integração listaid Integer Código (ID) da lista de contatos - Array Retorna lista com dados diversos nome Integer Nome da lista descricao Response Descrição da lista status datahora Status da lista (Opções: Disponível, Importando contatos e Excluindo contatos) Data e hora de criação da lista no formato dd/mm/aaaa hh:ii

27 Método Retorna sBlackListEnvio Objetivo: Retorna os contatos que fizeram opt-out em um determinado envio. senha Senha do usuário de integração envioid Integer Request Código (ID) do envio porpagina Integer Quantidade de registros de amostra por página pagina Integer Número da pagina para a pesquisa - Array Retorna lista com dados diversos codigo Integer Código (ID) do contato do contato datahora_blacklist Response motivos Lista de motivos Data e hora da solicitação de opt-out no formato dd/mm/aaaa hh:ii Descrição dos motivos

28 Método Retorna sDevolvidos Objetivo: Retorna s de determinado envio que foram devolvidos pelo servidor do cliente. senha Senha do usuário de integração envioid Integer Request Código (ID) do envio porpagina Integer Quantidade de registros de amostra por página pagina Integer Número da página para a pesquisa - Array Retorna lista com dados diversos datahora Response Data e hora da solicitação de opt-out no formato dd/mm/aaaa hh:ii do contato

29 Método Retorna sEnvio Objetivo: Retorna s de determinado envio que foram devolvidos pelo servidor do cliente. senha Senha do usuário de integração envioid Integer Código (ID) do envio retornaentregues Bool Request True - retorna os s com sucesso de entrega False - retorna os s com erros de entrega porpagina Integer Quantidade de registros de amostra por página pagina Integer Número da página para a pesquisa - Array Retorna lista com dados diversos codigo Código (ID) do envio do contato status_codigo Integer Response Código do status status_descricao Descrição do status datahora chaveprimaria Data e hora do envio ou retorno de erro no formato dd/mm/aaaa hh:ii Indicação da chave primária estipulada na plataforma. Por padrão, o .

30 Método RetornaEnvios Objetivo: Retorna dados de um envio indicado. senha Senha do usuário de integração campanhaid Integer Request Código (ID) da campanha associada porpagina Integer Quantidade de registros de amostra por página pagina Integer Número da página para a pesquisa - Array Retorna lista com dados diversos codigo Integer Código (ID) do envio campanhaid Integer Código (ID) da campanha remetente_nome Nome do remetente remetente_ Response do remetente remetente_reply de resposta assunto Assunto da mensagem html Código HTML da mensagem datahora_programada 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. senha Request Senha do usuário de integração envioid Integer Código (ID) do envio - Array Retorna lista com dados diversos codigo Integer Código (ID) do envio assunto Assunto da mensagem Status de classificação: status_codigo Response "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 s processados duracao Duração do envio no formato hh:ii:ss quantidade_conexoes Integer Quantidade de conexões para realizar o envio

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. senha Request Senha do usuário de integração campanhaid Integer Código (ID) da campanha - Array Retorna lista com dados diversos codigo Integer Código (ID) do envio assunto Assunto da mensagem Response quantidade_total Integer Quantidade total de contatos recebidos Integer Quantidade de contatos que receberam o envio processados Integer Quantidade de s processados

33 duracao 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. senha Request Senha do usuário de integração contato do contato - Array Retorna lista com dados diversos datahora Integer Response envenvios_codigo Código do envio Data e hora da interação no formato dd/mm/aaaa hh:ii descricao Integer Descrição da ocorrência

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. Request senha Senha do usuário de integração - Array Retorna lista com dados diversos codigo Integer Código (ID) da lista nome Response Nome da lista descricao Integer Descrição da lista datahora Integer Data e hora da criação no formato dd/mm/aaaa hh:ii

35 Método RetornaMotivosOptOut Objetivo: Retorna os motivos de opt-out configurados pelo cliente na plataforma. Request senha Senha do usuário de integração - Array Retorna lista com dados diversos codigo Integer Response Código do motivo descricao Descrição do motivo Método RetornaQuantidadeListas Objetivo: Retorna quantidade de contatos por status. Request senha Senha do usuário de integração - Array Retorna lista com dados diversos total Integer Response Quantidade de contatos descricao Descrição da lista

36 Método RetornaQuantidadeEnvios Objetivo: Retorna quantidade total de envios. Request senha Senha do usuário de integração - Integer Response Retorna total de envios Método RetornaRegrasDicionario Objetivo: Retorna as expressões regulares para validação de domínios. Request senha Senha do usuário de integração - Array Retorna lista com dados diversos regra Response 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 Domínio com sintaxe correta correspondente ao teste da expressão regular

37 Método RetornaVisualizacoes Objetivo: Retorna as visualizações realizadas de um determinado envio por cada contato. senha Senha do usuário de integração envioid Integer Request Código (ID) do envio porpagina Integer Quantidade de registros por página (máximo de 200 registros) pagina Integer Indicação da página a ser pesquisada - Array Retorna lista com dados diversos datahora Data e hora da visualização no formato dd/mm/aaaa hh:ii Response do contato ip IP do contato chaveprimaria Indicação da chave primária estipulada na plataforma. Por padrão, o .

38 Método SuspendeContato Objetivo: Suspende o contato informado por um determinado período contabilizado em dias a partir da data atual. senha Senha do usuário de integração Request do contato dias Integer Quantidade em dias para suspensão - Bool Response Resposta da requisição executada Método ConviteReativacaoBlackList Objetivo: Reativação do contato de BlackList. senha Senha do usuário de integração contato do contato Request nomeremetente Nome do remetente da solicitação remetente do remetente da solicitação recebernotificacao Bool Confirmação do recebimento da notificação

39 - Bool Response Resposta da requisição executada 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 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 ( 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 . 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 . 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 será encaminhado ao do contato. Os dados de nome e 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 s pelas boas práticas de marketing (certificações/autenticações SPF dentre outros).

42 Rua Bandeira Paulista, º andar São Paulo SP Brasil Fale com a gente 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.