A Zenvia Customer Cloud também possibilita o uso da Base de contatos através da sua API. Neste documento vamos ver o conceito básico e mostrar as funcionalidades disponibilizadas pela API de base de contatos da Zenvia Customer Cloud.
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 da Zenvia Customer Cloud 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.
API para Base de contatos da Zenvia Customer Cloud
A API oferece as mesmas funcionalidades do painel de base de contatos da Zenvia Customer Cloud, permitindo agrupar seus contatos em uma lista para utilizá-los como público-alvo para suas campanhas.
⚠️ Atenção: Esta funcionalidade está disponível apenas para usuários com o perfil de Administrador.
A seguir vamos detalhar como utilizar a documentação API da ZenAPI para integrar a API de base de contatos.
💡 Dica: Para mais informações sobre a base de contatos, confira o artigo Base de contatos na Zenvia Customer Cloud.
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 base de contatos da Zenvia Customer Cloud.
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.
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.
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": "[email protected]", "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 na base de contatos e o link para a documentação que dá mais detalhes a respeito.
O que é possível fazer com a API
Utilizando a API da base de contatos da Zenvia Customer Cloud, 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ê conhece a API de base de contatos da Zenvia Customer Cloud, veja mais informações sobre a base de contatos.