manual de integraÇÃo - akna.infoakna.info/.../aktr02010003001_manual_de_integracao...2 sumário o...

1

MANUAL DE INTEGRAÇÃO

AKNA TREINAMENTOS

AKTR02010003001

2

Sumário

O que é?..............................................................................................................................................4

Para que serve?..................................................................................................................................4

Como começar?..................................................................................................................................4

01 - Controle de Usuários e Equipes..................................................................................................5

01.10 - Cria um novo usuário .................................................................................................. 5

01.13 Editar um usuário ........................................................................................................... 7

01.15 Excluir um usuário ......................................................................................................... 7

01.20 Criar uma nova equipe .................................................................................................. 8

01.22 Lista todas as equipes cadastradas .............................................................................. 9

01.23 Edita uma equipe ........................................................................................................... 9

1.25 Apaga uma equipe ......................................................................................................... 10

11 - Controle de Lista de Contatos...................................................................................................11

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

11.02 Retornar o Nome das Listas Cadastradas no Sistema ............................................... 12

11.05 Inclusão de Contatos em uma Lista ............................................................................ 12

11.10 Importação de Arquivo para a Lista ............................................................................ 14

11.11 Consulta a situação de processo de importação da integração (11.10) .................... 15

11.20 Histórico de Ações por Período ................................................................................... 16

11.21 - Situação do Processo de Histórico de Ações por Período (11.20) .......................... 17

11.22 Download do arquivo ZIP solicitado no histórico de ações por período (11.20) ........ 17

11.30 Históricos de Erros por Período .................................................................................. 18

11.90 - Insere Opt-Out / Opt-In .............................................................................................. 18

11.95 Retornam os Opt-Out do Dia ....................................................................................... 19

12.05 Cadastra uma nova Área de Interesse no Sistema. ................................................... 20

12.20 Remove uma Área de Interesse do Sistema. ............................................................. 20

12.50 - Lista todas as Área de Interesses Cadastradas. ...................................................... 20

12.70 - Edita uma Área de Interesse. .................................................................................... 21

15.05 - Criação de Mensagem .............................................................................................. 21

15.50 Lista de Mensagens Cadastradas ............................................................................... 23

15.55 Informações da Mensagem ......................................................................................... 24

19 - Controle de Ações.....................................................................................................................24

19.03 – Retornar o nome das ações Transacionais do sistema ........................................... 24

19.04 - Inclusão de uma Ação Transacional ......................................................................... 25

19.05 - Inclusão de uma Ação Pontual.................................................................................. 26

19.06 - Agendamentos de Envio da Ação ............................................................................. 28

19.07 - Envio de E-mail de Teste da Ação ............................................................................ 28

19.10 - Estatísticas das Ações em um Determinado Período .............................................. 29

3

19.11 - Totais da Ação ........................................................................................................... 29

19.31- Contatos que Visualizaram a Ação ............................................................................ 30

19.55 - Informações da Ação ................................................................................................. 30

19.80 - Lista de e-mails inválidos da Ação ............................................................................ 31

20 - Alterações de Listas das Ações................................................................................................32

20.01 - Inclusão de Contatos Direto em uma Ação Sem o Envio Imediato.......................... 32

20.05 Disparando uma Ação Transacional ........................................................................... 34

20.10 - Importação de Arquivo para a Ação .......................................................................... 35

20.11 - Situação de Importação de Arquivo para a Ação (20.10) ......................................... 36

30.05 Inserindo contatos em uma automação.................................................................................37

40 - Disparo de ações SMS Corporativo (Transacional)..................................................................39

40.01 Cadastrar Ação de SMS Corporativo .......................................................................... 39

40.02 - Consultar o Status do Envio ...................................................................................... 39

40.03 Consultar as Respostas dos Destinatários ................................................................. 40

40.04 Solicitação de relatório de cliques de SMS transacional ............................................ 40

40.05 Acompanhar o progresso da geração do relatório ...................................................... 41

40.06 Realizar o download arquivo zipado (.zip) .................................................................. 41

4

O que é? Nossa API é um documento técnico onde você encontra todas as integrações possíveis da plataforma Akna tanto para o produto E-mail Marketing quanto para SMS.

Para que serve? Elas servem para integrar um site ou algum outro programa utilizado em sua empresa com a plataforma. Por exemplo, nesse documento você tem instruções para ter um formulário em seu site que envia as informações preenchidas a uma lista na plataforma Akna.

Como começar? Para trabalhar com as integrações, é obrigatório criar um tipo de usuário chamado Usuário de Integração. Este usuário não tem acesso a nenhuma outra função da plataforma e apenas ele pode executar as integrações. Uma vez criado o Usuário de Integração, é muito importante identificar qual a integração que melhor atende sua necessidade. Por esse motivo, sugerimos que leia atentamente as orientações abaixo e, se ainda tiver alguma dúvida na escolha da melhor solução, não deixe de nos procurar.

Todas as transações devem seguir o padrão abaixo:

Envio de uma requisição POST para o um dos endereços abaixo:

http://app.akna.com.br/emkt/int/integracao.php

https://app.akna.com.br/emkt/int/integracao.php

Com os seguintes campos obrigatórios:

User = E-mail do usuário

Pass = Senha do usuário criptografada com MD5

Client = Código da empresa no sistema (solicite ao nosso atendimento esse campo é obrigatório

caso você tenha mais de um cadastro com a Akna).

XML = Conteúdo da Solicitação

Remetente = No caso de envio de SMS.

Todas as transações retornam um XML, e no caso de erro de pedido incorreto, alguns padrões de códigos de retorno são respeitados para todos os tipos de transações, são eles.

ATENÇÃO: O sistema faz diferenciação entre letras maiúsculas e minúsculas, portanto mantenha User, Pass, Client e XML exatamente como escrito aqui.

CUIDADO: um erro comum, é sempre criar uma lista e uma ação novas para todos os disparos. Isso faz com que a quantidade de listas e ações no sistema seja enorme, dificultando o gerenciamento das mesmas e impactando no desempenho da plataforma. Se você tem uma demanda recorrente com um mesmo conteúdo saiba que a melhor forma de fazer esse disparo é criando ações transacionais. Você cria uma ação e vai injetando contato para disparo conforme a sua demanda. Exemplo de aplicação: enviar um e-mail de boas-vindas quando um contato se inscreve em seu site. Enviar uma pesquisa de satisfação sempre que um contato passa por um atendimento em sua loja. Enviar um e-mail com os dados de uma compra, entre outras possibilidades.

http://app.akna.com.br/emkt/int/integracao.php

https://app.akna.com.br/emkt/int/integracao.php

5

01 - Usuário e/ou senha inválidos

02 - Permissão Negada

03 - Transação Inválida

05 - Usuário pertence a mais de uma empresa, obrigatório envio de código de empresa

06 - Acesso negado

11 – Variável do xml está sem conteúdo ou não foi informada. Verifique se a opção de encoding

do seu cliente de teste API está form-data.

• O XML deve ser enviado codificado em UTF-8. • Apenas os campos em negrito dos XML’s são obrigatórios. • Se estiver utilizando algum cliente de teste de API , como por exemplo postman, a opção de

codificação marcada deve ser form-data. Exemplo de configuração para utilização de um cliente para teste de API:

• Não são aceitos símbolos HTML tais como " ã ç e etc. Com exceção do & nestes

casos o texto deve conter a acentuação normalmente (áéãçí …).

• Crie um usuário para ser utilizado exclusivamente para a integração, por exemplo, integraçã[email protected].

• Lembre-se de tratar todos os XML de retorno, pois caso ocorra algum erro será descrito no mesmo e

será muito mais fácil identificar o problema e corrigir.

• Sempre que estiver tendo problemas relacionados à integração encaminhe a nossa equipe de atendimento o XML de envio e de retorno para garantirmos uma maior agilidade nesse atendimento.

01 - Controle de Usuários e Equipes

01.10 - Cria um novo usuário

Utilize essa integração quando desejar criar um novo usuário na ferramenta. Abaixo você encontra a descrição dos campos.

