Obtendo dados do Pipedrive usando Python

Pipedrive é um sistema de CRM popular adotado por empresas de todos os portes. Na EximiaCo, utilizamos o PipeDrive para controlar a relação com nossos clientes.

O Pipedrive oferece uma API fácil de usar, baseada em HTTP.

Chave de acesso

Se você utiliza Pipedrive em sua organização e deseja interagir com seus dados, primeiro precisa obter a chave de acesso a API. Isso é fácil de fazer.

A chave pode ser encontrada nas configurações do aplicativo web do Pipedrive, em “Settings > Personal preferences > API“. É importante não compartilhar essa chave com ninguém que você não confie, pois ela dá acesso aos dados da sua conta.

Instalando as dependências

Para fazer uso da API, usaremos o pacote requests. Para poder tratar os dados, usaremos o pandas.

! pip install pandas requests

No código, é importante importar esses dois pacotes.

import pandas as pd
import requests

Obtendo os dados

Vamos então iniciar nossa cruzada por obtenção de dados do Pipedrive. Para começar, vamos escrever código genérico para interagir com endpoints chaves.

def fetch_pipedrive(api_token, entity, start = 0, params = {}):
    url = f"https://api.pipedrive.com/v1/{entity}"
    
    params['api_token'] = api_token
    params['limit'] = 500
    params['start'] = start

    response = requests.get(url, params=params)
    if response.status_code == 200:
        return response.json()
    else:
        return None
    
def convert_to_dataframe(source):
    if source and 'data' in source:
        df = pd.DataFrame(source['data'])
        return df
    else:
        return pd.DataFrame() 

Esse código busca informações a partir de um endpoint relevante dentro do Pipedrive. Abaixo a lista de referência:

1. Deals: Uma relação das negociações/oportunidades.
2. Persons: Usado para gerenciar informações sobre pessoas (contatos) no PipeDrive. Permite listar, criar, atualizar e deletar contatos.
3. Organizations: Similar ao endpoint de pessoas, mas focado em organizações. Você pode gerenciar informações sobre empresas e outras organizações que estão registradas no seu CRM.
4. Activities: Permite gerenciar atividades associadas aos negócios, como reuniões, chamadas, tarefas, e-mails, entre outros. É um componente crucial para o acompanhamento de interações com clientes.
5. Products: Usado para gerenciar os produtos que sua empresa oferece. Este endpoint permite listar produtos, associá-los a negócios, e gerenciar informações relacionadas a esses produtos.
6. Pipelines: Cada pipeline representa um conjunto de estágios que define um processo de vendas específico. Este endpoint permite manipular esses pipelines, que são essenciais para visualizar o fluxo de negócios.
7. Stages: Estágios de uma pipeline.
8. Webhooks: Permite configurar webhooks para eventos no PipeDrive, o que é útil para integrações em tempo real e reações automatizadas a mudanças no CRM.
9. Files: Gerencia arquivos associados a negócios, pessoas ou organizações. É possível fazer upload e download de arquivos, o que facilita a gestão documental integrada ao CRM.
10. Notes: Permite adicionar e gerenciar notas associadas a negócios, contatos e organizações. Notas são úteis para manter registros detalhados das interações e pensamentos relacionados aos clientes.
11. User: Para gerenciar informações sobre os usuários do sistema, como obter detalhes do usuário atualmente autenticado e listar todos os usuários da empresa.
12. Search: Um endpoint de busca que permite realizar buscas complexas e específicas através dos dados no PipeDrive, incluindo negócios, contatos, atividades e muito mais.

Por exemplo, o código abaixo resgata todas as pipelines definidas no Pipedrive da organização.

api_token = "SEU-API-TOKEN"
pipelines = convert_to_dataframe(fetch_pipedrive(api_token, "pipelines"))
pipelines

Obtendo listas completas de consultas paginadas

Um problema potencial da consulta que implementamos até aqui é o limite de elementos retornados em uma única cosulta. Atualmente, estamos buscando o total possível (500, que é restrição da própria Pipedrive).

A solução é iterar na busca enquanto houverem páginas novas.

def has_next_page(data):
    return data.get('additional_data', {}).get('pagination', {}).get('more_items_in_collection', False)

def fetch_next_page(api_token, entity, current_page):
    if not has_next_page(current_page):
        return None
    
    next_start = current_page.get('additional_data', {}).get('pagination', {}).get('next_start')
    return fetch_pipedrive(api_token, entity, next_start)
    
def get_all_deals(api_token):
    data = fetch_pipedrive(api_token, 'deals')
    df = convert_to_dataframe(data)
    while has_next_page(data):
        data = fetch_next_page(api_token, 'deals', data)
        other_df = convert_to_dataframe(data)
        df = pd.concat([df, other_df])
    return df

No exemplo acima, temos o código que recupera todos os deals no Pipedrive consolidando tudo em um único dataframe.

deals = get_all_deals(api_token)
deals

E é só o começo…

Com as informações em dataframes podemos qualificar os dados e fazer análises refinadas. O uso das APIs garante sempre os “dados quentes”.

Um ponto a se considerar é a combinação dos dados do Pipedrive com outras fontes, mas esse é tema para outro post.