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
- getLeads
/v1/crm-v4/leadsRetorna leads do CRM V4 com etapa, temperatura, responsável e timestamps do ciclo de vida. - getOportunidades
/v1/crm-v4/opportunitiesRetorna oportunidades do CRM V4 com etapa, valor do deal, responsável e timestamps do ciclo de vida. - getEmpresas
/v1/crm-v4/companiesRetorna empresas do CRM V4 com segmento, faixa de receita, responsável e dados de atividade. - getContatos
/v1/crm-v4/contactsRetorna contatos do CRM V4 com sua empresa principal e responsável. - getPipelines
/v1/crm-v4/pipelinesRetorna as etapas de pipeline do CRM V4 — uma linha por par board/coluna, ordenadas por board e posição da etapa. - getRetention
/v1/crm-v4/retentionCRM V4 retention by customer CNPJ for the months the period touches, against as many months right before it: monthly customer churn (CNPJs… - getContract cohort
/v1/crm-v4/retention/cohortCRM V4 contracts still active by cohort: each CNPJ is dated by its first month of recurring revenue, ever; the cohorts are the months from…
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 V4integrationId– Escopo da integraçãopage– 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 etapatemperature,ownerIdcreatedStart/createdEnd– Intervalo de data de criação
Oportunidades (/v1/crm-v4/opportunities)
boardId,columnId,phaseType– Filtros de pipeline e etapatype– Tipo do board (OPPORTUNITY,EXPANSION,ACQUISITION)ownerIdcreatedStart/createdEnd– Intervalo de data de criação
Empresas (/v1/crm-v4/companies)
segment,tierType,ownerIdlastActivityStart/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)
boardIdboardType– 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.