Carregando...

Controle de Listas de Contatos

Controle de Listas de Contatos

 

As integrações desse grupo permitem o controle de recursos relacionados as listas de contatos. É possível consultar informações de contatos na lista, gerar a relação de listas cadastradas, inserir contatos (pontualmente ou em lote) gerar um relatório referente aos envios de um período ou ação específica, remover contatos, inserir contatos opt-out e retornar os opt-out do dia.

 

11.01 - Consulta as Informações de um Contato em uma Lista Específica

 

Utilize essa integração para visualizar informações de um contato  em uma lista.

XML de Envio:

<main>
  <emkt trans="11.01">
    <lista>[TITULO DA LISTA]</lista>
    <contato>[E-MAIL ou CODIGO EXTERNO]</contato>
  </emkt>
</main>
*Itens em negrito são obrigatórios.

XML de Retorno:

<main>
  <emkt trans="11.01">
    <contato codigo="[CODIGO]">
      <nome>[NOME]</nome>
      <sequencia>[SEQUENCIA]</sequencia>
      <email>[EMAIL]</email>
      <sexo>[SEXO]</sexo>
      <idade>[IDADE]</idade>
      <data_nascimento>[DATA_NASCIMENTO]</data_nascimento>
      <endereco>[ENDERECO]</endereco>
      <complemento>[COMPLEMENTO]</complemento>
      <bairro>[BAIRRO]</bairro>
      <cidade>[CIDADE]</cidade>
      <estado>[ESTADO]</estado>
      <pais>[PAIS]</pais>
      <cep>[CEP]</Cep>
      <telefone1>[TELEFONE 1]</telefone1>
      <telefone2>[TELEFONE 2]</telefone2>
      <telefone3>[TELEFONE 3]</telefone3>
      <fax>[FAX]</fax>
      <infoadc1 name="[Campo Adicional 1]">[INFO 01]</infoadc1>
      <infoadc2 name="[Campo Adicional 2]">[INFO 02]</infoadc2>
      <infoadc3 name="[Campo Adicional 3]">[INFO 03]</infoadc3>
      <infoadc4 name="[Campo Adicional 4]">[INFO 04]</infoadc4>
      <infoadc5 name="[Campo Adicional 5]">[INFO 05]</infoadc5>
      <infoadc6 name="[Campo Adicional 6]">[INFO 06]</infoadc6>
      <infoadc7 name="[Campo Adicional 7]">[INFO 07]</infoadc7>
      <infoadc8 name="[Campo Adicional 8]">[INFO 08]</infoadc8>
      <infoadc9 name="[Campo Adicional 9]">[INFO 09]</infoadc9>
      <infoadc10 name="[Campo Adicional 10]">[INFO 10]</infoadc10>
      <infoadc11 name="[Campo Adicional 11]">[INFO 11]</infoadc11>
      <infoadc12 name="[Campo Adicional 12]">[INFO 12]</infoadc12>
      <infoadc13 name="[Campo Adicional 13]">[INFO 13]</infoadc13>
      <infoadc14 name="[Campo Adicional 14]">[INFO 14]</infoadc14>
      <infoadc15 name="[Campo Adicional 15]">[INFO 15]</infoadc15>
      <infoadc16 name="[Campo Adicional 16]">[INFO 16]</infoadc16>
      <infoadc17 name="[Campo Adicional 17]">[INFO 17]</infoadc17>
      <infoadc18 name="[Campo Adicional 18]">[INFO 18]</infoadc18>
      <infoadc19 name="[Campo Adicional 19]">[INFO 19]</infoadc19>
      <infoadc20 name="[Campo Adicional 20]">[INFO 20]</infoadc20>
      <data_validade>[DATA VALIDADE]</data_validade>
    </contato>
  </emkt>

 

11.02 - Retornar o Nome das Listas Cadastradas no Sistema

 

Utilize essa integração para gerar uma relação das listas cadastradas na plataforma.

XML de Envio:

<main>
  <emkt trans="11.02">
  </emkt>
</main> 
*Itens em negrito são obrigatórios

XML de Retorno:

<main>
  <emkt trans="01.22" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    (...)
  </emkt>
