Ploomes conta com a funcionalidade de Webhooks. Para contextualizar, um Webhook é um meio pelo qual um sistema fornecer informações em tempo real para outras aplicações ou serviços. Por exemplo: sempre que uma venda for cadastrada no Ploomes, enviar os dados para um ERP.
Como habilitar
Para habilitar os Webhooks na sua conta, é necessário fazer uso da API do Ploomes. O primeiro passo é registrar um endpoint para receber dados quando uma determinada ação no Ploomes acontecer. Um endpoint é simplesmente um endereço acessível por HTTP, pode ser um Webservice ou uma API própria ou de terceiros. Uma ação pode ser, por exemplo:
Cadastrar um cliente
Atualizar uma proposta
Finalizar uma tarefa
Excluir um Lead
Para realizar o registro, basta fazer um POST no seguinte endereço:
https://api2.ploomes.com/Webhooks
É necessário utilizar sua chave de integração no Header da requisição, na forma de um parâmetro 'User-Key' e o corpo da requisição deve contar os seguintes atributos:
{
"EntityId": 1,
"ActionId": 2,
"CallbackUrl": "sua_url_de_recebimento",
"ValidationKey": "1234"
}
O exemplo acima vai fazer com que dados sejam disparados para um determinado endereço sempre que um Cliente for atualizado.
Parâmetros
Abaixo a explicação para cada atributo:
EntityId: a entidade que você deseja utilizar. Uma entidade pode ser um Cliente, um Negócio, uma Proposta, Lead, Tarefa, entre outros. O link abaixo leva para um artigo com informações sobre todas as entidades disponíveis:
Como identificar todos os campos (padrões e customizados) e suas chaves no Ploomes para desenvolvimento através da API
ActionId: o ID da ação. Uma ação pode ser, por exemplo, criação, deleção, atualização ou ações específicas para algumas entidades, como no caso de Negócios que podem ser Ganhos, Perdidos e Reabertos e Tarefas que podem ser finalizadas. Para saber quais as ações disponíveis, basta dar um GET no seguinte endereço (sempre se lembre da chave do usuário no Header):
https://public-api2.ploomes.com/Webhooks@Actions
CallbackUrl: a URL (endereço WEB) que receberá os dados enviados pelos Webhooks do Ploomes
ValidationKey: uma chave que pode ser criada (inventada) e usada no endereço que vai receber os dados do Ploomes. Com ela, é possível validar se as requisições estão sendo enviadas pelo Ploomes mesmo e rejeitar as demais, no caso de alguém descobrir seu serviço e tentar algum ataque, por exemplo.
Na mensagem enviada, a chave de validação (ValidationKey) estará no Header com o nome X-Ploomes-Validation-Key
Corpo do Payload (exemplo)
______________________________________________________
Body:
{
"Action": "Update",
"Entity": "Contacts",
"AccountId": 57,
"ActionUserId": 116,
"Old":
{
"OtherProperties": {
"contact_check": false //CAMPOS CUSTOMIZÁVEIS DA CONTA
},
"Phones": [
{
"PhoneNumber": "(11) 3842-6673",
"TypeId": 1,
"CountryId": 76
}
],
"Tags": [
{
"TagId": 290
}
],
"Id": 2630362,
"LegalName": "Ploomes",
},
"New":
{
"OtherProperties": {
"contact_check": true
},
"Phones": [
{
"PhoneNumber": "(11) 4380-7749",
"TypeId": 1,
"CountryId": 76
}
],
"Tags": [
{
"TagId": 287
}
],
"Id": 2630362,
"LegalName": "Ploomes Sistemas Empresariais",
}
}
______________________________________________________
Análise do payload
"Action": "Update", --> Atualização
"Entity": "Contacts", --> de Contato
"AccountId": 57, --> ID da conta Ploomes
"ActionUserId": 116, --> ID do usuário que gerou a ação (atualizou o contato)
Old --> Detalhes de como eram os campos ANTES da atualização - somente os campos alterados são retornados. Pode ser NULL caso seja uma Criação.
New --> Detalhes dos valores dos campos DEPOIS da atualização.
Com o atributo ActionUserId e os objetos OLD e NEW é possível identificar os valores antes e depois de cada alteração e com isso fazer tratativas específicas para cada caso.
Exemplo de caso de uso: Se um usuário (ActionUserId) da equipe financeira editar o campo 'Análise de crédito concluída' de Falso para Verdadeiro, enviar um e-mail para o responsável pelo Negócio informando que a análise foi concluída e agora o processo comercial pode prosseguir.
Para acessar obter acesso à API do Ploomes, acesse o link abaixo:
Como obter acesso à API do Ploomes
Caso tenha dúvidas sobre a utilização dos Webhooks ou precisar de informações adicionais, nossa equipe de suporte estará sempre à disposição para ajudar.