Pessoas (Persons)

Gerencie pessoas (clientes, fornecedores, leads, contatos) vinculadas a sua empresa.

Listar Pessoas

GET /external/v1/persons

Retorna uma lista paginada de pessoas.

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 nome, razao social ou documento
personType	string	Nao	Filtro por tipo: INDIVIDUAL ou COMPANY
classification	string	Nao	Filtro por classificacao: CUSTOMER, SUPPLIER, LEAD, PARTNER
orderBy	string	Nao	Campo de ordenacao: name, 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/persons?page=1&limit=10&personType=COMPANY" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Resposta (200):

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9i0j1",
      "name": "Tech Solutions Ltda",
      "socialName": "Tech Solutions Tecnologia Ltda",
      "documentNumber": "12345678000190",
      "personType": "COMPANY",
      "email": "contato@techsolutions.com.br",
      "phone": "+5511999998888",
      "genre": null,
      "country": "BR",
      "classifications": ["CUSTOMER", "PARTNER"],
      "tags": ["tecnologia", "enterprise"],
      "isActive": true,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-02-20T14:45:00.000Z"
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

Buscar Pessoa por ID

GET /external/v1/persons/:id

Exemplo de requisicao:

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

Resposta (200):

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1",
  "name": "Tech Solutions Ltda",
  "socialName": "Tech Solutions Tecnologia Ltda",
  "documentNumber": "12345678000190",
  "personType": "COMPANY",
  "email": "contato@techsolutions.com.br",
  "phone": "+5511999998888",
  "genre": null,
  "country": "BR",
  "classifications": ["CUSTOMER", "PARTNER"],
  "tags": ["tecnologia", "enterprise"],
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Sala 501",
    "neighborhood": "Bela Vista",
    "city": "Sao Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "country": "BR"
  },
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-02-20T14:45:00.000Z"
}

Resposta (404):

{
  "statusCode": 404,
  "message": "RESOURCE_NOT_FOUND",
  "friendlyMessage": "Pessoa nao encontrada."
}

Criar Pessoa

POST /external/v1/persons

Body:

Campo	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome ou razao social (max: 255)
socialName	string	Nao	Nome fantasia
documentNumber	string	Nao	CPF (11 digitos) ou CNPJ (14 digitos), apenas numeros
personType	string	Sim	INDIVIDUAL (pessoa fisica) ou COMPANY (pessoa juridica)
email	string	Nao	Email principal
phone	string	Nao	Telefone com DDI (ex: +5511999998888)
genre	string	Nao	MALE, FEMALE ou OTHER (apenas para INDIVIDUAL)
country	string	Nao	Codigo ISO 3166-1 alpha-2 (default: BR)
classifications	string[]	Nao	Array: CUSTOMER, SUPPLIER, LEAD, PARTNER
tags	string[]	Nao	Tags livres para organizacao

Exemplo de requisicao:

curl -X POST "https://api.tesselys.com.br/external/v1/persons" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "documentNumber": "12345678901",
    "personType": "INDIVIDUAL",
    "email": "maria.oliveira@email.com",
    "phone": "+5521988887777",
    "genre": "FEMALE",
    "country": "BR",
    "classifications": ["CUSTOMER"],
    "tags": ["vip", "indicacao"]
  }'

Resposta (201):

{
  "id": "clx2b3c4d5e6f7g8h9i0j1k2",
  "name": "Maria Oliveira",
  "socialName": null,
  "documentNumber": "12345678901",
  "personType": "INDIVIDUAL",
  "email": "maria.oliveira@email.com",
  "phone": "+5521988887777",
  "genre": "FEMALE",
  "country": "BR",
  "classifications": ["CUSTOMER"],
  "tags": ["vip", "indicacao"],
  "isActive": true,
  "createdAt": "2026-03-25T08:00:00.000Z",
  "updatedAt": "2026-03-25T08:00:00.000Z"
}

Atualizar Pessoa

PUT /external/v1/persons/:id

Atualiza os dados de uma pessoa existente. Envie apenas os campos que deseja alterar.

Exemplo de requisicao:

curl -X PUT "https://api.tesselys.com.br/external/v1/persons/clx2b3c4d5e6f7g8h9i0j1k2" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.novo@email.com",
    "classifications": ["CUSTOMER", "PARTNER"],
    "tags": ["vip", "indicacao", "premium"]
  }'

Resposta (200):

{
  "id": "clx2b3c4d5e6f7g8h9i0j1k2",
  "name": "Maria Oliveira",
  "socialName": null,
  "documentNumber": "12345678901",
  "personType": "INDIVIDUAL",
  "email": "maria.novo@email.com",
  "phone": "+5521988887777",
  "genre": "FEMALE",
  "country": "BR",
  "classifications": ["CUSTOMER", "PARTNER"],
  "tags": ["vip", "indicacao", "premium"],
  "isActive": true,
  "createdAt": "2026-03-25T08:00:00.000Z",
  "updatedAt": "2026-03-25T09:15:00.000Z"
}

Valores de Enum

personType

Valor	Descricao
INDIVIDUAL	Pessoa fisica
COMPANY	Pessoa juridica

genre

Valor	Descricao
MALE	Masculino
FEMALE	Feminino
OTHER	Outro

classifications

Valor	Descricao
CUSTOMER	Cliente
SUPPLIER	Fornecedor
LEAD	Lead / Prospect
PARTNER	Parceiro