CRM V4

Visão geral

Visão geral da API CRM V4 do V4MOS.AI

A API CRM V4 do V4MOS.AI expõe dados de leads, oportunidades, empresas, contatos e pipelines sincronizados do CRM V4 (mars-sales) conectado à sua organização. Os endpoints compartilham o prefixo /v1/crm-v4 e usam a mesma autenticação, paginação e envelope de metadados das demais integrações do V4MOS.AI.

Endpoints disponíveis

Autenticação

Todos os endpoints exigem o query parameter organizationId. Os endpoints de leads, oportunidades, empresas, contatos e pipelines usam os headers x-client-id e x-client-secret. Os endpoints de retenção (/v1/crm-v4/retention e /v1/crm-v4/retention/cohort) não aceitam esse par: exigem Authorization: Bearer {token} com token user ou oaclient. Veja Autenticação.

Parâmetros comuns

  • organizationId (obrigatório) – Organização dona da integração CRM V4
  • integrationId – Escopo da integração
  • page – Número da página (padrão: 1)
  • limit – Registros por página (padrão: 500, máx: 5000)

Filtros por recurso

Leads (/v1/crm-v4/leads)

  • boardId, columnId, phaseType – Filtros de pipeline e etapa
  • temperature, ownerId
  • createdStart / createdEnd – Intervalo de data de criação

Oportunidades (/v1/crm-v4/opportunities)

  • boardId, columnId, phaseType – Filtros de pipeline e etapa
  • type – Tipo do board (OPPORTUNITY, EXPANSION, ACQUISITION)
  • ownerId
  • createdStart / createdEnd – Intervalo de data de criação

Empresas (/v1/crm-v4/companies)

  • segment, tierType, ownerId
  • lastActivityStart / lastActivityEnd – Intervalo de última atividade

Contatos (/v1/crm-v4/contacts)

  • companyId, ownerId

Retenção (/v1/crm-v4/retention)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); sem paginação
  • Churn mensal de clientes e retenção bruta de receita (GRR) por CNPJ, nos meses do período e nos mesmos meses logo antes

Contratos ativos por safra (/v1/crm-v4/retention/cohort)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); sem paginação
  • Por mês de início do contrato, quantos CNPJs seguem faturando em cada mês seguinte, até o mês de endDate

As duas rotas de retenção são da auditoria: só aceitam Bearer token de kind user ou oaclient emitido para a aplicação V4MOS; o par x-client-id / x-client-secret e service accounts de cliente recebem 403.

Pipelines (/v1/crm-v4/pipelines)

  • boardId
  • boardType – Tipo do board (LEAD, OPPORTUNITY, EXPANSION, ACQUISITION)

Trabalhando com etapas

A etapa de um card é descrita por column_id + column_title + phase_type. Use phase_type na lógica de negócio — é o marcador estável e independente de idioma, enquanto column_title é texto livre que a organização pode renomear a qualquer momento. Faça o join dos cards com /v1/crm-v4/pipelines por board_id + column_id para resolver a ordem das etapas (column_order).

Paginação

As respostas retornam meta.page, meta.limit, meta.hasNextPage e meta.hasPreviousPage. Itere enquanto hasNextPage for true.

Nesta página