O Zenvia Attraction também possibilita o uso do gestor de contatos através da sua API. Neste documento vamos ver o conceito básico e mostrar as funcionalidades disponibilizadas pela API de gestão de contatos do Zenvia Attraction.

O que é uma API e como usá-la

A sigla API significa Application Programming Interface. Em resumo, trata-se de um tipo de aplicação que fornece um meio pelo qual dois sistemas são conectados e interagem trocando dados específicos. A API atua enviando recursos passados pelo usuário a um determinado servidor ou sistema, e, após essa etapa, a ponta externa dessa comunicação responde com os dados necessários para oferecer determinado serviço ao usuário.

Exemplo: Por meio da comunicação da API do Zenvia Attraction com os servidores da Zenvia, um usuário pode criar ou colocar destinatários em uma lista de contatos.

Por estes fatores, quando falamos em API tendemos a citar endpoints, que representam uma das pontas de comunicação entre a interface e o servidor externo. Graças a essa característica, as APIs possuem o benefício de economizar os recursos do usuário, uma vez que elas não rodam localmente na máquina do usuário e só utilizam a resposta do servidor para prover as informações necessárias.

Em resumo, uma API é simplesmente uma aplicação que troca informações entre um sistema externo e um usuário. 

Benefícios de uma API

A seguir, veja alguns dos benefícios de uma API:

Integração simples

Como a API não roda localmente na máquina do usuário, os recursos necessários para seu funcionamento também são menores, o que também permite um processo de integração mais simples e ágil.

Rápida implementação

A implementação ágil e fácil customização acabam colaborando significativamente em simplificar também o processo de desenvolvimento e permitir que resultados práticos sejam atingidos em menor tempo hábil.

Dados encapsulados

Como a API disponibiliza apenas uma ponta da comunicação para o usuário e funciona enviando e recebendo uma representação dos recursos necessários para seu funcionamento, toda essa comunicação acaba sendo encapsulada, o que aprimora a segurança e a confidencialidade dos dados.

A API para gestão de contatos do Zenvia Attraction

A API oferece as mesmas funcionalidades do painel de gestão de contatos do Zenvia Attraction, permitindo agrupar seus contatos em uma lista para utilizá-los como público-alvo para suas campanhas.

💡 Dica: Para mais informações sobre o painel de gestão de contatos, confira o artigo Gerenciar contatos no Zenvia Attraction.

A seguir vamos detalhar como utilizar a documentação API da ZenAPI para integrar a API de gestão de contatos.

Como a ZenAPI funciona

Primeiramente, acesse a documentação da ZenAPI e localize Contacts no menu à esquerda, todas as documentações que estão abaixo desta categoria são referentes à API de gestão de contatos do Zenvia Attraction.

Neste exemplo, vamos detalhar a primeira ação, o Create a new contact.

O próximo passo para usar a API é efetuar a autenticação.

Como funciona a autenticação da API

Para utilizar a API será necessário passar um token de autorização, sendo eles:

• Token JWT usado pelo serviço Front-End da Zenvia;
• X-API-Token passado no parâmetro do Header.

É possível encontrá-los neste local da documentação: 

Dentre esses dois, recomendamos principalmente o X-API-Token pelos seus benefícios à segurança, uma vez que caso seja necessário, você pode simplesmente revogar o acesso facilmente por meio do painel de Tokens e Webhooks no menu Desenvolvedores da Plataforma Zenvia. Além disso, para criar um novo Token, basta clicar em Criar novo, na mesma tela:

Note que, para realizar qualquer uma das ações disponíveis, é necessário enviar o token no cabeçalho HTTP 'X-API-TOKEN'.

Exemplo: X-API-TOKEN: hKp94crjv9OF3UGrCpSXUJw1-UYHhRvLKNLt

A seguir vamos falar sobre os métodos e como fazer uma requisição no corpo

Como fazer uma requisição

Para fazer a criação de um novo contato, o desenvolvedor precisará usar o método da ação na URL. No nosso caso, seria o método POST.

Assim sendo, ele precisará fazer o método POST na URL https://api.zenvia.com/v2/contacts e passar no corpo da requisição o payload a seguir:

{

  "channels": {

    "email": "contact@domain.example",

    "mobile": "5510888883333",

    "landline": "551044443333"

  },

  "firstName": "Rafael",

  "lastName": "Souza",

  "customData": {

    "property1": "2022-06-13",

    "property2": "2022-06-13"

  },

  "addresses": [

    {

      "country": "Brazil",

      "zipcode": "01310-300",

      "state": "SP",

      "city": "São Paulo",

      "address": "Av. Paulista",

      "streetNumber": "2300",

      "neighborhood": "Bela Vista"

    }

  ],

  "listIds": [

    "list-id-01",

    "list-id-02",

    "list-id-03"

  ]

}

Para ter mais informações sobre cada componente do Payload, basta consultar a descrição localizada em Request body schema:

Nesta seção, está listado o que é cada campo, como eles devem ser passados e como o payload precisa ser passado nesta estrutura.

Agora que você já sabe como trabalhar com a API e como navegar na documentação, segue abaixo uma lista de todas as funcionalidades disponíveis no gestor de contatos do Zenvia Attraction e o link para a documentação que dá mais detalhes a respeito.

O que é possível fazer com a API

Utilizando a API de gestão de contatos do Zenvia Attraction, você pode:

• Criar contatos;
• Listar todos os contatos disponíveis;
• Recuperar as informações de um contato;
• Atualizar as informações de um contato;
• Excluir um contato;
• Criar listas de contatos;
• Listar todas as listas de contatos disponíveis;
• Recuperar as informações de uma lista de contatos;
• Atualizar as informações de uma lista de contatos;
• Excluir uma lista de contatos (Apenas a lista é excluída, não os contatos);
• Listar os contatos de uma lista de contatos;
• Criar campos de dados personalizados para serem utilizados na API de contatos;
• Listar todos os campos de dados personalizados de contato disponíveis.

Pronto! Agora que você conheça a API do Zenvia Attraction, veja mais informações sobre o gestor de contatos.