mailto:integraçã[email protected]

6

Envio:

<main>

<func trans="01.10">

<dados_usuario>

<email>[E-MAIL]</email>

<nome>[NOME]</nome>

<senha>[SENHA]</senha>

<confirma_senha>[SENHA]</confirma_senha>

<equipe codigo=[99]>[NOME_EQUIPE]</equipe>

<documento>[DOCUMENTO]</documento>

<idioma>[pt-br/es/en]</idioma>

<telefone>[TELEFONE]</telefone>

<tel_movel>[TELEFONE]</tel_movel>

<supervisor>[S/N]</supervisor>

<acesso_nivel_inferior>[S/N]</acesso_nivel_inferior>

</dados_usuario>

<seguranca>

<restricao_ip>[S/N]</restricao_ip>

<ip_restrito>[999.999.999.999];(...)</ip_restrito>

<data_bloqueio>[AAAA-MM-DD]</data_bloqueio>

<acesso_admin>[S/N]</acesso_admin>

</seguranca>

</func>

</main>

• Equipe - O valor dessa chave deverá ser obtido com a integração 01.22 desse documento. O código da equipe só deverá ser passado quando não for utilizar o caminho completo da equipe. Ao utiliza-lo não se deve passar valor algum entre as chaves equipe, ou seja, pode-se utilizar apenas uma opção por vez.

• IP Restrito - deve-se obrigatoriamente passar os ip’s separados por ';' (ponto e vírgula). Essa opção deve ser utilizada quando desejar restringir o acesso dos usuários a ferramenta. Assim o acesso não será feito caso o usuário esteja em outro número de ip que não seja o informado.

• Data Bloqueio - Utilize caso deseje que o usuário não tenha mais acesso a ferramenta após um

determinado período.

• Acesso Admin - Para que o usuário tenha permissão de administrador na ferramenta. Retorno:

<main>

<func trans="01.10" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">

<return id="00">Ok</return>

</func>

</main>

7

01.13 Editar um usuário Utilize essa integração quando desejar editar um usuário na ferramenta para alterações. Envio:

<main>


<dados_usuario>


<nome>[NOME]</nome>

<senha>[SENHA]</senha>

<confirma_senha>[SENHA]</confirma_senha>

<equipe codigo=[99]>[NOME_EQUIPE]</equipe>

<documento>[DOCUMENTO]</documento>


<telefone>[TELEFONE]</telefone>

<tel_movel>[TELEFONE]</tel_movel>

<supervisor>[S/N]</supervisor>

<acesso_nivel_inferior>[S/N]</acesso_nivel_inferior>

</dados_usuario>

<seguranca>

<restricao_ip>[S/N]</restricao_ip>

<ip_restrito>[999.999.999.999];(...)</ip_restrito>

<data_bloqueio>[AAAA-MM-DD]</data_bloqueio>

<acesso_admin>[S/N]</acesso_admin>

</seguranca>

</func>

</main>

• Equipe - O valor dessa chave deverá ser obtido com a integração 01.22 desse documento. O

código da equipe só deverá ser passado quando não for utilizar o caminho completo da equipe. Ao utiliza-lo não se deve passar valor algum entre as chaves equipe, ou seja, pode-se utilizar apenas uma opção por vez.

• IP Restrito - deve-se obrigatoriamente passar os ips separados por ';' (ponto e vírgula). Essa opção

deve ser utilizada quando desejar restringir o acesso dos usuários a ferramenta. Assim o acesso não será feito caso o usuário esteja em outro número de ip que não seja o informado.

• Data Bloqueio - Utilize caso deseje que o usuário não tenha mais acesso a ferramenta após um determinado período.

• Acesso Admin - Para que o usuário tenha permissão de administrador na ferramenta.

Retorno:

<main>



</func>

</main>

01.15 Excluir um usuário

Utilize essa integração quando desejar excluir um usuário da ferramenta. Envio:

<main>


<dados_usuario>


</dados_usuario>

</func>

</main>

8

Retorno:

<main>



</func>

</main>

01.20 Criar uma nova equipe Utilize essa integração quando desejar criar uma nova equipe na ferramenta. As equipes são como um grupo com regras de permissões. Elas facilitam a administração quando se tem muitos usuários, por exemplo, imagine que você tem 10 usuários todos da equipe marketing, se precisar trocar alguma permissão basta alterar a permissão na equipe ao invés de trocar de um em um. Envio:

<main>


<equipe>

<nome>[NOME_EQUIPE]</nome>

<criar_estrutura>[TRUE]</criar_estrutura>

</equipe>

</func>

</main>

• Nome: o valor dessa chave deverá seguir o formato de retorno conforme a integração 01.22,

passando-se o nome da nova equipe no final da estrutura. Por exemplo: Para criar uma equipe chamada “Treinamento2” abaixo da equipe Treinamento ficaria: Superior|Treinamento|Treinamento2.

• Criar Estrutura: Se for passado TRUE neste valor o sistema irá criar toda a estrutura necessária para

a criação da equipe.

ATENÇÃO: Não é possível excluir um usuário caso ele tenha permissão de administrador. Primeiro será necessário retirar essa opção que poderá ser feita via integração 01.13 (editar um usuário) ou manualmente acessando a ferramenta.

9

Retorno:

<main>



</func>

</main>

01.22 Lista todas as equipes cadastradas Utilize essa integração quando desejar visualizar uma lista de todas as equipes presentes na ferramenta. Envio:

<main>

<func trans="1.22">

</func>

</main>

Retorno:

<main>


<EQUIPE CODIGO="1">Equipe 1</EQUIPE>

<EQUIPE CODIGO="2" EQUIPE_SUPERIOR="1">Equipe 1|Equipe 1.1</EQUIPE>

<EQUIPE CODIGO="3" EQUIPE_SUPERIOR="2">Equipe 1|Equipe 1.1|Equipe 1.1.1</EQUIPE>

(...)

</func>

</main>

01.23 Edita uma equipe

Utilize essa integração quando desejar editar uma equipe na ferramenta para alterações.

Envio:

<main>


<equipe>


<novo_nome>[NOVO_NOME_EQUIPE]</novo_nome>

<criar_estrutura>[TRUE]</criar_estrutura>

</equipe>

</func>

</main>

• Nome - O valor dessa chave deverá seguir o formato de retorno conforme a integração 1.22 (Lista

equipes cadastradas), passando-se o caminho completo da equipe.

• Novo Nome: O valor dessa chave deverá seguir o formato de retorno conforme a integração 01.22 (Lista equipes cadastradas), passando-se o novo nome da nova equipe no final da estrutura.

• Criar Estrutura: Se for passado TRUE neste valor o sistema irá criar toda a estrutura necessária para a alteração da equipe.

10

Exemplo: Se tivermos uma equipe com o caminho como o descrito a seguir: Equipe1|Equipe1.1|Equipe1.1.1 E quisermos alterar a equipe Equipe1.1.1 para: Equipe2|Equipe2.1 E não existir uma equipe chamada Equipe2 e desejamos criá-la no processo. Então o XML deverá ser como o descrito abaixo:

<main> <func trans="01.23"> <equipe> <nome>Equipe1|Equipe1.1|Equipe1.1.1</nome> <novo_nome>Equipe2|Equipe2.1</novo_nome> <criar_estrutura>TRUE</criar_estrutura> </equipe> </func> </main>

Depois de a operação correr com sucesso a estrutura ficará como a descrita abaixo: Equipe1|Equipe1.1 Equipe2|Equipe2.1 Retorno:

<main>



</func>

</main>

1.25 Apaga uma equipe

Utilize essa integração quando desejar excluir uma equipe. Envio:

<main>

<func trans="1.25">

<equipe>


</equipe>

</func>

</main>

• Nome - O valor dessa chave deverá seguir o formato de retorno conforme a integração 01.22 (Lista

equipes cadastradas), passando-se o caminho completo da equipe.

