HubSpot CRM Operations

Operações no CRM HubSpot

Use esta habilidade para ler e, com confirmação explícita, atualizar dados do CRM HubSpot por meio da API v3 do HubSpot CRM: registros de contatos, pesquisa de contatos, visualizações de pipeline de negócios e alterações de estágio de negócios. Esta é uma habilidade de ferramenta para um fornecedor de CRM (HubSpot). Construir aplicativos ou workflows no HubSpot é desenvolvimento de aplicativos; esta habilidade gerencia o fluxo de trabalho cotidiano do agente: responder "quem é este contato?", "o que está no pipeline?" e aplicar uma alteração confirmada de estágio.

Contrato de operação

1. Descoberta somente leitura antes de qualquer mutação. Liste e pesquise contatos, visualize negócios e pipelines livremente. O script crm-cli incluído realiza leituras sem escrever nada.
2. Confirme o alvo, o escopo e o caminho de reversão antes de agir. Mover um negócio para um novo estágio altera um pipeline compartilhado que os relatórios de receita leem: requer uma diretiva humana explícita nomeando o negócio e o estágio de destino, além da pré-visualização --dry-run e da confirmação --yes por meio do crm-cli. As movimentações de estágio são reversíveis, mas deixam um histórico de auditoria — confirme antes de agir.
3. Respeite as leituras limitadas. O HubSpot pagina com limit; nunca avance páginas além do que a tarefa precisa. crm-cli --limit limita toda listagem e pesquisa.
4. Mantenha as evidências limitadas. Cite nomes curtos, e-mails, valores e rótulos de estágio; nunca despeje registros completos, tokens ou payloads brutos no chat.
5. Conheça o modelo de objetos. Contatos e negócios são objetos distintos com mapas de propriedades; as transições de estágio devem usar um ID de estágio do pipeline do negócio (pipelines list), não um rótulo de estágio.

O script crm-cli

scripts/crm-cli é um CLI focado em agentes e apenas com stdlib sobre a API v3 do HubSpot CRM. Ele cobre todo o escopo do problema: registros, pesquisa e visualizações de pipeline.

crm/scripts/crm-cli --help                                # sem token ou rede necessária
crm/scripts/crm-cli --json --limit 20 contacts list
crm/scripts/crm-cli --json contacts get --id 51
crm/scripts/crm-cli --json contacts search --query "ada"
crm/scripts/crm-cli --json --limit 20 deals list
crm/scripts/crm-cli --json deals list --pipeline default --stage appointmentscheduled
crm/scripts/crm-cli --json pipelines list
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --dry-run   # pré-visualização
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # confirmado

Códigos de saída: 0 sucesso, 1 erro de API ou verificação falha, 2 erro de uso. As alterações de estágio são protegidas: sem --dry-run ou --yes, o script recusa com código 1 e nunca chama a API. As leituras são limitadas por --limit (padrão 20, máximo 100).

Ciclo de operação

1. Definir o escopo da pergunta: é uma consulta (quem/o que está no CRM) ou uma alteração (mover um negócio)? Localize o objeto com contacts search/contacts list ou deals list.
2. Ler com limites: contacts get para um registro, deals list para a visualização do pipeline (opcionalmente filtrado por pipeline e estágio), pipelines list para resolver rótulos de estágio em IDs.
3. Triar a resposta: mapear a pergunta para evidências (detalhes do contato, valor/estágio do negócio, distribuição do pipeline).
4. Agir com confirmação: apenas uma diretiva humana para alterar, pré-visualizada com --dry-run e confirmada com --yes.
5. Verificar: releia o negócio (deals list --stage <destino>) e confirme que o estágio foi movido.

Registros, pesquisa, visualizações de pipeline

