Leads

Gerencie leads (contatos iniciais e prospects) vinculados a sua empresa.

Listar Leads

GET /external/v1/leads

Retorna uma lista paginada de leads.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
page	number	Nao	Pagina atual (default: 1)
limit	number	Nao	Itens por pagina (default: 20, max: 100)
search	string	Nao	Busca por titulo
status	string	Nao	Filtro por status: NEW, CONTACTED, QUALIFIED, UNQUALIFIED, CONVERTED
orderBy	string	Nao	Campo de ordenacao: title, createdAt (default: createdAt)
order	string	Nao	Direcao: ASC ou DESC (default: DESC)

Exemplo de requisicao:

curl -X GET "https://api.tesselys.com.br/external/v1/leads?page=1&limit=10&status=NEW" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Resposta (200):

{
  "data": [
    {
      "id": "clx7f8g9h0i1j2k3l4m5n6o7",
      "title": "Interesse em plano Enterprise",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "status": "NEW",
      "sourceChannel": "WEBSITE",
      "description": "Contato recebido via formulario do site solicitando demonstracao.",
      "tags": ["enterprise", "inbound"],
      "isActive": true,
      "createdAt": "2026-03-20T09:00:00.000Z",
      "updatedAt": "2026-03-20T09:00:00.000Z"
    }
  ],
  "meta": {
    "total": 34,
    "page": 1,
    "limit": 10,
    "totalPages": 4
  }
}

Buscar Lead por ID

GET /external/v1/leads/:id

Exemplo de requisicao:

curl -X GET "https://api.tesselys.com.br/external/v1/leads/clx7f8g9h0i1j2k3l4m5n6o7" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Resposta (200):

{
  "id": "clx7f8g9h0i1j2k3l4m5n6o7",
  "title": "Interesse em plano Enterprise",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "status": "NEW",
  "sourceChannel": "WEBSITE",
  "description": "Contato recebido via formulario do site solicitando demonstracao.",
  "tags": ["enterprise", "inbound"],
  "isActive": true,
  "createdAt": "2026-03-20T09:00:00.000Z",
  "updatedAt": "2026-03-20T09:00:00.000Z"
}

Criar Lead

POST /external/v1/leads

Body:

Campo	Tipo	Obrigatorio	Descricao
title	string	Sim	Titulo do lead (max: 255)
personId	string	Nao	ID da pessoa vinculada
description	string	Nao	Descricao detalhada do lead
sourceChannel	string	Nao	Canal de origem: WEBSITE, PHONE, EMAIL, REFERRAL, SOCIAL_MEDIA, EVENT, OTHER
tags	string[]	Nao	Tags livres para organizacao

Exemplo de requisicao:

curl -X POST "https://api.tesselys.com.br/external/v1/leads" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prospeccao via LinkedIn - Acme Corp",
    "personId": "clx2b3c4d5e6f7g8h9i0j1k2",
    "description": "Contato iniciado via LinkedIn apos interacao com post sobre automacao.",
    "sourceChannel": "SOCIAL_MEDIA",
    "tags": ["linkedin", "automacao"]
  }'

Resposta (201):

{
  "id": "clx8g9h0i1j2k3l4m5n6o7p8",
  "title": "Prospeccao via LinkedIn - Acme Corp",
  "personId": "clx2b3c4d5e6f7g8h9i0j1k2",
  "personName": "Maria Oliveira",
  "status": "NEW",
  "sourceChannel": "SOCIAL_MEDIA",
  "description": "Contato iniciado via LinkedIn apos interacao com post sobre automacao.",
  "tags": ["linkedin", "automacao"],
  "isActive": true,
  "createdAt": "2026-03-25T14:30:00.000Z",
  "updatedAt": "2026-03-25T14:30:00.000Z"
}

Nota

O lead e criado automaticamente com status NEW. Para alterar o status, utilize o endpoint de atualizacao.

Atualizar Lead

PUT /external/v1/leads/:id

Atualiza os dados de um lead existente. Envie apenas os campos que deseja alterar.

Body (campos opcionais):

Campo	Tipo	Descricao
title	string	Novo titulo
status	string	Novo status: NEW, CONTACTED, QUALIFIED, UNQUALIFIED, CONVERTED
description	string	Nova descricao
tags	string[]	Novas tags (substitui as anteriores)

Exemplo de requisicao:

curl -X PUT "https://api.tesselys.com.br/external/v1/leads/clx8g9h0i1j2k3l4m5n6o7p8" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONTACTED",
    "description": "Reuniao agendada para 28/03. Interesse confirmado em automacao financeira.",
    "tags": ["linkedin", "automacao", "reuniao-agendada"]
  }'

Resposta (200):

{
  "id": "clx8g9h0i1j2k3l4m5n6o7p8",
  "title": "Prospeccao via LinkedIn - Acme Corp",
  "personId": "clx2b3c4d5e6f7g8h9i0j1k2",
  "personName": "Maria Oliveira",
  "status": "CONTACTED",
  "sourceChannel": "SOCIAL_MEDIA",
  "description": "Reuniao agendada para 28/03. Interesse confirmado em automacao financeira.",
  "tags": ["linkedin", "automacao", "reuniao-agendada"],
  "isActive": true,
  "createdAt": "2026-03-25T14:30:00.000Z",
  "updatedAt": "2026-03-25T16:00:00.000Z"
}

Valores de Enum

status

Valor	Descricao
NEW	Lead novo, ainda nao contatado
CONTACTED	Lead contatado, aguardando retorno
QUALIFIED	Lead qualificado com potencial de conversao
UNQUALIFIED	Lead sem perfil ou interesse adequado
CONVERTED	Lead convertido em negocio

sourceChannel

Valor	Descricao
WEBSITE	Formulario ou chat do site
PHONE	Contato telefonico
EMAIL	Contato por email
REFERRAL	Indicacao de cliente ou parceiro
SOCIAL_MEDIA	Redes sociais (LinkedIn, Instagram, etc.)
EVENT	Evento, feira ou conferencia
OTHER	Outro canal