Introdução à API
Guia para navegar pela referência da API da V4MOS.AI
Esta seção contém todos os endpoints públicos da API da V4MOS.AI, organizados por plataforma. Cada página de endpoint é gerada a partir da especificação OpenAPI e traz parâmetros, schemas de resposta, exemplos de código e um playground para testar a chamada.
URL Base
https://data.v4mos.aiTodas as requisições devem ser feitas via HTTPS, com requisições e respostas em JSON (UTF-8).
Plataformas
📊 Publicidade e Mídia
- Google Ads - Contas, campanhas, grupos de anúncios, palavras-chave, conversões e segmentações
- Facebook Ads - Contas, campanhas, conjuntos de anúncios, anúncios, criativos e breakdowns
- Google Analytics - Sessões, eventos, transações, clientes e produtos do GA4
🛒 E-commerce
- Tray - Clientes, pedidos e produtos
- Shopify - Clientes, pedidos, itens de pedido e produtos
- VTEX - Pedidos e itens de pedido
- E-commerce Summary - Resumo agregado de pedidos de VTEX, Shopify e Tray
🎯 CRM
- HubSpot - Contatos, negócios, empresas, pipelines e produtos
- Kommo - Leads, contatos, pipelines e usuários
- CRM V4 - Leads, oportunidades, empresas, contatos e pipelines
📈 Análises
- Lucratividade - Indicadores de lucratividade, evolução de métricas e cohort
- Produtos - Venda, margem, estoque e cohort de entrada por produto
- Aquisição - Funil, canais, campanhas e mídia paga
Padrões Comuns da API
Autenticação
Todas as requisições exigem as credenciais nos headers e o organizationId como query parameter. Veja Autenticação para gerar suas credenciais.
x-client-id: seu_client_id
x-client-secret: seu_client_secretParâmetros de Consulta Comuns
| Parâmetro | Tipo | Descrição | Padrão |
|---|---|---|---|
organizationId | string | ID da organização | obrigatório |
page | integer | Número da página | 1 |
limit | integer | Registros por página (1 a 5000) | 500 |
orderBy | string | Campo para ordenação | varia por endpoint |
orderDirection | string | Direção da ordenação (ASC/DESC) | varia por endpoint |
Os filtros de data e os demais parâmetros variam por endpoint; consulte a página de cada endpoint. Detalhes de paginação e limites de taxa estão em Limites e Boas Práticas.
Paginação
As listagens são paginadas por page e limit, e a resposta traz os registros em data e o estado da paginação em meta:
{
"data": [...],
"meta": {
"page": 1,
"limit": 500,
"hasNextPage": true,
"hasPreviousPage": false
}
}pagecomeça em1;limitvai de1a5000(padrão500). Valores fora da faixa são ajustados automaticamente.- Para percorrer todos os registros, incremente
pageenquantometa.hasNextPagefortrue. - Endpoints agregados (como os de E-commerce Summary) devolvem um único resultado, sem paginação. Confira o schema de resposta na página de cada endpoint.
Exemplos completos em Limites e Boas Práticas.
Erros comuns
| Status | Quando acontece | Como resolver |
|---|---|---|
400 | organizationId ausente ou parâmetro inválido (erro de validação) | Envie organizationId em toda requisição e confira nomes, tipos e formatos dos parâmetros |
401 | Headers x-client-id/x-client-secret ausentes ou credenciais inválidas | Confira os headers ou gere novas credenciais em Autenticação |
429 | Limite de 100 requisições por minuto por credencial excedido | Aguarde o tempo do header Retry-After e use retry com backoff exponencial |
500 | Erro interno do servidor | Tente novamente com backoff; se persistir, fale com o suporte |
O corpo das respostas de erro é JSON, com a descrição do problema em message.
Próximos Passos
- Gere suas credenciais em Autenticação
- Escolha uma plataforma no menu lateral
- Teste os endpoints no playground de cada página
- Entenda a atualização dos dados em Sincronização e Atualização de Dados