Pessoas

Gerencie pessoas (clientes, fornecedores, leads, contatos), seus emails e telefones.

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

Emails de Pessoa (Person Emails)

Listar Emails de Pessoa

`GET /external/v1/person-emails`

Retorna uma lista paginada de emails vinculados a pessoas.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`page`	`number`	Nao	Pagina atual (default: `1`)
`limit`	`number`	Nao	Itens por pagina (default: `20`, max: `100`)
`personId`	`string`	Nao	Filtro por pessoa

Exemplo de requisicao:

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

Resposta (200):

{
  "data": [
    {
      "id": "clxd3l4m5n6o7p8q9r0s1t2u3",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "email": "contato@techsolutions.com.br",
      "isPrimary": true,
      "isActive": true,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "clxd4m5n6o7p8q9r0s1t2u3v4",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "email": "financeiro@techsolutions.com.br",
      "isPrimary": false,
      "isActive": true,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "updatedAt": "2026-02-01T09:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Buscar Email de Pessoa por ID

`GET /external/v1/person-emails/:id`

Exemplo de requisicao:

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

Resposta (200):

{
  "id": "clxd3l4m5n6o7p8q9r0s1t2u3",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "email": "contato@techsolutions.com.br",
  "isPrimary": true,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

Criar Email de Pessoa

`POST /external/v1/person-emails`

Body:

Campo	Tipo	Obrigatorio	Descricao
`personId`	`string`	Sim	ID da pessoa vinculada
`email`	`string`	Sim	Endereco de email
`isPrimary`	`boolean`	Nao	Define como email principal (default: `false`)

Exemplo de requisicao:

curl -X POST "https://api.tesselys.com.br/external/v1/person-emails" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
    "email": "suporte@techsolutions.com.br",
    "isPrimary": false
  }'

Resposta (201):

{
  "id": "clxe5n6o7p8q9r0s1t2u3v4w5",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "email": "suporte@techsolutions.com.br",
  "isPrimary": false,
  "isActive": true,
  "createdAt": "2026-03-25T18:00:00.000Z",
  "updatedAt": "2026-03-25T18:00:00.000Z"
}

Atualizar Email de Pessoa

`PUT /external/v1/person-emails/:id`

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

Body (campos opcionais):

Campo	Tipo	Descricao
`email`	`string`	Novo endereco de email
`isPrimary`	`boolean`	Definir como email principal

Exemplo de requisicao:

curl -X PUT "https://api.tesselys.com.br/external/v1/person-emails/clxe5n6o7p8q9r0s1t2u3v4w5" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "isPrimary": true
  }'

Resposta (200):

{
  "id": "clxe5n6o7p8q9r0s1t2u3v4w5",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "email": "suporte@techsolutions.com.br",
  "isPrimary": true,
  "isActive": true,
  "createdAt": "2026-03-25T18:00:00.000Z",
  "updatedAt": "2026-03-25T18:30:00.000Z"
}

Telefones de Pessoa (Person Phones)

Listar Telefones de Pessoa

`GET /external/v1/person-phones`

Retorna uma lista paginada de telefones vinculados a pessoas.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`page`	`number`	Nao	Pagina atual (default: `1`)
`limit`	`number`	Nao	Itens por pagina (default: `20`, max: `100`)
`personId`	`string`	Nao	Filtro por pessoa

Exemplo de requisicao:

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

Resposta (200):

{
  "data": [
    {
      "id": "clxf6o7p8q9r0s1t2u3v4w5x6",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "phone": "+5511999998888",
      "phoneType": "MOBILE",
      "isPrimary": true,
      "isActive": true,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "clxf7p8q9r0s1t2u3v4w5x6y7",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "phone": "+551133334444",
      "phoneType": "LANDLINE",
      "isPrimary": false,
      "isActive": true,
      "createdAt": "2026-01-15T10:35:00.000Z",
      "updatedAt": "2026-01-15T10:35:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Buscar Telefone de Pessoa por ID

`GET /external/v1/person-phones/:id`

Exemplo de requisicao:

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

Resposta (200):

{
  "id": "clxf6o7p8q9r0s1t2u3v4w5x6",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "phone": "+5511999998888",
  "phoneType": "MOBILE",
  "isPrimary": true,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

Criar Telefone de Pessoa

`POST /external/v1/person-phones`

Body:

Campo	Tipo	Obrigatorio	Descricao
`personId`	`string`	Sim	ID da pessoa vinculada
`phone`	`string`	Sim	Numero de telefone com DDI (ex: `+5511999998888`)
`isPrimary`	`boolean`	Nao	Define como telefone principal (default: `false`)
`phoneType`	`string`	Nao	Tipo: `MOBILE`, `LANDLINE`, `WHATSAPP` (default: `MOBILE`)

Exemplo de requisicao:

curl -X POST "https://api.tesselys.com.br/external/v1/person-phones" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
    "phone": "+5511988887777",
    "isPrimary": false,
    "phoneType": "WHATSAPP"
  }'

Resposta (201):

{
  "id": "clxg8q9r0s1t2u3v4w5x6y7z8",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "phone": "+5511988887777",
  "phoneType": "WHATSAPP",
  "isPrimary": false,
  "isActive": true,
  "createdAt": "2026-03-25T19:00:00.000Z",
  "updatedAt": "2026-03-25T19:00:00.000Z"
}

Atualizar Telefone de Pessoa

`PUT /external/v1/person-phones/:id`

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

Body (campos opcionais):

Campo	Tipo	Descricao
`phone`	`string`	Novo numero de telefone
`isPrimary`	`boolean`	Definir como telefone principal
`phoneType`	`string`	Novo tipo: `MOBILE`, `LANDLINE`, `WHATSAPP`

Exemplo de requisicao:

curl -X PUT "https://api.tesselys.com.br/external/v1/person-phones/clxg8q9r0s1t2u3v4w5x6y7z8" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "isPrimary": true,
    "phoneType": "MOBILE"
  }'

Resposta (200):

{
  "id": "clxg8q9r0s1t2u3v4w5x6y7z8",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "phone": "+5511988887777",
  "phoneType": "MOBILE",
  "isPrimary": true,
  "isActive": true,
  "createdAt": "2026-03-25T19:00:00.000Z",
  "updatedAt": "2026-03-25T19:30: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

phoneType

Valor	Descricao
`MOBILE`	Celular
`LANDLINE`	Telefone fixo
`WHATSAPP`	WhatsApp

Listar Pessoas​

GET /external/v1/persons​

Buscar Pessoa por ID​

GET /external/v1/persons/:id​

Criar Pessoa​

POST /external/v1/persons​

Atualizar Pessoa​

PUT /external/v1/persons/:id​

Emails de Pessoa (Person Emails)​

Listar Emails de Pessoa​

GET /external/v1/person-emails​

Buscar Email de Pessoa por ID​

GET /external/v1/person-emails/:id​

Criar Email de Pessoa​

POST /external/v1/person-emails​

Atualizar Email de Pessoa​

PUT /external/v1/person-emails/:id​

Telefones de Pessoa (Person Phones)​

Listar Telefones de Pessoa​

GET /external/v1/person-phones​

Buscar Telefone de Pessoa por ID​

GET /external/v1/person-phones/:id​

Criar Telefone de Pessoa​

POST /external/v1/person-phones​

Atualizar Telefone de Pessoa​

PUT /external/v1/person-phones/:id​

Valores de Enum​

personType​

genre​

classifications​

phoneType​

Listar Pessoas

`GET /external/v1/persons`

Buscar Pessoa por ID

`GET /external/v1/persons/:id`

Criar Pessoa

`POST /external/v1/persons`

Atualizar Pessoa

`PUT /external/v1/persons/:id`

Emails de Pessoa (Person Emails)

Listar Emails de Pessoa

`GET /external/v1/person-emails`

Buscar Email de Pessoa por ID

`GET /external/v1/person-emails/:id`

Criar Email de Pessoa

`POST /external/v1/person-emails`

Atualizar Email de Pessoa

`PUT /external/v1/person-emails/:id`

Telefones de Pessoa (Person Phones)

Listar Telefones de Pessoa

`GET /external/v1/person-phones`

Buscar Telefone de Pessoa por ID

`GET /external/v1/person-phones/:id`

Criar Telefone de Pessoa

`POST /external/v1/person-phones`

Atualizar Telefone de Pessoa

`PUT /external/v1/person-phones/:id`

Valores de Enum

personType

genre

classifications

phoneType