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.

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" — 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"])
`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

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"
  }'

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