Para excluir a equipe não pode existir nenhuma equipe relacionada a ela, e também nenhum usuário cadastrado nela. Somente será excluída a última equipe passada. Exemplo: Se quisermos excluir a equipe Equipe1.1 do caminho descrito a seguir: Equipe1|Equipe1.1|Equipe1.1.1 Será necessário primeiro a exclusão da Equipe1.1.1 e depois da equipe Equipe1.1, ou seja será necessário duas integrações distintas para obter o resultado esperado.

11

Retorno:

<main>



</func>

</main>

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

Utilize essa integração quando desejar visualizar informações de um contato específico.

Envio: <main>

<emkt trans="11.01">

<lista>[TITULO DA LISTA]</lista>

<contato>[E-MAIL ou CODIGO EXTERNO]</contato>

</emkt>

</main>

Retorno: <main>


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



<fax>[FAX]</fax>

<infoadc1 name="[Campo Adicional 1]">[INFO 01]</infoadc1>




















<data_validade>[DATA VALIDADE]</data_validade>

</contato>

</emkt>

ATENÇÃO: Contato: Deve ser informado o e-mail ou código externo. Caso tenha certeza que o contato existe na lista, mas a integração retorna que o contato não foi encontrado, verifique se o índice da lista está de acordo com o tipo de informação passada no campo do contato, ou seja, verifique se é uma lista que utiliza o e-mail como índice ou um código como índice.

12

11.02 Retornar o Nome das Listas Cadastradas no Sistema

Utilize essa integração quando desejar uma relação das listas cadastradas na ferramenta. Envio:

<main>


</emkt>

</main>

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>





(...)

</emkt>

</main>

• ID: Identificador da lista no sistema. • INDICE: Índice da lista:

E – E-mail; C – Código Externo.

• 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 quando desejar inserir um ou mais contatos para uma lista existente, caso a lista não exista o sistema cria automaticamente a lista e importa os contatos. 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 na plataforma. Basta no campo nome informar o nome de uma lista já existente.

13

Envio: <main>


<nome>[NOME DA LISTA]</nome>

<substituir>[S/N]</substituir>

<tags>

<nome>[NOME DA TAG1]</nome>


</tags>

<destinatario codigo="[CODIGO]">

<nome>[NOME]</nome>


<sexo>[SEXO]</sexo>



<empresa>[EMPRESA]</empresa>

<cpf>[CPF]</cpf>

<atividade>[ATIVIDADE]</atividade>

<profissao>[PROFISSAO]</profissao>

<tipoend>[TIPO DE ENDERECO]</tipoend>






<pais>[PAIS]</pais>

<cep>[CEP]</Cep>




<fax>[FAX]</fax>

<infoadc1>[INFO 01]</infoadc1>





















</destinatario>


(...)

</destinatario>

(...)

</emkt>

</main>

Retorno:

<main>



<return id="99">

<EMAIL_INVALIDO>[EMAIL]</EMAIL_INVALIDO>

( … )

</return>

</emkt>

</main>

• Substituir: O valor padrão é N (Não), mas caso seja informado S (Sim) todos os e-mails da lista serão

removidos antes da importação.

14

• Os campos “infoadc” são os campos adicionais que são possíveis incluir na ferramenta. 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 na ferramenta, mas poderá cria-lo.

• Destinatario.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.

11.10 Importação de Arquivo para a Lista

Utilize essa integração quando desejar utilizar um arquivo contendo muitos contatos para uma lista existente. Caso a lista não exista o sistema cria automaticamente a lista e importa os contatos. Essa importação é recomendada para importar muitos contatos de uma única vez. Envio: <main>


<nome>[NOME DA LISTA]</nome>

<identificador>[E/C]</identificador>

<tags>



</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]" />



<fax col="[NUMERO DA COLUNA]" />

<infoadc1 col="[NUMERO DA COLUNA]" />















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

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.

15






<data_validade col="[NUMERO DA COLUNA]" />

</campos>

</emkt></main>

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 Texto porem a melhor extensão é o CSV. O arquivo no formato ZIP deve conter somente um arquivo dentro no formato XLS, CSV ou Texto. 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:[email protected]/pasta/arquivo.csv

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 - Atualizar os dados dos contatos que estiverem diferentes. Todos os campos exceto e-mail são de uso opcional, portanto a omissão de <nome col="[NUMERO DA COLUNA]" /> por exemplo, pode ser feita sem problemas.

Retorno:

<main>


<processo>[CODIGO MD5]</processo>

</emkt>

</main>

11.11 Consulta a situação de processo de importação da integração (11.10)

Utilize essa integração quando desejar saber a situação da importação. O retorno mostrará o percentual do progresso de importação e problemas que podem ter como, por exemplo, contatos duplicados, em formato inválido que poderia ser a falta do “@”. Todos esses contatos não são inseridos na lista. Envio:

<main>



</emkt>

</main>

ATENÇÃO: Perceba que todos os campos possuem um item col="[NUMERO DA COLUNA] nele você deve informar o número da coluna em seu arquivo CSV onde se encontra aquele campo.

ATENÇÃO: A codificação do arquivo que será feito o upload deve ser ISO-8859-1

ftp://user:[email protected]/pasta/arquivo.csv

16

Retorno:

<main>



<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.20 Histórico de Ações por Período

Essa integração é a primeira de três integrações que devem ser usadas. Utilize o processo quando desejar gerar um relatório com o histórico dos contatos em um determinado período. O retorno após os três passos será um arquivo csv com informações como cliques, ações que participou e outros. Veja mais detalhes abaixo. Envio:

<main>


<data_inicial>AAAA-MM-DD HH:MM:SS</data_inicial>

<data_final>AAAA-MM-DD HH:MM:SS</data_final>

<usuario>[E-MAIL DO USUÁRIO]</usuario>

<novas_colunas>S</novas_colunas>

<campos>

<infoadc13>S</infoadc13>

</campos>

</emkt>

</main>

Retorno: <main>



</emkt>

</main>

ATENÇÃO: - A diferença entre a data inicial e data final não pode ser maior que 24 horas. - Caso queira consultar uma ação especifica troque <data_inicial>AAAA-MM-DD HH:MM:SS</data_inicial> <data_final>AAAA-MM-DD HH:MM:SS</data_final> Por: <acao>[TITULODAACAO]</acao> ou <acao_codigo>[CODIGODAACAO]</acao_codigo> As colunas código do evento e elemento só são inseridas quando for utilizada a opção: <novas_colunas>S</novas_colunas> Utilizando a tag <campos> você pode acrescentar ao relatório gerado campos presentes na lista sejam campo padrão ou campo adicional. <campos> <infoadc04>S</infoadc04> </campos>

17

11.21 - Situação do Processo de Histórico de Ações por Período (11.20)

Essa integração é o segundo passo da integração 11.20. Utilize para verificar o status do processo de geração do relatório. Utilize o código do retorno da integração 11.20 para o envio conforme segue abaixo: Envio:

<main>



</emkt>

</main>

Retorno:

<main>




<resultado>


</resultado>

</emkt>

</main>

Somente quando o retorno for “100” e não houver mensagem de erro podemos solicitar a 11.22.

11.22 Download do arquivo ZIP solicitado no histórico de ações por período (11.20) Esse é o terceiro e último passo para geração do relatório de histórico dos contatos. Utilize o código do retorno da integração 11.20 para o envio conforme segue abaixo:

Envio:

<main>


<processo>[CODIGO MD5]</processo >

</emkt>

</main>

Retorno:

Essa solicitação retorna um arquivo no formato zip, contendo um csv com as seguintes

colunas Ação, Data e Hora, E-mail, Código externo, Evento (Descrição), Código do Evento

e Elemento. O csv retornado usará ; (ponto e virgula) como separador dos campos.

Possibilidades de códigos de eventos

TE – Troca de e-mail, o elemento terá os dois e-mails separados por | (pipe), sendo que

o primeiro será o e-mail anterior e o segundo o novo e-mail

OO – Opt-out, o elemento será a Área de interesse

OI – Opt-in, o elemento será a Área de interesse

