ChatMetric – API Externa

API RESTful para integração com sistemas externos. Permite leitura de dados de CRM (leads, negócios, pipeline) e atualização de registros via PUT.

Base URL

https://api.chatmetric.com.br/open

Autenticação

X-API-Key: sk_live_...

Formato

Todas as requisições e respostas usam JSON. Sempre envie Content-Type: application/json em POSTs.

Rate Limit

1.000 requisições por hora por API Key. O limite restante é retornado nos headers de resposta.

Autenticação

Todos os endpoints (exceto os de teste) exigem uma API Key válida enviada no header HTTP.

Exemplo de requisição autenticada

curl https://api.chatmetric.com.br/open/leads \
  -H "X-API-Key: sk_live_SuaChaveAqui"

Rate Limiting

Os headers abaixo são retornados em todas as respostas autenticadas:

Header	Descrição
X-RateLimit-Limit	Limite total de requisições por hora
X-RateLimit-Remaining	Requisições restantes na janela atual
X-RateLimit-Reset	Timestamp Unix de quando o limite será resetado

Códigos de Erro

Código	Significado
401	API Key ausente, inválida ou inativa
404	Recurso não encontrado ou não pertence à sua conta
422	Dados inválidos no body da requisição
429	Rate limit excedido
500	Erro interno do servidor

Leads

GET /leads Listar leads com filtros e paginação

Requer auth

Retorna todos os leads da conta com suporte a filtros, ordenação e paginação. Inclui dados de WhatsApp vinculado, responsável e produtos associados via negócios.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
page	int	opcional	Número da página (padrão: 1)
per_page	int	opcional	Registros por página, máx 100 (padrão: 20)
origem	string	opcional	Filtrar por origem: site, whatsapp, formulario, etc
id_usuario_responsavel	int	opcional	Filtrar por ID do usuário responsável
cidade	string	opcional	Filtrar por cidade
estado	string	opcional	Filtrar por estado (UF, ex: SP)
busca	string	opcional	Busca em nome, email, telefone ou empresa
order_by	string	opcional	Campo para ordenação (padrão: created_at)
order_dir	string	opcional	Direção: asc ou desc (padrão: desc)

Resposta 200

