MetricsFarma

Introdução

A API externa do MetricsFarma permite que sistemas integrados (como o Chatplus/IA) cadastrem clientes e registrem atendimentos automaticamente. Todas as rotas utilizam autenticação via API key enviada no header da requisição.

Base URL

https://app.metricsfarma.cloud

Autenticação

Todas as requisições devem incluir o header X-API-Key com a chave da empresa. A chave é gerada no painel administrativo e vinculada a uma empresa ativa.

curl -H "X-API-Key: mf_sua_chave_aqui" https://app.metricsfarma.cloud/api/externo/...

Conceito: Sessão

Cada cliente possui 1 sessão por dia. Ao registrar um atendimento, a sessão do dia é criada ou atualizada automaticamente. A IA pode fornecer o status_sessao e o valor_sessao diretamente. Se não fornecidos, o status é auto-calculado (cancelamento > venda > não convertida) e o valor é a soma dos tickets de venda. As métricas do cliente (total gasto, pedidos, etc.) são recalculadas com base nas sessões convertidas.

Clientes

Cadastro e consulta de clientes vinculados à empresa.

Cadastrar cliente

POST/api/externo/clientes

Cadastra um novo cliente ou retorna o existente se o telefone já estiver registrado na empresa. Idempotente por telefone.

Autenticação

Header X-API-Key

Body (JSON)

Campo	Tipo	Obrig.	Descrição
`nome`	`string`	Sim	Nome completo do cliente
`telefone`	`string`	Sim	Telefone do cliente (mín. 8 dígitos)
`canal_origem`	`string`	Não	Canal de origem (ex: "whatsapp", "instagram")

Respostas

201Cliente criado

{
  "ok": true,
  "cliente": {
    "id": "uuid",
    "nome": "Maria Silva",
    "telefone": "11999999999"
  },
  "existente": false
}

200Cliente já existente

{
  "ok": true,
  "cliente": {
    "id": "uuid",
    "nome": "Maria Silva",
    "telefone": "11999999999"
  },
  "existente": true
}

401API key inválida

{ "error": "API key inválida ou empresa inativa" }

400Body inválido

{ "error": "Body inválido. Campos: nome (string), telefone (string), canal_origem? (string)" }

cURL Request

curl -X POST https://app.metricsfarma.cloud/api/externo/clientes \
  -H "X-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Silva",
    "telefone": "11999999999",
    "canal_origem": "whatsapp"
  }'

Atendimentos

Registro de atendimentos (tickets). Cada atendimento é vinculado automaticamente a uma sessão do dia (1 sessão por cliente por dia). A IA pode fornecer o status e valor da sessão diretamente, ou deixar o sistema auto-calcular.

Listar atendimentos do dia

GET/api/externo/atendimentos

Retorna todos os atendimentos de um cliente em uma data, em ordem cronológica. Chamado antes de processar o ticket atual, retorna apenas os tickets já registrados no dia — usados como contexto pela IA.

Autenticação

Header X-API-Key

Query Params

Campo	Tipo	Obrig.	Descrição
`telefone`	`string`	Sim	Telefone do cliente com DDI (ex: 556186518376)
`data`	`string`	Sim	Data no formato YYYY-MM-DD (ex: 2026-04-25)

Respostas

200Sucesso

{
  "ok": true,
  "cliente_id": "uuid-do-cliente",
  "atendimentos": [
    {
      "chatplus_id": "473264",
      "horario": "08:12",
      "status": "nao_convertido",
      "valor_venda": null,
      "produtos": [],
      "resumo_ia": "Cliente perguntou sobre preço, não finalizou."
    },
    {
      "chatplus_id": "473391",
      "horario": "09:31",
      "status": "venda",
      "valor_venda": 45.25,
      "produtos": ["Vitamina D"],
      "resumo_ia": "Cliente comprou Vitamina D 2000UI."
    }
  ]
}

200Sem atendimentos na data

{
  "ok": true,
  "cliente_id": "uuid-do-cliente",
  "atendimentos": []
}

401API key inválida

{ "error": "API key inválida ou empresa inativa" }

400Parâmetros ausentes

{ "error": "Parâmetros obrigatórios: telefone, data" }

404Cliente não encontrado

{ "error": "Cliente não encontrado" }

cURL Request

curl -X GET "https://app.metricsfarma.cloud/api/externo/atendimentos?telefone=556186518376&data=2026-04-25" \
  -H "X-API-Key: SUA_API_KEY"

Registrar atendimento

POST/api/externo/atendimentos

Registra um novo atendimento (ticket). Cria ou atualiza a sessão do dia automaticamente. A IA pode definir status_sessao e valor_sessao; se omitidos, são auto-calculados dos tickets. Recalcula métricas do cliente com base em todas as sessões convertidas.

Autenticação

Header X-API-Key

Body (JSON)