EN – Encaminhamento, o elemento será o e-mail para quem o usuário encaminhou

ET – Entregue, nesse caso não haverá conteúdo em elemento

ER – Erro, o elemento será o erro que ocorreu

VW – Visualizou, nesse caso não haverá conteúdo em elemento

CL – Clique, o elemento será o link onde ocorreu o clique

AC – Alteração de cadastro, caso não haverá conteúdo em elemento

PR – Pedido de remoção, o elemento virá preenchido com o motivo caso esse tenha sido

informado.

18

11.30 Históricos de Erros por Período

Utilize essa integração quando desejar gerar um relatório com o histórico dos erros dos contatos nas ações como, por exemplo, caixa postal cheia. Envio:

<main>


<data_inicial>AAAA-MM-DD HH:MM:SS</data_inicial>

<data_final>AAAA-MM-DD HH:MM:SS</data_final>

</emkt>

</main>

Retorno:

<main>



<contato>

<data>[AAAA-MM-DD HH:MM:SS]</data>

<email>[EMAIL DO CONTATO]</email>

<acao>[TITULO DA ACAO]</acao>

<evento>[TIPO DE ERRO]</evento>

</contato>

</emkt>

</main>

DATA – Data e hora do histórico. EMAIL – Email do contato que gerou o histórico. ACAO – Titulo da ação que o contato participou. EVENTO - Tipo de erros que podem ser apresentados:

• Anti-spam • Conteúdo rejeitado • Caixa postal cheia • Outros • Falha de entrega • Destinatário desconhecido • Servidor desconhecido • Caixa postal indisponível

11.90 - Insere Opt-Out / Opt-In Utilize essa integração quando desejar tornar um contato opt-out ou opt-in. Quando um contato é opt-out ele não recebe mais as mensagens enviadas pela ferramenta. 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 poderá 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: <categoria>[TODAS]</categoria>

Na ferramenta 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.

ATENÇÃO: A diferença entre a data inicial e data final não pode ser maior que 24 horas.

19

Envio: <main>


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



(...)

</emkt>

</main>

Retorno:

<main>



</emkt>

</main>

Retorno com falha:

<main>


<return id="99">Categoria não encontrada (Lista de categorias separadas por virgula)</return>

</emkt>

</main>

11.95 Retornam os Opt-Out do Dia

Utilize essa integração quando desejar verificar os opt-out que ocorreram no dia. Envio:

<main>


<data>AAAA-MM-DD</data>

</emkt>

</main>

Retorno:

<main>


<contato>

<datahora>[AAAA-MM-DD HH:MM:SS]</datahora>

<email>[EMAIL DO CONTATO]</email>

<acao codigo="[CODIGO DA ACAO]">[NOME DA ACAO]</acao>

<motivo codigo="[CODIGO DO MOTIVO]">[DESCRICAO DO MOTIVO]</motivo>

<area codigo="[CODIGO DA AREA]">[NOME DA AREA DE INTERESSE]</area>

</contato>

<contato>

(...)

</contato>

</emkt>

</main>

ATENÇÃO: Esse processo só considera ações não arquivadas.

20

12 - Controle de Mensagens

12.05 Cadastra uma nova Área de Interesse no Sistema.

Utilize essa integração quando desejar inserir novas áreas de interesse. A área de interesse defini as mensagens que um contato deve ou receber. Assim o status do contato será opt-out ou opt-in. Envio: <main>


<categoria>

<nome>[NOME DA ÁREA DE INTERESSE]</nome>

</categoria>

</emkt>

</main>

Retorno:

<MAIN>

<EMKT TRANS="12.05" KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">

<RETURN ID="00">OK</RETURN>

</EMKT>

</MAIN>

12.20 Remove uma Área de Interesse do Sistema.

Utilize essa integração quando desejar excluir uma área de interesse.

Envio:

<main>


<categoria>

<nome>[ NOME DA ÁREA DE INTERESSE]</nome>

</categoria>

</emkt>

</main>

Retorno:

<MAIN>


<RETURN ID="00">OK</RETURN>

</EMKT>

</MAIN>

12.50 - Lista todas as Área de Interesses Cadastradas.

Utilize essa integração quando desejar visualizar todas as áreas de interesse presentes na ferramenta.

Envio:

<main>


<categoria>

<nome>[TODAS]</nome>

</categoria>

</emkt>

</main>

21

Retorno: <MAIN>


<CATEGORIA>

<DESCRICAO CODIGO=”[CODIGO]”>[DESCRICAO]<DESCRICAO>

( … )

</CATEGORIA>

</EMKT>

</MAIN>

12.70 - Edita uma Área de Interesse.

Utilize essa integração quando desejar alterar o nome da área de interesse.

Envio:

<main>


<categoria>

<nome>[ NOME DA ÁREA DE INTERESSE]</nome>

<novo>[ NOVO NOME DA ÁREA DE INTERESSE]</novo>

</categoria>

</emkt>

</main>

Retorno:

<main>



</emkt>

</main>

15.05 - Criação de Mensagem Utilize essa integração quando desejar criar uma mensagem na ferramenta. Nesse caso é necessário ter uma mensagem em HTML.

Envio:

<main>


<nome>[NOME DA MENSAGEM]</nome>

<categoria>[NOME DA CATEGORIA]</categoria>

<idioma>[CÓDIGO DO IDIOMA]</idioma>

<html>[HTML]</html>

<texto tipo="[P/H/C]">[TEXTO ALTERNATIVO]</texto>

<alternativa>[MENSAGEM DE VISUALIZAÇÃO ALTERNATIVA]</alternativa>

<optout>[MENSAGEM DE OPT-OUT]</optout>

<encaminhar>[MENSAGEM DE ENCAMINHAMENTO]</encaminhar>

<msg_redes_sociais>[MENSAGEM REDES SOCIAIS]</msg_redes_sociais>

<redes_sociais>[REDES SOCIAIS]</redes_sociais>

<link url="[LINK]" tipo="[N/P/A/O/E]">[NOME DO LINK]</link>

<link url="[LINK]" tipo="[N/P/A/O/E]">[NOME DO LINK]</link>

<atualizar_acoes>S</atualizar_acoes> (...)

</emkt>

</main>