</main>

ID: Código identificador  da lista no sistema.

INDICE: Índice da lista. Informa se a lista tem como índice o campo e-mail (E) ou o campo código externo (C). Listas de índice "E" tratam o campo e-mail como "chave" não permitindo a duplicidade dele. Listas com índice "C" tratam o campo código externo como a "chave" assim o campo e-mail poderá se repetir na lista. Um exemplo dessa utilização seria uma escola onde o pai possui dois filhos e precisaria receber a informação de ambos. Nesse caso o código externo poderia ser o RA do aluno.

 CONTATOS_VALIDOS: Quantidade de contatos válidos na lista.

ARQUIVADA: A lista está com o status arquivada no momento:

  S – Sim;

  N – Não.

Depois de um período sem uso por questões de desempenho as listas vão para um arquivo “morto” por isso o status fica como arquivada. Para utilizar a mesma desarquive na própria ferramenta em opções da lista.

NOME_DA_LISTA: Título da lista utilizada no sistema.

 

11.05 - Inclusão de Contatos em uma Lista

 

Utilize essa integração para inserir um ou mais contatos na lista. Se a lista ainda não existir ela é criada nesse momento.  Se a quantidade de contatos a ser importado for maior que mil (1.000) recomendamos o uso da integração (11.10 – Importação de um Arquivo para a Lista).

ATENÇÃO: A importação de contatos para a plataforma não depende exclusivamente da criação de uma nova lista, você pode importar os contatos em uma lista já presente. Para isso no campo "nome" informe uma lista já existente.

XML  de Envio:

<main>
  <emkt trans="11.05">
    <nome>[NOME DA LISTA]</nome>
    <substituir>[S/N]</substituir>
    <tags>
      <nome>[NOME DA TAG1]</nome>
      <nome>[NOME DA TAG2]</nome>
    </tags>
    <destinatario codigo="[CODIGO]">
      <nome>[NOME]</nome>
      <email>[EMAIL]</email>
      <sexo>[SEXO]</sexo>
      <idade>[IDADE]</idade>
      <data_nascimento>[DATA_NASCIMENTO]</data_nascimento>
      <empresa>[EMPRESA]</empresa>
      <cpf>[CPF]</cpf>
      <atividade>[ATIVIDADE]</atividade>
      <profissao>[PROFISSAO]</profissao>
      <tipoend>[TIPO DE ENDERECO]</tipoend>
      <endereco>[ENDERECO]</endereco>
      <complemento>[COMPLEMENTO]</complemento>
      <bairro>[BAIRRO]</bairro>
      <cidade>[CIDADE]</cidade>
      <estado>[ESTADO]</estado>
      <pais>[PAIS]</pais>
      <cep>[CEP]</Cep>
      <telefone1>[TELEFONE 1]</telefone1>
      <telefone2>[TELEFONE 2]</telefone2>
      <telefone3>[TELEFONE 3]</telefone3>
      <fax>[FAX]</fax>
      <infoadc1>[INFO 01]</infoadc1>
      <infoadc2>[INFO 02]</infoadc2>
      <infoadc3>[INFO 03]</infoadc3>
      <infoadc4>[INFO 04]</infoadc4>
      <infoadc5>[INFO 05]</infoadc5>
      <infoadc6>[INFO 06]</infoadc6>
      <infoadc7>[INFO 07]</infoadc7>
      <infoadc8>[INFO 08]</infoadc8>
      <infoadc9>[INFO 09]</infoadc9>
      <infoadc10>[INFO 10]</infoadc10>
      <infoadc11>[INFO 11]</infoadc11>
      <infoadc12>[INFO 12]</infoadc12>
      <infoadc13>[INFO 13]</infoadc13>
      <infoadc14>[INFO 14]</infoadc14>
      <infoadc15>[INFO 15]</infoadc15>
      <infoadc16>[INFO 16]</infoadc16>
      <infoadc17>[INFO 17]</infoadc17>
      <infoadc18>[INFO 18]</infoadc18>
      <infoadc19>[INFO 19]</infoadc19>
      <infoadc20>[INFO 20]</infoadc20>
      <data_validade>[DATA VALIDADE]</data_validade>
    </destinatario>
    <destinatario codigo="[CODIGO]">
      (...)
    </destinatario>
    (...)
  </emkt>
