> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Pipedrive > Negócios, pessoas, organizações, atividades e notas de uma conta Pipedrive, com a visibilidade de cada registro, no Data Catalog, no Memory e no Knowledge. O conector Pipedrive lê negócios, pessoas, organizações, atividades, notas, funis, etapas, usuários e os dicionários de campos de uma conta Pipedrive, e grava com cada registro quem pode vê-lo segundo a visibilidade definida no Pipedrive. | | | | - | - | | **Status** | Disponível | | **Conteúdo** | Registros e documentos | | **Autenticação** | Token de API | | **Permissões** | Por item | | **Sincronização** | Incremental e full refresh, por recurso | | **Última revisão** | 07/10/2026 | ## Capacidades * Traz ao Data Catalog os registros do CRM: negócios, pessoas, organizações e atividades, com funis, etapas e usuários da conta. * Traduz os campos customizados. Os valores de `deals`, `persons` e `organizations` viram tabelas em formato longo, uma linha por campo, com o nome do campo e o rótulo da opção resolvidos pelos dicionários de campos. * Envia o texto de cada nota ao Knowledge como documento, com a mesma permissão da linha da nota. * Alimenta o Memory pelo fragmento de ontologia do conector: negócios, pessoas, organizações, usuários, atividades, funis e etapas viram nós. Pessoas se unem a contatos de outros CRMs pelo e-mail ou telefone, e organizações pelo domínio do site. Os nós só entram no grafo depois que a ontologia unificada é aplicada. * Calcula a permissão de cada registro a partir do campo de visibilidade do Pipedrive e do plano da conta (ver Permissões). ## Recursos disponíveis | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `users` | Usuários da conta, com `email`, `is_admin`, `active_flag` e `role_id` | Full refresh | Nenhum | Catálogo e Memory | Sim | | `pipelines` | Funis de vendas | Full refresh | Nenhum | Catálogo e Memory | Sim | | `stages` | Etapas de cada funil, com a probabilidade padrão | Full refresh | Nenhum | Catálogo e Memory | Sim | | `deal_fields` | Dicionário dos campos de negócio: código, nome, tipo e opções | Full refresh | Nenhum | Catálogo | Sim | | `person_fields` | Dicionário dos campos de pessoa | Full refresh | Nenhum | Catálogo | Sim | | `organization_fields` | Dicionário dos campos de organização | Full refresh | Nenhum | Catálogo | Sim | | `deals` | Negócios, com valor, moeda, status, etapa, dono, pessoa, organização e `custom_fields` | Full refresh, incremental opcional | `update_time` | Catálogo e Memory | Sim | | `persons` | Pessoas, com todos os e-mails e telefones e `custom_fields` | Full refresh, incremental opcional | `update_time` | Catálogo e Memory | Sim | | `organizations` | Organizações, com endereço, site, setor e `custom_fields` | Full refresh, incremental opcional | `update_time` | Catálogo e Memory | Sim | | `activities` | Atividades, com tipo, vencimento, conclusão e o negócio, pessoa ou organização ligados | Full refresh | Nenhum | Catálogo e Memory | Sim | | `notes` | Metadados da nota no catálogo. O texto vai só para o Knowledge | Full refresh | Nenhum | Catálogo e Knowledge | Sim | No Data Catalog, `notes` nasce ligado e os demais recursos nascem desligados. Você escolhe quais carregar depois de conectar. `deal_fields`, `person_fields` e `organization_fields` não têm switch no Data Catalog. Cada um é carregado junto com a entidade que descreve: `deal_fields` com `deals`, `person_fields` com `persons` e `organization_fields` com `organizations`. Sem eles, as tabelas de campos customizados não seriam construídas. ## Permissões (ACL) O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em **Comportamento dos dados**, você escolhe entre dois modos: | Modo | Quem vê | | - | - | | Aberto | Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas. | | Espelhar a fonte | Cada pessoa vê apenas os registros que a própria fonte libera para ela. | No modo "Espelhar a fonte", a Strattum reconhece cada pessoa pelo e-mail que ela tem no Pipedrive. O conector grava esse e-mail como uma identidade do Pipedrive, ligada a esta conexão. O Pipedrive não tem a opção **Exigir login na fonte como prova de identidade**. > [!WARNING] > > Hoje, no modo "Espelhar a fonte", `deals`, `persons`, `organizations`, `activities` e `notes` não aparecem para nenhum usuário. A plataforma ainda não associa as identidades gravadas pelo Pipedrive às contas da Strattum. `users`, `pipelines`, `stages`, `deal_fields`, `person_fields` e `organization_fields` continuam visíveis para quem pode usar o conector. Para liberar o conteúdo agora, use "Aberto" e limite o acesso em **Quem pode usar este conector**. No passo de acesso do assistente de criação, o **Comportamento dos dados** começa em "Aberto". ### Como a fonte define acesso No Pipedrive, negócios, pessoas e organizações têm um dono e um nível de visibilidade (`visible_to`). O significado do nível depende do plano da conta. Os grupos de visibilidade são os papéis (`roles`) da conta, que podem ter subgrupos. Atividades e notas não têm visibilidade própria. Funis, etapas, usuários e campos são visíveis para qualquer usuário da conta. ### Como a Strattum traduz o acesso Para negócios, pessoas e organizações, quem recebe acesso depende do `visible_to` e do plano. Os administradores ativos da conta entram em todos os registros. | `visible_to` | Premium / Ultimate | Lite / Growth | | - | - | - | | `1` | Dono | Dono | | `3` | Dono e membros do grupo do dono | Todos os usuários ativos | | `5` | Dono e membros do grupo do dono e dos subgrupos | Dono | | `7` | Todos os usuários ativos | Dono | | Ausente ou desconhecido | Dono | Dono | Uma atividade ou nota recebe os leitores de um registro pai, o autor e os administradores. O pai é o negócio, se houver. Senão, a pessoa, e por último a organização. Funis, etapas, usuários e os três dicionários de campos recebem acesso para todos que podem usar o conector. O plano vem do campo **Plano do Pipedrive** do Console. O conector também lê as opções de visibilidade da conta: se elas incluem `5` ou `7`, a conta é tratada como Premium / Ultimate, mesmo que o campo diga Lite / Growth. Se as opções não puderem ser lidas, vale Premium / Ultimate, a leitura mais restrita. Todo erro de leitura reduz o acesso, nunca o amplia. Se os grupos não puderem ser lidos, os níveis `3` e `5` caem para dono e administradores. Se o pai de uma nota ou atividade foi apagado ou não respondeu, ela fica com autor e administradores. O Pipedrive libera alguns negócios para seguidores (followers). O conector não lê seguidores, então um seguidor só vê o negócio se outra regra da tabela o incluir. ### Quando a identidade não é encontrada * Usuário inativo ou apagado no Pipedrive não recebe acesso. * Usuário sem e-mail no Pipedrive não recebe acesso, e a execução registra quantos ficaram de fora. * Um registro sem nenhum leitor resolvido fica invisível no modo "Espelhar a fonte". Uma nota nessa situação não é publicada no Knowledge. ### Quando a permissão é atualizada A permissão é calculada em todo sync, junto com o dado. Mudar um usuário de grupo, promovê-lo a administrador ou desativá-lo não altera os registros, então o conector compara a cada execução os usuários, os grupos e o plano com os da última execução completa. Se algo mudou, os recursos com permissão rodam em full refresh naquela execução e todos os registros são regravados com a permissão nova. Atividades e notas rodam sempre em full refresh. Quando uma delas está ligada, `deals`, `persons` e `organizations` também rodam em full refresh, para que uma mudança de visibilidade no pai chegue aos filhos na mesma execução. ## Pré-requisitos * Uma conta Pipedrive em qualquer plano. * Um usuário Admin da conta para gerar o token. O token de um usuário comum limita a sincronização ao que ele vê, e o teste de conexão recusa esse token. * Saber o plano da conta (Lite / Growth ou Premium / Ultimate), que muda o significado da visibilidade. * Uma só conexão Pipedrive por instalação da Strattum. ## Autenticação e escopos A autenticação usa o token de API pessoal do usuário Admin, enviado no cabeçalho `x-api-token`. O token pessoal não tem escopos: ele herda o acesso do usuário que o gerou. | Permissão do usuário | Para quê | | - | - | | Admin da conta | Ler todos os negócios, pessoas, organizações, atividades e notas, e não só os visíveis para o dono do token. | | Admin da conta | Ler os grupos de visibilidade (`/api/v1/roles`), necessários para calcular as permissões. | Se o usuário dono do token for desativado, o conector para de sincronizar. **1. Entre como Admin** Acesse o Pipedrive com um usuário Admin da conta. Prefira um usuário que não vá ser desativado. **2. Abra o token** Clique no nome da conta, no canto superior direito, e abra **Company settings** > **Personal preferences** > **API**. **3. Copie o token** Copie o token pessoal. Você o informa no Console. ## Configuração no Console **1. Abra o assistente** Em **Conectores**, crie uma nova conexão e selecione **Pipedrive**. **2. Preencha a conexão** **Nome do Conector** (Opcional): como a conexão aparece na lista. O padrão é `Pipedrive`. **Token de API** (Obrigatório): o token pessoal do usuário Admin. **Plano do Pipedrive** (Opcional): **Premium / Ultimate** ou **Lite / Growth**. O padrão é **Premium / Ultimate**. Escolha o plano real da conta: marcar Lite numa conta Premium abre para todos os usuários o que era visível só para o grupo do dono. **3. Teste a conexão** Clique em **Testar Conexão**. Você só avança depois de um teste com sucesso ou com ressalvas. O teste confere o token, se o usuário é Admin, o acesso aos grupos e aos negócios, e avisa quando o plano escolhido não bate com o da conta. **4. Escolha a frequência** Em **Sincronização** (Obrigatório), escolha a frequência. **5. Defina o acesso** Em **Permissionamento**, defina **Quem pode usar este conector** e o **Comportamento dos dados**. O padrão é "Todos os usuários" e "Aberto". **6. Revise e salve** Em **Revisão**, confira os dados e salve. Depois, no Data Catalog, ligue os recursos que você quer carregar e marque os dados pessoais, se houver. Ver [Dados pessoais (PII)](https://docs.strattum.ai/data-pipelines/personal-data.md). > [!NOTE] > > As notas só são indexadas quando um contexto do Knowledge está ligado ao conector. Sem contexto, elas continuam sendo extraídas e publicadas, mas não aparecem na busca. ## Como a sincronização funciona A frequência vem do passo **Sincronização**. A referência do conector é uma execução a cada 6 horas. **Ordem.** Em cada execução, o conector lê primeiro os usuários e os grupos de visibilidade, depois funis, etapas e dicionários de campos, depois negócios, pessoas e organizações, e por último atividades e notas. Recurso desligado no Data Catalog não é gravado. **Paginação.** O conector pede 500 itens por página. As listagens da API v2 avançam por cursor, e `users` e `notes` (API v1) avançam por deslocamento. **Full refresh (padrão).** A tabela do recurso é reescrita a cada execução, e um registro apagado no Pipedrive some dela. **Incremental.** Só `deals`, `persons` e `organizations` aceitam. A execução pede ao Pipedrive o que mudou desde o último `update_time` visto, menos 10 minutos de margem, e mescla o resultado pelo id. O incremental só vale com `activities` e `notes` desligados, e uma mudança de usuários ou grupos força um full refresh. **Remoção.** Em incremental, um registro apagado no Pipedrive continua na Strattum até o próximo full refresh. Se o Pipedrive indicar mais páginas sem dizer onde continuar, a execução mescla o que leu em vez de reescrever a tabela, e o cursor não avança. **Notas no Knowledge.** Cada nota vira um documento com o título `Nota `. Uma execução que leu todas as notas sem falha reconcilia o Knowledge, e notas apagadas no Pipedrive saem do índice. Se uma página de notas falhar, as notas lidas até ali são publicadas e nada é removido. ## API da fonte | Método e caminho | Usado para | Recurso | | - | - | - | | `GET /api/v1/users/me` | Teste de conexão: validar o token e o perfil Admin | Nenhum | | `GET /api/v1/users` | Listar usuários e montar o mapa de e-mails da permissão | `users` | | `GET /api/v1/roles` | Listar os grupos de visibilidade e a hierarquia | Permissão | | `GET /api/v1/roles/{id}/assignments` | Membros de um grupo, só para usuário ativo sem grupo informado | Permissão | | `GET /api/v2/pipelines` | Listar funis | `pipelines` | | `GET /api/v2/stages` | Listar etapas | `stages` | | `GET /api/v2/dealFields` | Listar os campos de negócio e detectar o plano | `deal_fields` | | `GET /api/v2/personFields` | Listar os campos de pessoa | `person_fields` | | `GET /api/v2/organizationFields` | Listar os campos de organização | `organization_fields` | | `GET /api/v2/deals` | Listar negócios | `deals` | | `GET /api/v2/persons` | Listar pessoas | `persons` | | `GET /api/v2/organizations` | Listar organizações | `organizations` | | `GET /api/v2/activities` | Listar atividades | `activities` | | `GET /api/v1/notes` | Listar notas e ler o texto | `notes` | | `GET /api/v2/deals/{id}`, `/api/v2/persons/{id}`, `/api/v2/organizations/{id}` | Ler um pai que não estava na listagem, para a permissão de atividades e notas | `activities`, `notes` | **Rate limits.** O Pipedrive dá a cada conta um orçamento diário de 30.000 tokens, multiplicado pelo plano (Lite 1, Growth 2, Premium 5, Ultimate 7) e pelo número de assentos. Há também um limite por janela de 2 segundos: com token de API, 20 requisições no Lite, 40 no Growth, 100 no Premium e 120 no Ultimate. Esgotado o limite, o Pipedrive responde 429, e responde 403 quando bloqueia tráfego abusivo. O conector desacelera quando restam menos de 10% das requisições da janela. Diante de um 429, espera o tempo informado pelo Pipedrive, no máximo 60 segundos, e tenta de novo até 5 vezes. Depois disso, a execução falha, o que acontece quando o orçamento diário acabou. Um 403 encerra a execução sem nova tentativa. Erros 5xx e conexões interrompidas têm até 5 tentativas com recuo crescente. Referência oficial: [Pipedrive, limites de requisição](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting) ## Limitações conhecidas * No modo "Espelhar a fonte", negócios, pessoas, organizações, atividades e notas ainda não aparecem para nenhum usuário. A plataforma ainda não associa as identidades gravadas pelo Pipedrive às contas da Strattum. Para liberar o conteúdo agora, use "Aberto" e limite o acesso em **Quem pode usar este conector**. * O Pipedrive não permite vincular a conta de cada usuário: a identidade é o e-mail do usuário no Pipedrive. * Seguidores (followers) e a lista de usuários com permissão de um negócio não são lidos. Um seguidor pode ver no Pipedrive um negócio que não vê na Strattum. * Os conjuntos de permissões do Pipedrive, como "ver atividades de outros usuários", não entram no cálculo. Só a visibilidade do registro conta. * O plano da conta não vem da API. Se o campo **Plano do Pipedrive** estiver errado numa conta Lite / Growth, registros visíveis para a empresa inteira ficam mais restritos que no Pipedrive. * Em incremental, um registro apagado no Pipedrive só some no próximo full refresh. * Produtos, leads, arquivos, e-mails, projetos e metas não são lidos. * O título do documento de cada nota no Knowledge é `Nota `, sem o nome do negócio, da pessoa ou da organização. * Uma conexão Pipedrive por instalação. ## Troubleshooting | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | Token de API inválido. | O token está errado ou foi revogado. | Gere um novo token em **Personal preferences** > **API**, logado como Admin. | | O token pertence a um usuário que não é Admin da conta. | O token foi gerado por um usuário comum ou por um usuário desativado. | Gere o token com um usuário Admin ativo. | | Sem acesso aos grupos de visibilidade (roles). | O usuário do token não pode ler `/api/v1/roles`. | Gere o token com um usuário Admin. | | Não foi possível contatar a API do Pipedrive. | Falha de rede até `api.pipedrive.com`. | Verifique a conectividade de rede e tente de novo. | | Plano declarado é Lite/Growth, mas a conta parece ser Premium/Ultimate. | O campo **Plano do Pipedrive** não bate com a conta. | Corrija o campo. Até lá, o conector trata a visibilidade como Premium. | | Plano declarado é Premium/Ultimate, mas a conta parece ser Lite/Growth. | O campo **Plano do Pipedrive** não bate com a conta. | Corrija o campo para Lite / Growth, ou os registros visíveis para a empresa inteira ficam mais restritos. | | deals: não foi possível verificar o acesso aos negócios. | O teste não conseguiu ler `/api/v2/deals`. | Confira se o usuário do token vê os negócios e tente de novo. | | A execução falha depois de várias respostas 429. | O orçamento diário de tokens da conta acabou. | Aguarde a renovação diária do orçamento, reduza a frequência ou desligue recursos que não usa. | | As tabelas de campos customizados estão vazias. | A entidade correspondente está desligada no Data Catalog. | Ligue `deals`, `persons` ou `organizations`. O dicionário de campos vem junto. | | As notas não aparecem na busca do Knowledge. | Nenhum contexto do Knowledge está ligado ao conector. | Ligue um contexto do Knowledge ao conector. | ## Próximos passos > **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)** > > Ligue os recursos do Pipedrive, ajuste o modo de carga e marque dados pessoais. > **[Knowledge](https://docs.strattum.ai/knowledge/overview.md)** > > Veja como as notas do Pipedrive são indexadas e buscadas. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.