• HTML: A mensagem html deve ter os caracteres "<", ">", """ e "&" substituídos por "<", " > ",

""" e "&" respectivamente. Também é necessário utilizar o CDATA caso tenha um HTML. Você pode utilizar o link abaixo para efetuar essas substituições: (https://www.web2generators.com/html-based-tools/online-html-entities-encoder-and-decoder)

https://www.web2generators.com/html-based-tools/online-html-entities-encoder-and-decoder

22

Segue um exemplo de como deve ficar o HTML: <![CDATA[<HTML> <HEAD></HEAD> <BODY>TESTE</BODY> </HTML>]]> • Categoria: É a área de interesse da mensagem.

• Idioma (altera o idioma dos links adicionais como, por exemplo, o link de visualização alternativa):

pt-br => Português, valor padrão caso não seja enviado o idioma en => Inglês es => Espanhol

• Texto.Tipo: P - Texto padrão do sistema H - HTML da mensagem em formato texto C - Texto customizado pelo cliente

• Link.Tipo: N – Normal P – Alteração de dados cadastrais A – Visualização alternativa O – Solicitação de OptOut E – Encaminhamento de mensagem

• Link.Monitorar

Quando link.Tipo for igual a “N” (normal), podemos opcionalmente monitorá-lo. Informar os códigos de monitoramento separados por “|”, conforme lista abaixo:

• WA - Web Analytics • GA - Google Analytics Exemplos : <link url="[LINK]" tipo="N” monitorar=“GA”>[NOME DO LINK]</link> <link url="[LINK]" tipo="N” monitorar=“GA|WA”>[NOME DO LINK]</link>

• Link.Anunciante • Link.Anuncio

Os dois atributos devem ser utilizados ao mesmo instante. Somente poderá ser utilizado Anunciantes e Anúncios que estejam ativos no sistema.

Exemplos: <link url="[LINK]" tipo="N” anunciante=“NOME_ANUNCIANTE” anuncio=“NOME_ANUNCIO”>[NOME DO LINK]</link>

• Redes sociais, enviar os códigos das redes desejadas separados por vírgula, segue abaixo lista de redes disponíveis.

DLC => Delicious DIG => Digg FCB => Facebook FSQ => Fresqui GBM => Google Bookmarks MNM => Menéame MYY => My Yahoo MYS => Myspace ORK => Orkut TWT => Twitter WLV => Windows Live

• Atualizar Ações: Esse parâmetro tem como objetivo atualizar a mensagem nas ações que a mesma está vinculada.

23

Caso a mensagem tenha sido atualiza em uma ou mais ações, o XML de retorno exibi o nome dessas ações.

- A ação não pode estar excluída; - Se for uma Ação Recorrente, a atualização será na principal (ou seja, a ação PAI); - Se for uma Ação Transacional, a atualização é dada quando o status for ENVIADA; - Se for uma Ação de REMARKETING, as Ações atualizadas serão aquelas que estão dentro dos status PENDENTE, ENVIADA, REENVIO PARCIAL e PAUSADA. - Demais Ações dentro dos status PENDENTE, REENVIO PARCIAL e PAUSADA.

Retorno do XML utilizando a atualização:

Retorno sem a linha de atualização:

<main>



</emkt>

</main>

15.50 Lista de Mensagens Cadastradas

Utilize essa integração quando desejar uma lista com a relação de mensagens cadastradas na ferramenta. Envio: <main>


<data_inicial>AAAA-MM-DD</data_inicial>

<data_final> AAAA-MM-DD</data_final>

</emkt>

</main>

Retorno: <main>


<mensagem>

<titulo>[TITULO DA MENSAGEM]</titulo>


</mensagem>

</emkt>

</main>

ATENÇÃO: A data inicial e a data final não são obrigatórias e podem ser informados separadamente.

<?xml version="1.0" encoding="UTF-8"?>

<MAIN>

<EMKT TRANS="15.05" KEY="07d0011387c37884c03518276667">

<RETURN ID="00">Ok</RETURN>

<CAMPANHAS_ATUALIZADAS>

...

<CAMPANHA CODIGO="Código da Ação">Título da Ação</CAMPANHA>

<CAMPANHA CODIGO="Código da Ação">Título da Ação</CAMPANHA>

...

</CAMPANHAS_ATUALIZADAS>

</EMKT>

</MAIN>

24

15.55 Informações da Mensagem

Utilize essa integração quando desejar informações de uma determinada ação como, por exemplo, data de criação, os links adicionais ou inseridos, o HTML, entre outros. Envio: <main>



</emkt>

</main>

Retorno:

<main>


<mensagem>



<html>[CONTEUDO DA MENSAGEM]</html>

<texto_alternativo>[TEXTO ALTERNATIVO]</texto_alternativo>

<texto_optout>[TEXTO DA MENSAGEM DE OPTOUT]</texto_optout>

<texto_visalternativa>[TEXTO DA MENSAGEM DE VISUALIZACAO ALTERNATIVA]</texto_visalternativa>

<texto_encaminhamento>[TEXTO DA MENSAGEM DE ENCAMINHAMENTO]</texto_encaminhamento>

<texto_altcadastro>[TEXTO DA MENSAGEM DE ALTERAÇÃO DE CADASTRO]</texto_altcadastro>

<anexo>[NOME DO ARQUIVO]</anexo>

<anexo>(...)</anexo>

<link MONITORADO="[S/N]" OPTOUT="[S/N]" VISALTERNATIVA="[S/N]" ENCAMINHAR="[S/N]" ALTCADASTRO="[S/N]">

<titulo>[TITULO DO LINK]</titulo>

<url>[URL DO LINK]</url>

</link>

<link>

(...)

</link>

</mensagem>

</emkt>

</main>

19 - Controle de Ações 19.03 – Retornar o nome das ações Transacionais do sistema

Utilize essa integração quando desejar listar as ações transacionais presentes na ferramenta.

Envio:

<main>

<emkt trans=”19.03”>

</emkt>

</main>

Retorno:

<main>

<emkt trans=”19.03” key= “XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX”>

<ACAO ID=”[ID]”> [NOME_DA_ACAO_TRANSACIONAL]</ACAO>



(...)

</emkt>

</main>

• ID – Número Identificador da ação Transacional.

25

19.04 - Inclusão de uma Ação Transacional Uma ação transacional é um tipo de ação que é disparada sobre demanda ela não possui uma lista vinculada ao receber o contato dispara. Utilize essa integração para criar esse tipo de ação na ferramenta. Para inserir contatos na mesma utilize a integração 20.05 desse documento. Envio:

<main>


<nome>[NOME DA ACAO]</nome>

<mensagem url="true">[NOME OU LINK DA MENSAGEM]</mensagem>

<usuario>[E-MAIL USUARIO]</usuario>

<opcao>


<area_interesse>[ÁREA DE INTERESSE]</area_interesse>

<marca_envio>[ENVIAR SOMENTE QUANDO A MENSAGEM CONTIVER]</marca_envio> </opcao> <nome_remetente>[NOME DO REMETENTE]</nome_remetente>

<email_remetente>[EMAIL DO REMETENTE]</email_remetente>

<email_retorno>[EMAIL PARA RETORNO]</email_retorno>

<assunto>[ASSUNTO]</assunto>

<remocao tipo="SO/SC/CC" areainteresse="S/N" motivo="S/N" />

</emkt>

</main>

• Mensagem: Caso for utilizar uma URL o atributo deve ser indicado como TRUE. Segue exemplo abaixo

do formato:

<mensagem url="true"><![CDATA[ URL ]]></mensagem>

Quando utilizar URL o campo MARCA_ENVIO é obrigatório. • Usuário: Este campo contém o e-mail do usuário a quem pertence à ação. • Nome/E-mail do Remetente: É o nome e e-mail exibido como remetente da ação. • E-mail de retorno: É o e-mail que aparece quando o contato clica em responder no seu programa de e-

mail. • E-mail de término: É o e-mail ou lista de e-mails separados por ';' (ponto e vírgula) que informarão sobre

o término da ação. •

Remoção: Possui três atributos: tipo:

Sem Optout (SO): Envia mesmo para contatos com o status de opt-out e não exibe o link para solicitação de opt-out . Sem Confirmação (SC): Realiza opt-out direto. Com Confirmação (CC): É necessário confirmar o pedido de opt-out. Para habilitar 'área de interesse ou remoção' na solicitação de optout é obrigatório o tipo estar com o valor (CC). areainteresse: Solicita a área de interesse no pedido de remoção. motivo: Solicita que o contato informe o motivo do pedido de remoção. Retorno:

<main>



</emkt>

</main>

26

19.05 - Inclusão de uma Ação Pontual

Utilize essa integração quando desejar criar uma ação do tipo pontual. Você poderá escolher entre apenas criar a ação ou criar e já agendar. Se optar por já agendar o envio será obrigatório à inclusão da lista também. Verifique que tanto a linha do agendamento quanto da inclusão da lista no XML abaixo são obrigatórios.

Envio: <main>


<nome>[NOME DA ACAO]</nome>

<mensagem url="true">[NOME OU LINK DA MENSAGEM]</mensagem>

<usuario>[E-MAIL USUARIO]</usuario>

<opcao>

<idioma>[SIGLA DO IDIOMA]</idioma>

<area_interesse>[ÁREA DE INTERESSE]</area_interesse>

<marca_envio>[ENVIAR SOMENTE QUANDO A MENSAGEM CONTIVER]</marca_envio> </opcao> <data_encerramento>[AAAA-MM-DD]</data_encerramento>

<nome_remetente>[NOME DO REMETENTE]</nome_remetente>

<email_remetente>[EMAIL DO REMETENTE]</email_remetente>

<email_retorno>[EMAIL PARA RETORNO]</email_retorno>

<assunto>[ASSUNTO]</assunto>

<email_termino>[EMAIL DE TERMINO]</email_termino>

<solicita_motivo>[S/N]</solicita_motivo>



(...)

<filtro type="avancado">

<grupo tipo="[E/OU]">

<regra campo="[CAMPO]" operador="[TIPO_DE_OPERADOR]" valor1="[VALOR1]" valor2="[VALOR2]" />

</grupo>

</filtro>

<agendar>

<datahora>YYYY-MM-DD HH:MM:SS</datahora>

</agendar>

</emkt>

</main>

• Mensagem: Caso for utilizar uma URL o atributo deve ser indicado como TRUE. Segue exemplo

abaixo do formato: <mensagem url="true"><![CDATA[ URL ]]></mensagem>

Quando utilizar URL o campo MARCA_ENVIO é obrigatório.

• Usuario: Este campo contém o e-mail do usuário a quem pertence à ação.

• Data de Encerramento: É a data limite que o sistema vai contabilizar as informações (visualização, cliques, opt-out, etc). O período pode ser de cinco dias a seis meses após a data de envio.

• Nome/E-mail do Remetente: É o nome e e-mail exibido como remetente da ação.

• E-mail de retorno: É o e-mail que aparece quando o contato clica em responder no seu programa

de e-mail.

• E-mail de término: É o e-mail ou lista de e-mails separados por ';' (ponto e vírgula) que informarão sobre o término da ação.

• Solicita Motivo: Informa se deve solicitar o motivo de remoção no momento que o contato faz o opt-out.

ATENÇÃO: Lembre-se da recomendação inicial desse documento. Use a ação pontual apenas se ela for única. Se essa ação se repetir com frequência utilize a ação transacional. Integração 20.05 desse manual.

27

• Filtro: Para montar um filtro é preciso passar pelo menos um grupo com o seu tipo de operador e uma regra que deverá conter, campo, operador e valor(es). Para lógicas mais precisas, pode ser adicionado um grupo dentro de outro.

Os atributos que devem ser adicionados são:

Grupo: tipo -> E/OU Regra: campo -> nome do campo (vide abaixo padrao). operador -> tipo de operador (vide abaixo padrao). valor1(ou somente valor) -> primeiro ou unico valor desejado. valor2 -> segundo valor desejado, somente se for preciso usar dois valores (ex: entre 15 e 20).

Os valores que podem ser passados:

Campo - os nomes dos campos baseado no padrão do Email Marketing, seguindo a nomemenclatura: email, sexo, idade, data_nascimento, empresa, cpf, atividade, profissao, tipoend(Tipo de endereço), endereco, complemento, bairro, cidade, estado,pais, cep, telefone1, telefone2, telefone3, fax, data_validade.

Ou os campos adicionais, seguindo o padrão ca1, ca2, ca3, … ca20

Operador - lista dos valores que podem ser usados para todos os campos: igual, diferente, contém, não contém, começa com, termina com.

Com exceção dos seguintes campos, que tem operador(es) únicos: Sexo: é Estado: é, não é Idade e CEP: está entre

Exemplo de uso do filtro Para montar um filtro com as seguintes regras:

"O email não seja do yahoo.com ou gmail.com, e que tenha de 18 a 25, ou seja do sexo Feminino, ou que seja de estado de São Paulo, mas que não seja da cidade de Piracaia"

Esse filtro será montado da seguinte maneira:

<filtro type="avancado"> <grupo tipo="e"> <regra campo="email" operador="não contém" valor="yahoo.com" /> <regra campo="email" operador="não contém" valor="gmail.com" /> <grupo tipo="ou"> <regra campo="idade" operador="está entre" valor1="18" valor2="25" /> <regra campo="sexo" operador="igual" valor="F" /> <grupo tipo="e"> <regra campo="estado" operador="igual" valor="SP" /> <regra campo="cidade" operador="diferente" valor="Piracaia" /> </grupo> </grupo> </grupo> </filtro>

• Agendar: Tag utilizada para que após a inclusão da ação a mesma seja agendada para horário

especifícado. A utilização desta tag equivale à utilização da integração 19.06. • Data/Hora: Data e Hora de envio da ação. Este campo deve ser informado no formato AAAA-MM-

DD HH:MM:SS. Quando a tag Agendar é utilizada este campo é obrigatório. Retorno:

<main>


<return id="00">Ok</return </emkt>

</main>

28

19.06 - Agendamentos de Envio da Ação Utilize essa integração quando desejar agendar uma ação pontual. Se desejar o agendamento pode já ocorrer na integração de criação da ação (19.05).

Envio:

<main>


<titulo>[NOME DA AÇÃO]</titulo>

<datahora>AAAA-MM-DD HH:MM:SS</datahora>

<menosde>[NÃO ENVIAR EM MENOS DE X HORAS]</menosde>

<totalparcial>[NUMERO DE ENVIOS NO DISPARO]</totalparcial>

<reiniciar>[REINICIAR O ENVIO APÓS X HORAS]</reiniciar>

<envio_complementar>[S/N]</envio_complementar>

</emkt>

</main>

• Data/Hora: O campo “datahora” deve ser enviado no formato informado. Para cancelar um

agendamento feito anteriormente envie 0000-00-00 00:00:00 no campo.

• Menos de: O campo “menosde” deve ter o número de horas mínimas que o disparo deverá durar. • Total Parcial: Quantidade de e-mails a ser enviada por disparo.

• Reiniciar: Agenda um reenvio dos e-mails restantes após X horas do último e-mail enviado no último

disparo.

• Envio Complementar: A ferramenta faz um reenvio após 24 horas do disparo da ação para os contatos que ainda não interagiram.

Certifique-se que a ação possua contatos antes de agendar o envio.

Retorno:

<main>



</emkt>

</main>

19.07 - Envio de E-mail de Teste da Ação

Utilize essa integração quando desejar enviar um teste da ação antes do disparo da mesma. Os testes não consomem créditos porem poderá enviar apenas para até 10 endereços de e-mail. Envio: <main>



<assunto_teste>[S]</assunto_teste>



( ... )

</emkt>

</main>

Dica: assunto_teste: Se tiver “S” neste campo será inserido o texto "[Teste]" no início do assunto da mensagem facilita para quem receberá o teste.

29

Retorno:

<main>



</emkt>

</main>

19.10 - Estatísticas das Ações em um Determinado Período

Utilize essa integração quando desejar receber informações sobre as estatísticas das ações em um determinado período. Serão retornadas informações como nome da a cão, remetente, os destinatários e o status dos mesmos para a ação em questão.

Envio:

<main>


<datainicial>AAAA-MM-DD HH:MM:SS</datainicial>

<datafinal>AAAA-MM-DD HH:MM:SS</datafinal>

</emkt>

</main>

Retorno:

<main>



<campanha>

<codigo>[CODIGO]</codigo>

<nome>[NOME]</nome>

<email>[REMETENTE]</email>

<destinatario codigo="[CODIGO]" clicado="[S/N]">[EMAIL]</destinatario>

<destinatario codigo="[CODIGO1]" clicado="[S/N]">[EMAIL2]</destinatario>

(...)

</campanha>

<campanha>

(...)

</campanha>

(...)

</emkt>

</main>

19.11 - Totais da Ação Utilize essa integração quando desejar receber informações sobre os totais como por exemplo, total de destinatário, total de enviada, total de erros, entre outros. Envio:

<main>



</emkt>

</main>

30

Retorno:

<main>



<campanha>

<totaldestinatarios>[TOTAL DE DESTINATARIOS]</totaldestinatarios>

<totalenviado>[TOTAL ENVIADO]</totalenviado>

<totalentregue>[TOTAL ENTREGUE]</totalentregue>

<totalerros>[TOTAL DE ERROS]</totalerros>

<totalvisualizacao>[TOTAL DE VISUALIZAÇÕES]</totalvisualizacao>

<totalindicacoes>[TOTAL DE INDICAÇÕES]</totalindicacoes>

<totalremocoes>[TOTAL DE PEDIDOS DE REMOÇÃO]</totalremocoes>

<totalclicks>[TOTAL DE CLICKS]</totalclicks>

<link>


<unicos>[TOTAL DE CLICKS UNICOS]</unicos>

<total>[TOTAL DE CLICKS]</total>

</link>

(...)

<erro>

<titulo>[TIPO DE ERRO]</titulo>

<total>[TOTAL DE ERROS]</total>

</erro>

(...)

</campanha>

</emkt>

</main>

19.31- Contatos que Visualizaram a Ação Utilize essa integração quando desejar uma lista dos endereços de e-mail que abriram a mensagem.

Envio:

<main>


<titulo>[NOME DA AÇAO]</titulo>

</emkt>

</main>

Retorno: <main>



<campanha>


(...)

</campanha>

</emkt>

</main>

19.55 - Informações da Ação Utilize essa integração quando desejar informações de uma determinada ação, como por exemplo, os dados do remetente, quantidade de enviados, se os links estão sendo monitorados, entre outros. Envio:

<main>


<titulo>[TITULO DA AÇÃO]</titulo>

</emkt>

</main>

31

Retorno:

<main>


<acao>


<criacao>AAAA-MM-DD</criacao>

<remetente>

<nome>[NOME DO REMETENTE]</nome>

<email>[E-MAIL DO REMETENTE]</email>

<retorno>[E-MAIL DE RETORNO]</retorno>

</remetente>

<campanha>[CAMPANHA DA AÇÃO]</campanha>

<mensagem>

<titulo>[TITULO DA MENSAGEM UTILIZADA]</titulo>

<url>[URL DE ORIGEM DA MENSAGEM]</url>

<html>[CONTEUDO DA MENSAGEM]</html>

<texto_alternativo>[TEXTO ALTERNATIVO]</texto_alternativo>

<texto_optout>[TEXTO DA MENSAGEM DE OPTOUT]</texto_optout>

<texto_visalternativa>[TEXTO DA MENSAGEM DE VISUALIZACAO ALTERNATIVA]</texto_visalternativa>

<texto_encaminhamento>[TEXTO DA MENSAGEM DE ENCAMINHAMENTO]</texto_encaminhamento>

<texto_altcadastro>[TEXTO DA MENSAGEM DE ALTERAÇÃO DE CADASTRO]</texto_altcadastro>

<anexo>[NOME DO ARQUIVO]</anexo>

<anexo>(...)</anexo>

<link MONITORADO="[S/N]" OPTOUT="[S/N]" VISALTERNATIVA="[S/N]" ENCAMINHAR="[S/N]"

ALTCADASTRO="[S/N]">


<url>[URL DO LINK]</url>

</link>

<link>

(...)

</link>

</mensagem>

<area_interesse>[AREA DE INTERESSE]</area_interesse>

<envio>AAAA-MM-DD HH:MM:SS</envio>

<reenvio>AAAA-MM-DD HH:MM:SS</reenvio>

<contatos>

<total>[TOTAL DE CONTATOS DA AÇÃO]</total>

<enviado>[TOTAL DE ENVIOS]</enviado>

</contatos>

</acao>

</emkt>

</main>

19.80 - Lista de e-mails inválidos da Ação

Utilize essa integração quando desejar listas os contatos invalidados na ação em questão. Envio:

<main>



</emkt>

</main>

Retorno:

<main>



<campanha>

<codigo>[CODIGO]</codigo>

<nome>[NOME]</nome>

<email>[REMETENTE]</email>

<destinatario codigo="[CODIGO]">[EMAIL]</destinatario>

<destinatario codigo="[CODIGO1]">[EMAIL2]</destinatario>

(...)

</campanha>

</emkt>

</main>

32

20 - Alterações de Listas das Ações

20.01 - Inclusão de Contatos Direto em uma Ação Sem o Envio Imediato Utilize essa integração quando desejar inserir contatos em ação do tipo pontual que ainda não possui uma lista de contatos nem agendamento do envio. Envio: <main>


<acao>[TITULO DA AÇÃO]</acao>

<indice>[E/C]</indice>


<nome>[NOME]</nome>


<sexo>[SEXO]</sexo>




<cpf>[CPF]</cpf>









<pais>[PAIS]</pais>

<cep>[CEP]</Cep>




<fax>[FAX]</fax>






















</destinatario>


(...)

</destinatario>

</emkt> </main>

Índice: (o valor padrão é E) • E = quando o e-mail é o da lista, ou seja, esse campo não se repete. • C = quando o índice for um código externo, por exemplo, RA do aluno e nesse caso o campo e-mail

pode se repetir porem o campo RA não poderá. Todos os campos do destinatário exceto e-mail são de uso opcional, portanto a omissão de <nome></nome> por exemplo, pode ser feita sem problemas. A Ação que será utilizada não pode estar com a data de encerramento menor que a data atual. Para o envio da ação com os novos endereços cadastrados é necessário chamar a integração 19.06 (agenda uma ação do tipo pontual).

33

Retorno:

<main>



<return id="99">


( … )

<FALHA_INSERIR>[EMAIL]</FALHA_INSERIR>

( … )

<EMAIL_OPTOUT MENSAGEM="[MENSAGEM]">[EMAIL]</EMAIL_OPTOUT>

( … )

</return>

</emkt>

</main>

ATENÇÃO: O arquivo de retorno poderá eventualmente apresentar uma lista de e-mails que foram considerados inválidos pelo sistema na tag EMAIL_INVALIDO. Também poderá ocorrer erro de inserção do contato, este tipo de erro será retornado na tag FALHA_INSERIR. Será feita uma checagem para verificar se o endereço de e-mail passado é opt-out para a “área de interesse” desta ação. Caso seja constatado que ele é opt-out para a mesma, ou se ele for para todas as “áreas de interesses” não será possível o envio para este endereço de e-mail. Neste caso o email será apresentado na tag EMAIL_OPTOUT e no atributo MENSAGEM será apresentado a área de interesse que o contato é opt-out. Mesmo que ocorrera qualquer um dos erros acima mencionado a API irá fazer a inserção de todos os e-mails válidos.

34

20.05 Disparando uma Ação Transacional

Uma ação transacional é um tipo de ação que é disparada sobre demanda ela não possui uma lista vinculada ao receber o contato dispara. Utilize essa integração para inserir contato em uma ação já criada na ferramenta. Você poderá cria-la manualmente acessando a ferramenta ou utilizar a integração 19.04 desse documento. Envio:

<main>




<envio_minutos>[MINUTOS]</envio_minutos>


<nome>[NOME]</nome>


<sexo>[SEXO]</sexo>




<cpf>[CPF]</cpf>









<pais>[PAIS]</pais>

<cep>[CEP]</cep>




<fax>[FAX]</fax>






















</destinatario>


(...)

</destinatario>

(...)

</emkt>

</main>

Retorno:

<main>



<return id="99">


( … )

<FALHA_INSERIR>[EMAIL]</FALHA_INSERIR>

( … )

</return>

</emkt>

</main>

35

20.10 - Importação de Arquivo para a Ação

Utilize essa integração quando desejar importar um arquivo contendo os contatos para uma ação do tipo pontual.

Envio:

<main>




<envio>0000-00-00 00:00</envio>

<arquivo>[URL DO ARQUIVO]</arquivo>

<separador>[SEPARADOR]</separador>

<opcoes cabecalho="[S/N]" reenviar="[S/N]" />

<campos>

<email col="[NUMERO DA COLUNA]" />

<nome 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]" />