Campo	Tipo	Obrig.	Descrição
`cliente_id`	`uuid`	Sim	ID do cliente (deve pertencer à empresa da API key)
`chatplus_id`	`string`	Sim	ID único do atendimento no Chatplus. Garante idempotência — se duplicado, retorna o existente com sucesso.
`status`	`enum`	Sim	"venda" \| "sem_resposta" \| "nao_convertido" \| "cancelamento" \| "ignorado"
`valor_venda`	`number`	Não	Valor da venda (usado apenas quando status = "venda")
`resumo_ia`	`string`	Não	Resumo do ticket gerado pela IA (exibido no painel)
`resumo_sessao`	`string`	Não	Resumo global da sessão do dia (contexto acumulado)
`status_sessao`	`enum`	Não	"convertida" \| "cancelada" \| "nao_convertida" \| "ignorada" — Status da sessão definido pela IA. Se omitido, auto-calcula dos tickets.
`valor_sessao`	`number`	Não	Valor total gerado na sessão (definido pela IA). Se omitido, soma os valores dos tickets de venda.
`produtos`	`string[]`	Não	Lista de produtos mencionados (ex: ["Vitamina D", "Ômega 3"])
`categorias`	`string[]`	Não	Categorias do atendimento (ex: ["dermocosméticos", "suplementos"])
`canal_origem`	`string`	Não	Canal de origem do atendimento
`data_atendimento`	`ISO 8601`	Não	Data/hora do atendimento. Se omitido, usa a data atual.
`motivo_perda`	`string`	Não	Motivo da perda/cancelamento
`ticket_id`	`number`	Não	ID do clique de anúncio (vem da mensagem inicial do lead, formato T<id>). Faz lookup em tracking_clicks e popula gclid/UTMs no atendimento + first-touch no cliente.
`gclid`	`string`	Não	gclid direto (fallback se não tiver ticket_id).
`utm_source`	`string`	Não	utm_source direto (fallback).
`utm_campaign`	`string`	Não	utm_campaign direto (fallback).

Respostas

201Atendimento criado

{
  "ok": true,
  "atendimento": { "id": "uuid" },
  "sessao": {
    "id": "uuid",
    "status": "convertida",
    "valor_total": 189.9
  }
}

200Atendimento já existente (chatplus_id duplicado)

{
  "ok": true,
  "atendimento": { "id": "uuid" },
  "existente": true
}

401API key inválida

{ "error": "API key inválida ou empresa inativa" }

400Body inválido

{ "error": "Body inválido", "detail": [...] }

404Cliente não encontrado

{ "error": "Cliente não encontrado nesta empresa" }

cURL Request

curl -X POST https://app.metricsfarma.cloud/api/externo/atendimentos \
  -H "X-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": "uuid-do-cliente",
    "chatplus_id": "cp_12345",
    "status": "venda",
    "valor_venda": 189.90,
    "resumo_ia": "Cliente comprou Vitamina D e Ômega 3",
    "resumo_sessao": "Sessão com venda de R$ 189,90",
    "status_sessao": "convertida",
    "valor_sessao": 189.90,
    "produtos": ["Vitamina D", "Ômega 3"],
    "data_atendimento": "2026-03-15T14:00:00",
    "ticket_id": 1234
  }'

Rastreamento de tráfego pago

Endpoint público de redirect que captura cliques de anúncios (gclid + UTMs) e direciona o lead pro WhatsApp com um ticket único. Configurado por empresa em /configuracoes → Rastreamento.

Redirect de captura

GET/r/{slug}

Use essa URL como destino do botão "Falar no WhatsApp" da landing page. Quando o lead clica, o endpoint registra o clique (idempotente por gclid) e devolve um 302 pra wa.me já com a mensagem do template incluindo T<id>. O n8n da MetricsFarma lê esse ticket da primeira mensagem do contato e inclui no payload de POST /api/externo/atendimentos, amarrando o atendimento ao clique original.

Autenticação

Header Pública (sem API key — slug já identifica a empresa)

Query Params

Campo	Tipo	Obrig.	Descrição
`gclid`	`string`	Não	Google Click ID (auto-anexado pelo Google Ads quando auto-tagging está ativo).
`fbclid`	`string`	Não	Facebook Click ID.
`utm_source`	`string`	Não	Origem da campanha.
`utm_medium`	`string`	Não	Meio (cpc, organic, email...).
`utm_campaign`	`string`	Não	Nome da campanha.
`utm_term`	`string`	Não	Palavra-chave.
`utm_content`	`string`	Não	Identificador do criativo.
`lp`	`string`	Não	URL da landing page de origem (override do referer).

Respostas

302Redirect pro WhatsApp

Location: https://wa.me/5511999999999?text=Ol%C3%A1!%20Vim%20pelo%20an%C3%BAncio.%20Ticket%3A%20T1234

(Cabeçalho HTTP, sem body)

404Slug inválido ou config inativa

(empty)

cURL Request

# 1. Configure em /configuracoes → Rastreamento (slug = drogaria-mundial, número, mensagem template).
# 2. Use no botão da LP:
#    <a href="https://app.metricsfarma.cloud/r/drogaria-mundial">Falar no WhatsApp</a>
# 3. O Google Ads anexa ?gclid=... automaticamente.
# 4. Teste no terminal:

curl -i "https://app.metricsfarma.cloud/r/drogaria-mundial?gclid=teste123&utm_source=google&utm_campaign=remedios"

# Resposta (302):
# HTTP/1.1 302 Found
# Location: https://wa.me/5511999999999?text=Ol%C3%A1!...T1234

Códigos de erro

Status	Descrição
400	Body inválido ou campos obrigatórios ausentes
401	API key ausente, inválida ou empresa inativa
404	Recurso não encontrado (ex: cliente não pertence à empresa)
409	Conflito — registro duplicado (chatplus_id já existe)
500	Erro interno do servidor