</main>
*Itens em negrito são obrigatórios

XML de Retorno:

<main>
  <emkt trans="11.05" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
    <return id="99">
      <EMAIL_INVALIDO>[EMAIL]</EMAIL_INVALIDO>
      ( … )
    </return>
  </emkt>
</main>
*Itens em negrito são obrigatórios

Substituir: O valor padrão é N (Não), mas caso seja informado S (Sim) todos os contatos já presentes na lista serão removidos antes da importação.

Os campos “infoadc” são os campos adicionais possíveis de incluir na plataforma. Por exemplo, imagine que você tenha um e-commerce. Nesse caso pode precisar de um campo “descrição do produto”. Esse campo não existe, mas você pode criá-lo. Eles devem ser criados manualmente. Acesse nosso passo a passo.

 Codigo: O código externo do destinatário é opcional e deve ser utilizado quando desejar ter uma lista que possua repetição do e-mail.

Atenção: O arquivo de retorno poderá eventualmente apresentar uma lista de e-mails que foram considerados inválidos pelo sistema. A API irá fazer a inserção de todos os e-mails válidos.

 

11.10 - Importação de Arquivo para a Lista

 

Utilize essa integração para importar os contatos em lote. Dessa forma será importado um arquivo .csv contendo todos os contatos desejados. Caso a lista não exista o sistema cria automaticamente e importa os contatos.

Atenção: A importação de contatos para a plataforma não depende exclusivamente da criação de uma nova lista, você pode importar os contatos em uma lista já presente na plataforma. Basta no campo nome informar o nome de uma lista já existente.

XML de Envio:

<main>
  <emkt trans="11.10">
    <nome>[NOME DA LISTA]</nome>
    <identificador>[E/C]</identificador>
    <tags>
      <nome>[NOME DA TAG1]</nome>
      <nome>[NOME DA TAG2]</nome>
    </tags>
    <duplicidade_codigo_externo>[S/N]</duplicidade_codigo_externo>
    <arquivo>[URL DO ARQUIVO]</arquivo>
    <separador>[SEPARADOR]</separador>
    <acao>[I/S/R]</acao>
    <opcoes cabecalho="[S/N]" atualizar="[S/N]" />
    <campos>
      <nome col="[NUMERO DA COLUNA]" />
      <email col="[NUMERO DA COLUNA]" />
      <sexo col="[NUMERO DA COLUNA]" />
      <idade col="[NUMERO DA COLUNA]" />
      <data_nascimento col="[NUMERO DA COLUNA]" />
      <codigo_externo col="[NUMERO DA COLUNA]" />
      <empresa col="[NUMERO DA COLUNA]" />
      <cpf col="[NUMERO DA COLUNA]" />
      <atividade col="[NUMERO DA COLUNA]" />
      <profissao col="[NUMERO DA COLUNA]" />
      <tipoend col="[NUMERO DA COLUNA]" />
      <endereco col="[NUMERO DA COLUNA]" />
      <complemento col="[NUMERO DA COLUNA]" />
      <bairro col="[NUMERO DA COLUNA]" />
      <cidade col="[NUMERO DA COLUNA]" />
      <estado col="[NUMERO DA COLUNA]" />
      <pais col="[NUMERO DA COLUNA]" />
      <cep col="[NUMERO DA COLUNA]" />
      <telefone1 col="[NUMERO DA COLUNA]" />
      <telefone2 col="[NUMERO DA COLUNA]" />
      <telefone3 col="[NUMERO DA COLUNA]" />
      <fax col="[NUMERO DA COLUNA]" />
      <infoadc1 col="[NUMERO DA COLUNA]" />
      <infoadc2 col="[NUMERO DA COLUNA]" />
      <infoadc3 col="[NUMERO DA COLUNA]" />
      <infoadc4 col="[NUMERO DA COLUNA]" />
      <infoadc5 col="[NUMERO DA COLUNA]" />
      <infoadc6 col="[NUMERO DA COLUNA]" />
      <infoadc7 col="[NUMERO DA COLUNA]" />
      <infoadc8 col="[NUMERO DA COLUNA]" />
      <infoadc9 col="[NUMERO DA COLUNA]" />
      <infoadc10 col="[NUMERO DA COLUNA]" />
      <infoadc11 col="[NUMERO DA COLUNA]" />
      <infoadc12 col="[NUMERO DA COLUNA]" />
      <infoadc13 col="[NUMERO DA COLUNA]" />
      <infoadc14 col="[NUMERO DA COLUNA]" />
      <infoadc15 col="[NUMERO DA COLUNA]" />
      <infoadc16 col="[NUMERO DA COLUNA]" />
      <infoadc17 col="[NUMERO DA COLUNA]" />
      <infoadc18 col="[NUMERO DA COLUNA]" />
      <infoadc19 col="[NUMERO DA COLUNA]" />
      <infoadc20 col="[NUMERO DA COLUNA]" />
      <data_validade col="[NUMERO DA COLUNA]" />
    </campos>
  </emkt></main>