<fax col=20) Alterações de listas das ações"[NUMERO DA COLUNA]" />





















</campos>

</emkt>

</main>

Índice: (o valor padrão é E) • E = quando o e-mail é o da lista, ou seja, esse campo não se repete. • C = quando o índice for um código externo, por exemplo, RA do aluno e nesse caso o campo e-mail

pode se repetir porem o campo RA não poderá.

ATENÇÃO: O arquivo de retorno poderá eventualmente apresentar uma lista de e-mails que foram considerados inválidos pelo sistema na tag EMAIL_INVALIDO. Também poderá ocorrer erro de inserção do contato, este tipo de erro será retornado na tag FALHA_INSERIR. Mesmo que ocorrera qualquer um dos erros acima mencionado a API irá fazer a inserção de todos os e-mails válidos.

36

Envio: É a data/hora de envio da ação, caso não seja informada ela é agendada para ser enviada 5 minutos após a requisição. 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 Texto. O arquivo no formato ZIP deve conter somente um arquivo dentro no formato XLS, CSV ou Texto.

Exemplo: ftps://user:[email protected]/pasta/arquivo.zip Separador: O caractere que separa as colunas do arquivo. No formato Excel esse campo não é obrigatório. Opções: • Cabeçalho: Informa se o arquivo a ser importado tem cabeçalho. • Reenvio: Informa se o mesmo contato pode receber mais de uma vez essa mesma ação. *Todos os campos exceto e-mail são opcionais, portanto, a omissão das demais colunas podem ser feita sem problemas. Retorno:

<main>



</emkt>

</main>

20.11 - Situação de Importação de Arquivo para a Ação (20.10) Utilize essa integração para consultar como está o processo de importação de contatos para ação quando utilizada a integração 20.10. Envio:

<main>



</emkt>

</main>

Retorno:

<main>




<resultado>


<acao>[NOME DA LISTA]</acao>

<arquivo>[NOME DO ARQUIVO]</arquivo>

<linhas>[LINHAS NO ARQUIVO]</linhas>

<duplicados>[CONTATOS DUPLICADOS NO ARQUIVO]</duplicados>

<inseridos>[CONTATOS INSERIDOS]</inseridos>

<atualizados>[CONTATOS ATUALIZADOS]</atualizados>

<cadastrados>[CONTATOS JÁ CADASTRADOS]</cadastrados>

<validos_antes>[CONTATOS ANTES DA IMPORTAÇÃO]</validos_antes>

<validos_apos>[CONTATOS APÓS IMPORTAÇÃO]</validos_apos>

</resultado>

</emkt>

</main>

ftp://user:[email protected]/pasta/arquivo.zip

37

30.05 Inserindo contatos em uma automação Utilize essa integração para inserir contato diretamente em uma régua de relacionamento (automação). Passos para implementar: 1 – Criar o fluxo na plataforma Akna. 2- Obter o campo <automacao>. Esse campo deve ser preenchido com um “hash” encontrado na plataforma.