{
  "data": [
    {
      "id": 328,
      "id_conta": 13,
      "nome": "João Silva",
      "email": "joao@empresa.com",
      "telefone": "41999999999",
      "empresa": "Empresa XYZ",
      "cargo": "Diretor",
      "origem": "formulario",
      "cidade": "Curitiba",
      "estado": "PR",
      "pais": "Brasil",
      "observacoes": "Lead via formulário",
      "id_usuario_responsavel": null,
      "email_responsavel": "vendedor@empresa.com",
      "nome_responsavel": "Vendedor A",
      "data_primeira_interacao": null,
      "data_ultima_interacao": "2026-03-23T18:58:48",
      "created_at": "2026-02-25T17:18:46",
      "updated_at": "2026-03-23T18:58:48",
      "cpf": null,
      "rg": null,
      "data_nascimento": null,
      "cep": null,
      "logradouro": null,
      "numero": null,
      "complemento": null,
      "bairro": null,
      "whatsapp": {
        "telefone": "5541999999999",
        "nome": "João",
        "nome_salvo": null,
        "ultima_interacao": null,
        "total_mensagens": 0,
        "tem_mensagens_nao_lidas": false
      },
      "produtos": [
        { "id_produto": 1, "nome_produto": "Plano Pro", "codigo_item": "PRO-001" }
      ]
    }
  ],
  "metadata": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

POST /leads Criar novo lead

Requer auth

Cria um novo lead na conta. O ID é gerado automaticamente. O id_conta é determinado pela API Key — não precisa ser informado no body.

Body (application/json)

Campo	Tipo	Obrigatório	Descrição
nome	string	obrigatório	Nome do lead
email	string	opcional	Email do lead
telefone	string	opcional	Telefone
empresa	string	opcional	Empresa
cargo	string	opcional	Cargo
origem	string	opcional	Origem (site, whatsapp, formulario...)
cidade	string	opcional	Cidade
estado	string	opcional	Estado (UF)
pais	string	opcional	País (padrão: Brasil)
observacoes	string	opcional	Observações
id_usuario_responsavel	int	opcional	ID do responsável
cpf	string	opcional	CPF
rg	string	opcional	RG
data_nascimento	string	opcional	Data nascimento (YYYY-MM-DD)
cep	string	opcional	CEP
logradouro	string	opcional	Logradouro
numero	string	opcional	Número
complemento	string	opcional	Complemento
bairro	string	opcional	Bairro

Exemplo de requisição

POST /open/leads
Content-Type: application/json
X-API-Key: sk_live_...

{
  "nome": "Maria Oliveira",
  "email": "maria@empresa.com",
  "telefone": "41988887777",
  "empresa": "Empresa ABC",
  "cargo": "Gerente",
  "origem": "site",
  "cidade": "Curitiba",
  "estado": "PR"
}

Resposta 201 — lead criado

{ "id": 329, "nome": "Maria Oliveira", "email": "maria@empresa.com", ... }

GET /leads/{lead_id} Buscar lead por ID

Requer auth

Retorna todos os dados de um lead específico, incluindo WhatsApp e responsável.

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
lead_id	int	obrigatório	ID do lead

PUT /leads/{lead_id} Atualizar dados do lead

Requer auth

Atualiza os dados de um lead. Semântica PATCH — apenas os campos enviados no body são atualizados. Campos omitidos não são alterados.

Campos computados como email_responsavel e nome_responsavel são somente leitura. Para alterar o responsável, use id_usuario_responsavel.

Body (application/json) — todos opcionais

Campo	Tipo	Descrição
nome	string	Nome do lead
email	string	Email do lead
telefone	string	Telefone do lead
empresa	string	Empresa
cargo	string	Cargo
origem	string	Origem do lead (site, whatsapp, formulario...)
cidade	string	Cidade
estado	string	Estado (UF, ex: SP)
pais	string	País
observacoes	string	Observações
id_usuario_responsavel	int	ID do usuário responsável
cpf	string	CPF
rg	string	RG
data_nascimento	string	Data de nascimento (YYYY-MM-DD)
cep	string	CEP
logradouro	string	Logradouro
numero	string	Número
complemento	string	Complemento
bairro	string	Bairro
whatsapp.telefone	string	Número WhatsApp com DDI (ex: 5541999999999)
whatsapp.nome	string	Nome no WhatsApp
whatsapp.nome_salvo	string	Nome salvo na agenda

Exemplo de requisição

PUT /open/leads/328
Content-Type: application/json
X-API-Key: sk_live_...

{
  "empresa": "Nova Empresa Ltda",
  "cargo": "CEO",
  "cidade": "São Paulo",
  "estado": "SP",
  "whatsapp": {
    "nome_salvo": "João - Nova Empresa"
  }
}

Resposta 200 — lead atualizado completo

{ "id": 328, "nome": "João Silva", "empresa": "Nova Empresa Ltda", ... }

GET /leads/{lead_id}/negocios Listar negócios de um lead

Requer auth

Retorna todos os negócios vinculados ao lead, com etapa, responsável, produtos e custom fields.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
include_custom_fields	bool	true	Incluir custom fields
include_produtos	bool	true	Incluir produtos vinculados

Negócios

POST /negocios Criar novo negócio

Requer auth

Cria um novo negócio na conta. O ID é gerado automaticamente. O id_conta é determinado pela API Key.

Etapa: se não informada, o negócio é criado automaticamente na etapa de menor ordem ativa da conta (normalmente a etapa inicial do funil).

Body (application/json)

Campo	Tipo	Obrigatório	Descrição
titulo	string	obrigatório	Título do negócio
responsavel	object	obrigatório	`{"id": 16}` — ID do responsável
etapa	object	opcional	`{"id": 1}` — se omitido, usa etapa de menor ordem
dor_cliente	string	opcional	Dor / problema do cliente
valor	string	opcional	Valor em decimal (ex: "1500.00"). Padrão: "0.00"
moeda	string	opcional	Código da moeda. Padrão: BRL
status	string	opcional	ABERTO \| GANHO \| PERDIDO \| CANCELADO. Padrão: ABERTO
origem	string	opcional	Origem do negócio
observacoes	string	opcional	Observações internas
proxima_atividade	string	opcional	Próxima atividade
id_persona	int	opcional	ID da persona vinculada
id_lead	int	opcional	ID do lead para vincular como principal

Exemplo de requisição

POST /open/negocios
Content-Type: application/json
X-API-Key: sk_live_...

{
  "titulo": "Proposta Empresa ABC",
  "responsavel": { "id": 16 },
  "valor": "3500.00",
  "origem": "site",
  "observacoes": "Cliente interessado no plano anual",
  "id_lead": 328
}

Resposta 201 — negócio criado

{
  "id": 1242,
  "titulo": "Proposta Empresa ABC",
  "status": "ABERTO",
  "valor": "3500.00",
  "moeda": "BRL",
  "etapa": { "id": 1, "nome": "Novo Lead", "ordem": 1, "probabilidade_fechamento": "10.00" },
  "responsavel": { "id": 16, "nome": "João Verão" },
  "leads": [ { "id_lead": 328, "principal": true } ],
  ...
}

GET /negocios Listar negócios com filtros

Requer auth

Lista todos os negócios da conta com paginação, filtros e dados relacionados (etapa, responsável, leads, produtos, persona).

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
page	int	opcional	Página (padrão: 1)
per_page	int	opcional	Registros por página, máx 100 (padrão: 20)
status	string	opcional	ABERTO \| GANHO \| PERDIDO \| CANCELADO
id_etapa	int	opcional	ID da etapa do pipeline
id_usuario_responsavel	int	opcional	ID do responsável
valor_minimo	float	opcional	Valor mínimo do negócio
valor_maximo	float	opcional	Valor máximo do negócio
include_custom_fields	bool	opcional	Incluir custom fields (padrão: true)
include_produtos	bool	opcional	Incluir produtos (padrão: true)

Resposta 200

{
  "data": [
    {
      "id": 1241,
      "id_conta": 13,
      "titulo": "Proposta Empresa XYZ",
      "dor_cliente": null,
      "valor": "2.00",
      "moeda": "BRL",
      "status": "ABERTO",
      "data_fechamento_real": "2026-04-23T00:00:00",
      "origem": null,
      "observacoes": null,
      "proxima_atividade": null,
      "created_at": "2026-04-23T14:02:05",
      "updated_at": "2026-04-30T21:31:30",
      "persona": null,
      "etapa": { "id": 1, "nome": "Novo Lead", "ordem": 1, "probabilidade_fechamento": "10.00" },
      "responsavel": { "id": 16, "nome": "João Verão" },
      "motivo_perda": null,
      "leads": [ { "id_lead": 328, "principal": true } ],
      "produtos": []
    }
  ],
  "metadata": { "total": 45, "page": 1, "per_page": 20, "total_pages": 3 }
}

GET /negocios/{negocio_id} Buscar negócio por ID

Requer auth

Retorna dados completos de um negócio incluindo produtos com valores unitários, custom fields e leads vinculados.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
include_custom_fields	bool	true	Incluir custom fields
include_produtos	bool	true	Incluir produtos detalhados

PUT /negocios/{negocio_id} Atualizar dados do negócio

Requer auth

Atualiza os dados de um negócio. Semântica PATCH — apenas os campos enviados são atualizados. Campos de referência (etapa, responsável) são validados contra a conta antes de salvar.

etapa e responsavel não podem ser enviados como null — são campos obrigatórios no banco. Para removê-los, reatribua para outro valor válido.

Body (application/json) — todos opcionais

Campo	Tipo	Descrição
titulo	string	Título do negócio
dor_cliente	string	Dor / problema do cliente
valor	string	Valor em decimal (ex: "1500.00")
moeda	string	Código da moeda (ex: BRL, USD)
status	string	ABERTO \| GANHO \| PERDIDO \| CANCELADO
observacoes	string	Observações internas
proxima_atividade	string	Descrição da próxima atividade
etapa	object	`{"id": 2}` — ID da etapa do pipeline
responsavel	object	`{"id": 16}` — ID do usuário responsável
motivo_perda	object\|null	`{"id": 3}` ou `null` para remover
id_persona	int\|null	ID da persona ou `null` para desvincular

Exemplo de requisição

PUT /open/negocios/1241
Content-Type: application/json
X-API-Key: sk_live_...

{
  "status": "GANHO",
  "valor": "5000.00",
  "observacoes": "Contrato assinado",
  "etapa": { "id": 5 },
  "motivo_perda": null
}

Resposta 200 — negócio atualizado completo

{ "id": 1241, "titulo": "Proposta Empresa XYZ", "status": "GANHO", "valor": "5000.00", ... }

GET /negocios/{negocio_id}/historico Histórico de eventos do negócio

Requer auth

Retorna a trilha de auditoria completa do negócio: criação, mudanças de etapa, valor, responsável, status e notas.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Página
per_page	int	50	Registros por página (máx 100)

Resposta 200

{
  "data": [
    {
      "id": 88,
      "tipo_evento": "MUDANCA_ETAPA",
      "descricao": "Etapa alterada de 'Novo Lead' para 'Proposta'",
      "created_at": "2026-04-25T10:30:00",
      "usuario": { "id": 16, "nome": "João Verão" }
    }
  ],
  "metadata": { "total": 12, "page": 1, "per_page": 50, "total_pages": 1 }
}

GET /negocios/{negocio_id}/produtos Listar produtos do negócio

Requer auth

Retorna todos os produtos vinculados ao negócio com quantidade, valores e item específico (SKU).

GET /negocios/{negocio_id}/custom-fields Custom fields do negócio

Requer auth

Retorna apenas os custom fields preenchidos do negócio.

Pipeline

GET /pipeline-etapas Listar etapas do pipeline

Requer auth

Retorna todas as etapas ativas do pipeline ordenadas por posição, com probabilidade de fechamento.

Resposta 200

{
  "data": [
    { "id": 1, "nome": "Novo Lead", "ordem": 1, "cor": "#6366f1", "probabilidade_fechamento": "10.00", "ativo": true },
    { "id": 2, "nome": "Qualificado", "ordem": 2, "cor": "#f59e0b", "probabilidade_fechamento": "30.00", "ativo": true }
  ],
  "metadata": { "total": 5 }
}

Cadastros

GET /personas Listar personas da conta

Requer auth

Retorna os perfis-alvo de clientes configurados na conta.

GET /personas/{persona_id} Buscar persona por ID

Requer auth

Resposta 200

{ "id": 3, "nome": "CEO", "caracteristicaprincipal": "Decisor final", "descricao": "..." }

GET /produtos Listar produtos

Requer auth

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Página
per_page	int	20	Registros por página (máx 100)
apenas_ativos	bool	false	Se true, retorna apenas produtos ativos. Padrão: false (retorna todos)

GET /produtos/{produto_id} Buscar produto por ID

Requer auth

Resposta 200

{ "id": 1, "nome": "Plano Pro", "descricao": "...", "url": "https://...", "ativo": true }

POST /produtos Criar produto

Requer auth

Cria um novo produto na conta. O produto é criado como ativo por padrão. O id_conta é determinado automaticamente pela API Key.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
nome	string	obrigatório	Nome do produto (máx 100 caracteres)
url	string	opcional	URL do produto (máx 2000 caracteres)
descricao	string	opcional	Descrição do produto

Requisição

POST /open/produtos
Content-Type: application/json

{
  "nome": "Plano Enterprise",
  "url": "https://chatmetric.com.br/enterprise",
  "descricao": "Plano completo com todas as funcionalidades"
}

Resposta 201

{
  "id": 42,
  "nome": "Plano Enterprise",
  "descricao": "Plano completo com todas as funcionalidades",
  "url": "https://chatmetric.com.br/enterprise",
  "ativo": 1
}

PUT /produtos/{produto_id} Atualizar produto

Requer auth

Atualiza os dados de um produto existente. Todos os campos são opcionais — apenas os campos enviados no body serão atualizados (semântica PATCH).

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
nome	string	opcional	Novo nome do produto
url	string	opcional	Nova URL do produto
descricao	string	opcional	Nova descrição
ativo	boolean	opcional	`true` para ativar, `false` para desativar

Requisição

PUT /open/produtos/42
Content-Type: application/json

{
  "nome": "Plano Enterprise Plus",
  "descricao": "Versão expandida com suporte prioritário",
  "ativo": true
}

Resposta 200

{
  "id": 42,
  "nome": "Plano Enterprise Plus",
  "descricao": "Versão expandida com suporte prioritário",
  "url": "https://chatmetric.com.br/enterprise",
  "ativo": 1
}

Itens de Produto

GET /produtos/{produto_id}/itens Listar itens de um produto

Requer auth

Lista todos os itens (SKUs) de um produto. O item padrão aparece primeiro.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
apenas_ativos	bool	false	Se true, retorna apenas itens ativos. Padrão: false (retorna todos)

Resposta 200

{
  "data": [
    {
      "id": 10, "id_produto": 3, "codigo": "PRO-001",
      "nome": "Plano Mensal", "descricao": "...",
      "preco": 199.90, "moeda": "BRL",
      "is_default": true, "ativo": true,
      "data_criacao": "2026-01-10T10:00:00",
      "data_atualizacao": "2026-01-10T10:00:00"
    }
  ],
  "metadata": { "total": 1, "id_produto": 3 }
}

GET /produtos/{produto_id}/itens/{item_id} Buscar item por ID

Requer auth

Retorna os detalhes de um item específico.

POST /produtos/{produto_id}/itens Criar item de produto

Requer auth

Cria um novo item (SKU) para um produto. Se is_default for true, os outros itens são automaticamente desmarcados como padrão.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
nome	string	obrigatório	Nome do item (máx 255 caracteres)
codigo	string	opcional	Código / SKU do item
descricao	string	opcional	Descrição do item
preco	number	opcional	Preço (≥ 0)
moeda	string	opcional	Código da moeda (padrão: BRL)
is_default	boolean	opcional	Definir como item padrão (padrão: false)

Requisição

POST /open/produtos/3/itens
Content-Type: application/json

{
  "nome": "Plano Mensal",
  "codigo": "PRO-001",
  "preco": 199.90,
  "moeda": "BRL",
  "is_default": true
}

Resposta 201

{
  "id": 10, "id_produto": 3, "codigo": "PRO-001",
  "nome": "Plano Mensal", "descricao": null,
  "preco": 199.90, "moeda": "BRL",
  "is_default": true, "ativo": true,
  "data_criacao": "2026-07-02T10:00:00",
  "data_atualizacao": "2026-07-02T10:00:00"
}

PUT /produtos/{produto_id}/itens/{item_id} Atualizar item de produto

Requer auth

Atualiza os dados de um item existente. Apenas os campos enviados são alterados (semântica PATCH).

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
nome	string	opcional	Novo nome do item
codigo	string	opcional	Novo código / SKU
descricao	string	opcional	Nova descrição
preco	number	opcional	Novo preço (≥ 0)
moeda	string	opcional	Novo código de moeda
ativo	boolean	opcional	`true` para ativar, `false` para desativar

Requisição

PUT /open/produtos/3/itens/10
Content-Type: application/json

{ "preco": 249.90, "descricao": "Com 30 dias de trial" }

DEL /produtos/{produto_id}/itens/{item_id} Excluir item (soft delete)

Requer auth

Realiza exclusão lógica do item (ativo = 0). O registro permanece no banco.

O item padrão não pode ser excluído enquanto houver outros itens ativos. Defina outro item como padrão primeiro.

Retorna 204 No Content em caso de sucesso.

GET /vendedores Listar vendedores

Requer auth

Lista todos os vendedores da conta.

GET /vendedores/{vendedor_id} Buscar vendedor por ID

Requer auth

GET /vendedores/{vendedor_id}/skills Skills ativas do vendedor

Requer auth

Retorna as habilidades de vendas ativas do vendedor (máx 3 simultaneamente).

Resposta 200

{
  "data": [
    { "id": 2, "nome": "Escuta Ativa", "descricao": "...", "vinculado_em": "2026-01-10T09:00:00" }
  ],
  "metadata": { "total": 1 }
}

Configuração

GET /custom-fields/definition Estrutura dos custom fields

Requer auth

Retorna a definição completa dos custom fields configurados para a conta. Útil para geração de formulários dinâmicos e validação no client.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
apenas_ativos	bool	true	Retornar apenas campos ativos

ChatMetric API Externa v1.0 — Dúvidas? Contate o time de integrações.