*Itens em negrito são obrigatórios

Arquivo - Endereço do arquivo a ser importado, aceita os protocolos HTTP, HTTPS, FTP e FTPS.

O sistema suporta arquivos nos formatos .ZIP, .XLS, .CSV e .Txt, porem a melhor extensão é o .CSV(separados por vírgula).

No formato ZIP o mesmo deve conter somente um arquivo. Os arquivos podem estar  no formato .XLS, .CSV ou .Txt.

Para o arquivo a ser enviado temos o limite de até 20MB para arquivos .ZIP e 40MB para os outros tipos de arquivos.

 Exemplo: ftp://user:senha@ftp.dominio.com.br/pasta/arquivo.csv

Atenção: A codificação do arquivo deve ser ISO-8859-1.

Valores para o campo "ação":

  •  I = Adicionar o conteúdo do arquivo ao conteúdo da lista.
  •  S = Remover o conteúdo anterior da lista antes de importar.
  •  R = Excluir da lista os contatos importados do arquivo.

Opções (esses itens são opcionais)

  • Cabeçalho - Informe se o seu arquivo importado possui ou não a linha de cabeçalho, ou seja, se possui o nome das colunas.
  • Atualizar - Atualiza os dados dos contatos que estiverem diferentes.

Todos os campos exceto e-mail são de uso opcional, portanto a omissão pode ser feita sem problemas.

Atenção: Perceba que todos os campos possuem um item col="[NUMERO DA COLUNA], nele você deve informar o número da coluna que correspondente ao seu arquivo .CSV.

XML de Retorno:

<main>
  <emkt trans="11.10" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <processo>[CODIGO MD5]</processo>
  </emkt>
</main>

 

11.11 - Consulta a Situação do Processo de Importação dos Contatos

 

 Com esse integração é possível  saber a situação da importação dos contatos na integração anterior (11.10 Importação de Arquivo para Lista). O retorno mostrará o percentual do progresso de importação e problemas, como por exemplo, contatos duplicados, em formato inválido e etc. Todos esses contatos não são inseridos na lista.

XML  de Envio:

<main>
  <emkt trans="11.11">
    <processo>[CODIGO MD5]</processo>
  </emkt>
</main>
*Itens em negrito são obrigatórios

XML de Retorno:

<main>
  <emkt trans="11.11" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
    <progresso>[PERCENTUAL]</progresso>
    <resultado>
      <erro>[MENSAGEM DE ERRO]</erro>
      <lista>[NOME DA LISTA]</lista>
      <arquivo>[NOME DO ARQUIVO]</arquivo>
      <linhas>[LINHAS NO ARQUIVO]</linhas>
      <duplicados>[CONTATOS DUPLICADOS NO ARQUIVO]</duplicados>
      <inseridos>[CONTATOS INSERIDOS]</inseridos>
      <atualizados>[CONTATOS ATUALIZADOS]</atualizados>
      <invalidos>[CONTATOS INVALIDOS]</invalidos>
      <formato_invalido>[CONTATOS COM E-MAIL ERRADOS]</formato_invalido>
      <cadastrados>[CONTATOS JÁ CADASTRADOS]</cadastrados>
      <validos_antes>[CONTATOS VALIDOS ANTES DA IMPORTAÇÃO]</validos_antes>
      <validos_apos>[CONTATOS VALIDOS APÓS IMPORTAÇÃO]</validos_apos>
    </resultado>
  </emkt>