Caminho para obter o “hash”: Em automações cadastradas. Edite a automação que deseja fazer a integração. No campo importar listas escolha a opção “Importar via API”.

38

Envio:

Retorno:

<main>


<automacao>[HASH]</automacao>

<destinatario>

<nome>[NOME]</nome>


<sexo>[SEXO]</sexo>




<cpf>[CPF]</cpf>









<pais>[PAIS]</pais>

<cep>[CEP]</Cep>




<celular>[CELULAR]</celular>

<fax>[FAX]</fax>





















</destinatario>

<destinatario>

(...)

</destinatario>

(...)

</emkt>

</main>

<MAIN>

<EMKT TRANS="30.05" KEY="0a0001745188308e7d3c515bfd3d">

<RETURN ID="00">Ok</RETURN>

</EMKT>

</MAIN>

39

40 - Disparo de ações SMS Corporativo (Transacional) 40.01 Cadastrar Ação de SMS Corporativo Utilize essa integração para enviar um SMS para os contatos Envio:

<main>


<remetente></remetente>

<identificador></identificador>

<encurtar_url>S</encurtar_url>

<sms>

<telefone></telefone>

<mensagem></mensagem>

</sms>

<sms>

<telefone></telefone>

<mensagem></mensagem>

</sms>

</emkt>

</main>

Remetente: Remetente cadastrado na plataforma para envio de mensagens SMS. Esse campo é obrigatório para envio SMS somente se existir mais de um remetente cadastrado na plataforma. Identificador: Código alfanumérico com até treze caracteres para identificar a integração. No caso de não ser enviado será gerado automaticamente e não é obrigatório. Encurtar URL: Esta tag precisa ser usada (valor ‘S’) para que o link possa ser rastreado. Telefone: Telefone do contato. Campo obrigatório e deve ser enviado no seguinte formato DDD + Número do telefone. Exemplo: "11977777777" Mensagem: Mensagem a ser enviada ao contato. * Todos os campos são obrigatórios, exceto o campo 'remetente' e identificador. No caso do remetente nas condições anteriormente ditas, a omissão destes pode fazer com que a mensagem não seja enviada. Retorno: <MAIN>

<EMKT TRANS="40.01" KEY="0950014941cbc070d30aee01e982">

<RETURN ID="00">5672fa9f43cea</RETURN>

</EMKT>

</MAIN>

40.02 - Consultar o Status do Envio

Utilize essa integração para consultar o status dos envios após executar a integração 40.01. Envio:

<main>


<sms>

<codigo>5672fa9f43cea</codigo>

</sms>

</emkt>

</main>

ATENÇÃO: O Valor informado na tag RETURN é necessário para a utilização das Integrações 40.02 e 40.03

40

O código é o valor informado na integração 40.01 Retorno:

<MAIN>

<EMKT TRANS="40.02" KEY="0c0001f53cbaa770d631a8f9f98e">

<SMS>

<TELEFONE>[NÚMERO DO TELEFONE]</TELEFONE>

<STATUS>[SITUAÇÃO DO ENVIO]</STATUS>

</SMS>

</EMKT>

</MAIN>

40.03 Consultar as Respostas dos Destinatários

Utilize essa integração para consultar as respostas dos contatos que receberam o SMS enviado através da integração 40.01.

Envio:

<main>


<sms>

<codigo>5672fa9f43cea</codigo>

</sms>

</emkt>

</main>

O código é o valor informado na integração 40.01

Retorno:

<MAIN>

<EMKT TRANS="40.03" KEY="09000114b58c4170d5657f4889a0">

<SMS>

<TELEFONE>[TELEFONE DO DESTINATÁRIO]</TELEFONE>

<MENSAGEM>[MENSAGEM ENVIADA PELO DESTINATÁRIO]</MENSAGEM>

<DATA_RECEBIMENTO>AAAA-MM-DD HH:MM:SS</DATA_RECEBIMENTO>

</SMS>

</EMKT>

</MAIN>

40.04 Solicitação de relatório de cliques de SMS transacional

Utilize essa integração para consultar os cliques dos contatos que receberam o SMS enviado através da integração 40.01.

Envio: <main>


<sms>

<identificador>[identificador1],[identificador2], ...</identificador>

<telefone>[telefone1],[telefone2], ...</telefone>

<envio>

<inicio>2020-01-03 12:00:00</inicio>

<fim>2020-01-03 12:30:00</fim>

</envio>

<clique>

<inicio>2020-01-03 10:00:00</inicio>

<fim>2020-01-03 11:00:00</fim>

</clique>

</sms>

ATENÇÃO: Os status podem sofrer alteração até o final do dia.

41

</emkt>

</main>

As tags de envio ou clique, é obrigatório apenas uma das duas opções, ou seja, caso seja informado o clique não preciso informar o envio e caso seja informado o envio não preciso informar o clique (é possível informar ambas caso o cliente queria.

Os períodos informados não podem ser maiores que 48 horas.

Retorno:

<main>



</emkt>

</main>

40.05 Acompanhar o progresso da geração do relatório

Utilize essa integração para consultar o processo de geração do relatório solicitado na integração 40.04

Envio:

<main>



</emkt>

</main>

Retorno:

<main>




<resultado>


</resultado>

</emkt>

</main>

40.06 Realizar o download arquivo zipado (.zip)

Utilize essa integração para fazer o download do arquivo gerado na integração 40.04

Envio:

<main>


<processo>00ccc3b7dcd22dd396d39b5e665a22a1</processo>

</emkt>

</main>

manual de integraÇÃo - akna.infoakna.info/.../aktr02010003001_manual_de_integracao...2 sumário o...

Documents