• Registros de contatos (/objects/contacts): listar (GET) ou recuperar um (GET por ID); o CLI resume nome, sobrenome, e-mail, empresa e data de criação. Pesquisa (POST /objects/contacts/search) encontra contatos por texto de consulta, limitada por --limit.
• Visualizações de pipeline de negócios (/objects/deals): listar negócios com valor, pipeline e estágio, opcionalmente filtrados para um pipeline ou estágio. pipelines list (/pipelines/deals) retorna os pipelines com seus IDs e rótulos de estágio — use o ID do estágio ao filtrar ou atualizar.
• Alterações de estágio (PATCH /objects/deals/{id}): uma mutação protegida que define a propriedade dealstage. Pré-visualize o estágio de destino com --dry-run, confirme com --yes e verifique com uma leitura de acompanhamento. Apenas movimentações de estágio estão no escopo; outras edições de propriedades do negócio são trabalho de aplicação.

Modelo de acesso

• Tokens de acesso de aplicativo privado HubSpot (pat_...) escopo por objeto e leitura/gravação. Leituras precisam de crm.objects.contacts.read e crm.objects.deals.read; atualizações de estágio precisam de crm.objects.deals.write.
• Registros carregam um mapa properties indexado pelos nomes das propriedades (ex.: dealstage, dealname, amount). Os valores das propriedades são strings; o CLI resume os campos que esta habilidade usa.
• Tokens são credenciais: armazene em HUBSPOT_TOKEN, nunca em código, chat ou commits. Gire um token vazado nas configurações do aplicativo privado.

Roteamento de referência

Carregar quando	Referência
Fontes, tabelas de escopo, procedimento de atualização	references/00-source-index.md
Endpoints, paginação, modelo de objetos, atualizações de estágio, erros	references/01-hubspot-crm-operations.md

Artefatos incluídos

• scripts/crm-cli: CLI limitado e apenas stdlib (contacts list/get/search, deals list/update-stage, pipelines list; --json; --limit; mutações bloqueadas por --dry-run/--yes).
• tests/test_crm_cli.py: 13 testes determinísticos contra uma API HubSpot simulada, incluindo a proteção de mutação e o contrato somente leitura.
• references/: índice de fontes com data + referência de operações do CRM HubSpot.
• evals/evals.json: seis casos de avaliação de qualidade de saída para execuções de agente.

Limite de verificação

Afirmação	Evidência mínima
Um contato existe	crm-cli contacts search --query ... --json ou contacts get retorna o registro
Uma visualização de pipeline está correta	crm-cli deals list --json retorna negócios com IDs de estágio e o filtro aplicado
Um rótulo de estágio mapeia para um ID	crm-cli pipelines list --json retorna o mapa de estágios do pipeline
Uma alteração de estágio foi aplicada	crm-cli deals update-stage --yes sai com 0 e um deals list --stage subsequente mostra o negócio
Uma mutação é segura para executar	crm-cli deals update-stage --dry-run imprime o negócio exato + estágio de destino

Limites rígidos

• Nunca mover um negócio sem uma diretiva humana, pré-visualização --dry-run e confirmação --yes — alterações de pipeline alimentam relatórios de receita e histórico de auditoria.
• Nunca afirmar que um registro está faltando quando o token pode não ter escopo de objeto; verifique o modelo de acesso primeiro.
• Nunca avançar leituras além do --limit; nunca despejar registros completos, tokens ou payloads brutos no chat.
• Esta habilidade opera a API do CRM HubSpot. Ela não constrói aplicativos HubSpot nem cobre outros CRMs.

Quando não usar

• Construir aplicativos HubSpot, automações de workflow ou objetos personalizados — isso é desenvolvimento de aplicativos HubSpot; veja backend-engineering para design de serviços.
• Marketing, sequências e automação de e-mail no HubSpot — isso é a superfície de Marketing do HubSpot, não a API de CRM que esta habilidade cobre.
• Outros CRMs (Salesforce, Pipedrive, Zoho) — cada um tem sua própria API e ferramentas; esta habilidade cobre HubSpot.
• Estratégia de CRM, design de processo de vendas ou metodologia de pipeline — isso é trabalho organizacional/de estratégia, não uma operação de API.