</main>

11.40 – Informa as Listas em que o Contato está Presente

 

Essa integração gera uma relação de listas em que um determinado contato está presente. Você pode informar mais de um contato na mesma integração.

XML de Envio:

<main>
   <emkt trans="11.40">
      <email>teste@teste.com.br</email>
      <email>teste@teste.com.br</email>
     (...)
   </emkt>
</main>
*Itens em negrito são obrigatórios.

XML de Retorno:

<main>
 <emkt>
  <contato>
    <email>teste@teste.com.br</email>
      <listas>
       <titulo>Lista 01</titulo>
       <titulo>Lista 02</titulo>
       <titulo>Lista 30</titulo>
      </listas>
   </contato>
   <contato>
    <email>teste01@teste.com.br</email>
     <listas>
       <titulo>Lista 01</titulo>
       <titulo>Lista 35</titulo>
       <titulo>Lista 70</titulo>
     </listas>
   </contato>
 </emkt>
</main>

 

11.45 – Remover Contatos de uma Lista

 

Utilize essa integração para remover contatos de uma determinada lista. Você pode utilizar como “chave” para a remoção o endereço de e-mail ou o número de celular.

XML de remoção usando o campo e-mail:

<main>
 <emkt trans="11.45">
  <titulo>Titulo da lista</titulo>
   <destinatarios>
    <email>teste@teste.com.br</email>
    <email>teste@teste.com.br</email>
    <email>teste@teste.com.br</email>
    (...)
   </destinatarios>
  </emkt>
</main>
*Itens em negrito são obrigatórios.

XML de remoção usando o campo celular:

<main>
 <emkt trans="11.45">
  <titulo>Titulo da lista</titulo>
   <destinatarios>
    <celular>11999999999</celular>
    <celular>11999999999</celular>
    <celular>11999999999</celular>
    (...)
   </destinatarios>
  </emkt>
</main>
*Itens em negrito são obrigatórios.

XML de Retorno:

<MAIN>
    <EMKT TRANS="11.45" KEY="0c5001c9dd16bb98dd78631b9ce6">
        <RETURN ID="00">Contatos removidos com sucesso. </RETURN>
    </EMKT>
</MAIN>

 

11.90 - Insere Opt-Out / Opt-In

 

Utilize essa integração para tornar um contato opt-out ou opt-in. Quando um contato é opt-out ele não recebe mais as mensagens enviadas pela plataforma. Se o contato está com o status opt-in ele irá receber normalmente. Você pode utilizar as categorias para definir o tipo de mensagem que ele deve ou não receber. A categoria deve conter o título à qual o contato será alterado para opt-out / opt-in. Também poderá conter a literal “[TODAS]” para indicar que a alteração valerá para todas as categorias. Exemplo: [TODAS]

 Na plataforma a categoria está descrita como área de interesse. Você pode tornar um contato opt-in para uma categoria e opt-out para outra assim ele receberá apenas as mensagens da área que ele tiver interesse.

XML  de Envio:

<main>
  <emkt trans="11.90">
    <acao>[ACAO]</acao> (0 = Opt-out, 1 = Opt-In)
    <email>[EMAIL]</email> (E-mail que será setado opt-out ou opt-in)
    <categoria>[CATEGORIA]</categoria>
    <categoria>[CATEGORIA]</categoria>
    <categoria>[CATEGORIA]</categoria>
    (...)
  </emkt>
</main>
*Itens em negrito são obrigatórios.

XML de Retorno:

<main>
  <emkt trans="11.90" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
  </emkt>
</main>

Retorno com falha:

<main>
  <emkt trans="11.90" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="99">Categoria não encontrada (Lista de categorias separadas por vírgula)</return>
  </emkt>
</main>
Este conteúdo foi útil?38