Visão Geral do CRM

O módulo CRM é o único disponível na API pública hoje. Ele organiza o ciclo de vendas em torno de quatro recursos: pipeline (funil), estágio, negócio (deal) e atividade. Todos vivem sob o prefixo /crm e seguem as convenções gerais da API — autenticação por API Key, envelope de resposta padronizado e IDs em UUID v4.

O ciclo

Pipeline
  └── Estágio (ordenado por sort_order)
        └── Negócio (ocupa um estágio por vez)
              └── Atividade (ligação, reunião, tarefa, e-mail, nota...)

1. Pipeline

O funil de vendas. Tem nome e uma lista ordenada de estágios. Ver Pipelines & Estágios.

2. Estágio

Uma etapa do funil (ex.: “Em negociação”). Cada negócio ocupa exatamente um estágio do seu pipeline por vez.

3. Negócio

A oportunidade de venda em si — pertence a um pipeline e a um estágio, carrega os dados do contato/cliente e o valor prospectado. Ver Negócios.

4. Atividade

Uma interação ligada a um negócio — ligação, reunião, tarefa, e-mail ou nota, com data prevista e conclusão. Ver Atividades.

Sem contatos e empresas como cadastro à parte

A API pública não tem um recurso próprio de “contato” ou “empresa do CRM”. Os dados de quem está do outro lado da negociação vivem como campos livres diretamente no negócio: contact_name, company_name, client_email, client_phone. Não há um ID de contato reaproveitável entre negócios diferentes — cada negócio carrega sua própria cópia desses dados.

Nota

Um modelo de contato/empresa como cadastro compartilhado entre negócios está em avaliação, mas depende de uma decisão de modelo de dados ainda não tomada. Não documentamos isso como disponível até existir de fato.

Catálogos por pipeline

Cada pipeline nasce com catálogos próprios de status, origem (source), motivo de perda (loss reason) e tipo de atividade, sempre semeados com os valores padrão do sistema quando o pipeline é criado pela API pública — não são customizáveis por ela. Os valores padrão de status são:

Status	Kind
sem_contato	aberto
em_contato	aberto
negociando	aberto
proposta_enviada	aberto
ganho	ganho
perdido	perdido

O kind (aberto/ganho/perdido) é o que a API usa para decidir o resultado de marcar um negócio como ganho, perdido ou reaberto — o status em si é sempre o valor livre do catálogo daquele pipeline.

Campos compartilhados

Todo recurso do CRM expõe:

Campo	Tipo	Descrição
id	string (UUID v4)	Identificador do recurso.
created_at	string (ISO-8601)	Data e hora de criação.
updated_at	string (ISO-8601)	Data e hora da última atualização.

Valores monetários (prospected_value, budget) são inteiros em centavos. Datas e horários são strings em ISO-8601 (ou YYYY-MM-DD quando é só data).

Próximos passos

• Pipelines & Estágios — crie o funil antes de criar negócios.
• Negócios — crie, mova de etapa, marque como ganho ou perdido.
• Atividades — registre interações ligadas a um negócio.

Para o formato completo de erros e códigos de status, ver Erros. Para escopos exigidos por cada operação, ver Escopos & Permissões.