Visão geral

A API Ploomes da V4MOS.AI entrega os registros brutos sincronizados das contas Ploomes conectadas à sua organização: negócios, histórico de estágios dos negócios, leads, clientes, funis, estágios, status, origens, motivos de perda, campos, usuários e exclusões. As linhas vêm como foram sincronizadas, com os nomes de coluna do data warehouse (snake_case), prontas para levar ao seu BI. Todos os endpoints usam o prefixo /v1/ploomes e seguem a mesma autenticação, paginação e formato de resposta.

Primeiros passosCopiar link da seção

URL base: https://data.v4mos.ai. Toda chamada exige suas credenciais de API e o organizationId — veja Autenticação.

1. Conecte a integração Ploomes em app.v4mos.ai (Contas conectadas) e aguarde a primeira sincronização.
2. Chame qualquer endpoint abaixo com o seu organizationId, por exemplo GET /v1/ploomes/deals?organizationId=….
3. Toda linha traz integration_id e integration_name: a conta conectada de onde ela veio. Para ler uma conta só, passe esse valor em integrationId.

Endpoints disponíveisCopiar link da seção

• getNegócios/v1/ploomes/dealsUma linha por negócio: funil, estágio, status, valor, datas de início e término, origem, responsável, cliente e lead de origem.
• getHistórico de estágios dos negócios/v1/ploomes/deal-stage-historyUma linha por mudança de estágio de um negócio: estágio de origem e de destino, se avançou, ganhou ou perdeu, valor e dias no estágio.
• getLeads/v1/ploomes/leadsUma linha por lead: status, motivo de descarte, responsável, pessoa e empresa.
• getClientes/v1/ploomes/contactsUma linha por cliente (pessoa ou empresa): tipo, empresa, origem, status, responsável e lead de origem.
• getFunis/v1/ploomes/pipelinesUma linha por funil, com o indicador de arquivado.
• getEstágios/v1/ploomes/stagesUma linha por estágio do funil, com a ordem.
• getStatus de negócio/v1/ploomes/deal-statusesUma linha por status de negócio (em aberto, ganho, perdido).
• getOrigens/v1/ploomes/originsUma linha por origem de clientes e negócios.
• getMotivos de perda/v1/ploomes/loss-reasonsUma linha por motivo de perda de negócio, com o funil.
• getCampos/v1/ploomes/fieldsUma linha por definição de campo, com a entidade e o tipo.
• getUsuários/v1/ploomes/usersUma linha por usuário da conta: perfil e indicadores de integração e de suspenso.
• getNegócios excluídos/v1/ploomes/deleted-dealsUma linha por negócio excluído no Ploomes; use para remover esses negócios da sua cópia.
• getClientes excluídos/v1/ploomes/deleted-contactsUma linha por cliente excluído no Ploomes; use para remover esses clientes da sua cópia.

RecursosCopiar link da seção

Paginação e filtrosCopiar link da seção

• page (padrão 1) e limit (padrão 500, máximo 5000). meta.hasNextPage diz se existe outra página; as linhas vêm sempre na mesma ordem, então avance as páginas até ele ser false.
• dateFrom / dateTo (YYYY-MM-DD, inclusivos) filtram pela coluna de data indicada na tabela acima. Recursos sem coluna de data recusam esses parâmetros.
• integrationId mantém só as linhas de uma conta conectada.
• As respostas ficam em cache por 30 minutos e os dados são sincronizados uma vez por dia — veja Sincronização de dados.

Formato da respostaCopiar link da seção

{
  "data": [{ "...": "um objeto por linha, com as colunas listadas em cada endpoint" }],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Valores monetários e contadores grandes (campos format: decimal e format: int64 no schema de cada endpoint) chegam como texto, por exemplo "125.50", para não perder precisão. Converta para um tipo decimal do seu lado.