Contatos

Pessoas, endereços, tags e anotações.

18 rotas. Todas exigem a chave de API no header Authorization, salvo quando marcadas como públicas. Abrir este módulo no Swagger.

Listar contatos da empresa com paginação

GET /companie/person/list/{skip}/{take}

• skip/take: quantos registros pular e quantos trazer.
• Cada contato vem com tags, anotações, atividades e oportunidades vinculadas.
• Para filtros por tag, origem, cidade ou financeiro, use POST /companie/person/filterAdvanced/....

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
skip	URL	string	sim
take	URL	string	sim
blackList	query	true · false		Só contatos na blacklist (true) ou fora dela (false). Omita para trazer todos.
order	query	name_asc · name_desc · whatsapp_asc · whatsapp_desc · document_asc · document_desc · created_at_asc · created_at_desc		Ordenação. Padrão name_asc.

Respostas

Status	Descrição
200	Página de contatos.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar contatos com filtros avançados

POST /companie/person/filterAdvanced/{filter}/{date_start}/{date_end}

Corpo mínimo (todos estes campos são obrigatórios, mesmo vazios):

{ "tags": [], "campaign_id": [], "skip": 0, "take": 20, "is_vm": false }

• skip/take: paginação.
• is_vm: use false. Com true, a última compra passa a ser lida do campo date_last do cliente.
• tags / tags_excluded: ids de tag (GET /companie/tag) que o contato deve ter / não pode ter.
• campaign_id: ids de campanha de disparo; traz só contatos dessas campanhas.
• key: busca por nome, WhatsApp, e-mail ou CPF/CNPJ.
• blackList: true, false ou "all".
• positions: lista de cargos (texto do campo office).
• created_at e last_purchase: { "filter": "this_month" } ou { "filter": "other_period", "value_start": "2026-01-01", "value_end": "2026-01-31" }.
• qty_payed, value_payed, average_ticket: { "value_start": 100, "filter": "gte" }; com between, informe também value_end.
• origin_type + origin_sales_channel_id ou origin_automation_type: origem do lead.

Atenção: o período da URL (filter, date_start, date_end) filtra pela data de vencimento dos lançamentos financeiros do cliente vinculado, não pela data de cadastro. Com qualquer valor diferente de all, contatos sem lançamento no período ficam de fora. Para filtrar pela data de cadastro, use all na URL e created_at no corpo. Datas no formato YYYY-MM-DD.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
filter	URL	all · today · yesterday · this_week · last_week · this_month · last_month · last_30_days · …	sim
date_start	URL	string		Opcional na URL: pode ser omitido junto com os segmentos seguintes.
date_end	URL	string		Opcional na URL: pode ser omitido junto com os segmentos seguintes.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
tags_excluded	número[]
key	string
tags	número[]	sim
campaign_id	número[]	sim
gender	string
companie_id	número
skip	número	sim
take	número	sim
is_whatsapp	boolean
birthday_month	número
person_debtor	boolean
city	string ou null
state	string ou null
qty_payed	object
qty_payed.value_start	número	sim
qty_payed.value_end	número
qty_payed.filter	gte · lte · between
value_payed	object
value_payed.value_start	número	sim
value_payed.value_end	número
value_payed.filter	gte · lte · between
average_ticket	object
average_ticket.value_start	número	sim
average_ticket.value_end	número
average_ticket.filter	gte · lte · between
last_purchase	object
last_purchase.value_start	string
last_purchase.value_end	string
last_purchase.filter	all · today · yesterday · this_week · last_week · this_month · last_month · last_30_days · …
created_at	object
created_at.value_start	string
created_at.value_end	string
created_at.filter	all · today · yesterday · this_week · last_week · this_month · last_month · last_30_days · …
funnel_id	número ou null
funnel_step_id	número ou null
is_vm	boolean	sim
blackList	boolean ou all
positions	objeto[]
order	name_asc · name_desc · whatsapp_asc · whatsapp_desc · document_asc · document_desc · created_at_asc · created_at_desc
origin_type	sales_channel · input_automation · ``
origin_sales_channel_id	número ou null
origin_automation_type	import · api · instagram · checkout · manual · ``

Respostas

Status	Descrição
200	Página de contatos. Cada item traz também campaign_person com as campanhas do contato.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Detalhar contato

GET /companie/person/detail/{id}

Traz o contato com tags, anotações, atividades e oportunidades vinculadas.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	número	sim	Id do contato.

Respostas

Status	Descrição
200	Contato.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	error_person_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Criar contato

POST /companie/person

• companie_user_id: id do usuário dono do contato; normalmente o dono da chave.
• WhatsApp e telefone são normalizados para DDI+DDD+número (sem DDI, assume 55).
• birth: data YYYY-MM-DD.
• Recusa com 409 se CPF/CNPJ, e-mail ou WhatsApp/telefone já estiverem em outro contato da empresa. Com a opção da empresa que permite contato duplicado, só o CPF/CNPJ é conferido.
• Também cria o cadastro de cliente ligado ao contato. Se o contato tiver WhatsApp e a empresa tiver a automação de boas-vindas ativa, a mensagem entra na fila de envio.
• Endereço: envie depois com PUT /companie/person/address/:id.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
companie_user_id	número	sim
name	string	sim
document	string
organization	string
phone	string
whatsapp	string
email	string
office	string
birth	data ou null
email_secundary	string ou null
whatsapp_secundary	string ou null

Respostas

Status	Descrição
200	Contato criado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_companie_user_id_not_exist (string JSON) ou o objeto de duplicidade abaixo.
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar contato

PUT /companie/person/{id}

Substitui os dados do contato. Envie todos os campos, não só os alterados:

• whatsapp ausente ou vazio apaga o WhatsApp do contato.
• phone é gravado com o mesmo valor do whatsapp; o valor enviado em phone só entra na checagem de duplicidade.
• Campos de texto omitidos ficam como estão; email_secundary e whatsapp_secundary omitidos são apagados.

Recusa com 409 se CPF/CNPJ, e-mail ou WhatsApp/telefone já estiverem em outro contato da empresa. Com a opção da empresa que permite contato duplicado, só o CPF/CNPJ é conferido.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
document	string
name	string	sim
organization	string
phone	string
whatsapp	string
email	string
office	string
birth	data ou null
email_secundary	string ou null
whatsapp_secundary	string ou null

Respostas

Status	Descrição
200	Contato atualizado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	error_person_not_exist (ErrorCode)
409	Dado já usado por outro contato.
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Excluir contato

DELETE /companie/person/{id}

Recusa a exclusão quando o contato:

• está vinculado a qualquer oportunidade (error_exist_opportunity_person_in_person), seja ele o único contato dela ou não. Remova o vínculo ou a oportunidade antes;
• tem cliente com lançamento financeiro (error_exist_financial_in_person).

Tags e anotações do contato são apagadas junto.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Contato excluído.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_not_exist, error_exist_opportunity_person_in_person ou error_exist_financial_in_person em message. (GenericError)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Consultar endereço do contato

GET /companie/person/address/{id}

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Endereço.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	error_person_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Atualizar endereço do contato

PUT /companie/person/address/{id}

Grava o endereço no contato e no cadastro de cliente ligado a ele. zipcode com 8 dígitos sem traço; state é a UF com 2 letras; province é o bairro.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
zipcode	string	sim
address	string	sim
number	string	sim
complement	string
province	string	sim
city	string	sim
state	string	sim
country	string

Respostas

Status	Descrição
200	Contato com o endereço atualizado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Incluir ou tirar contato da blacklist

PUT /companie/person/blacklist/{personId}

Contato na blacklist não recebe mensagens automáticas. Ao incluir (true), as mensagens de WhatsApp pendentes para o contato são bloqueadas. O cadastro de cliente ligado ao contato recebe o mesmo valor.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
personId	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
is_blacklist	boolean	sim	true inclui na blacklist; false tira.

Respostas

Status	Descrição
200	Contato atualizado. Quando há cliente ligado, vem { person, client }; senão, só o contato.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	person_not_exists (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Buscar contatos por texto

GET /companie/person/autocomplete/find

Procura q no nome, WhatsApp, e-mail e CPF/CNPJ dos contatos da empresa. Informe sempre q, skip e take.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
q	query	string	sim	Texto da busca.
skip	query	número	sim
take	query	número	sim
blackList	query	true · false		Só contatos na blacklist (true) ou fora dela (false). Omita para trazer todos.
order	query	name_asc · name_desc · whatsapp_asc · whatsapp_desc · document_asc · document_desc · created_at_asc · created_at_desc		Ordenação. Padrão name_asc.

Respostas

Status	Descrição
200	Contatos encontrados.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar anotações do contato

GET /companie/person/annotation/{personId}

Ordenadas pelo texto da anotação (ordem alfabética), não pela data.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
personId	URL	string	sim

Respostas

Status	Descrição
200	Anotações.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Criar anotação no contato

POST /companie/person/annotation

companie_user_id: autor da anotação; normalmente o dono da chave.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
person_id	número	sim
companie_user_id	número	sim
description	string	sim

Respostas

Status	Descrição
200	Anotação criada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_companie_user_id_not_exist ou error_person_id_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar anotação

PUT /companie/person/annotation/{id}

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
description	string	sim

Respostas

Status	Descrição
200	Anotação atualizada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_annotation_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Excluir anotação

DELETE /companie/person/annotation/{id}

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Anotação excluída.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_annotation_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar todos os vínculos de tag com contato da empresa

GET /companie/personTag

Respostas

Status	Descrição
200	Vínculos contato-tag.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Adicionar tag ao contato

POST /companie/personTag

Pegue o tag_id em GET /companie/tag. Se o contato já tiver a tag, o vínculo é recriado (novo id).

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
person_id	número	sim
tag_id	número	sim

Respostas

Status	Descrição
200	Vínculo criado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_not_exist ou error_tag_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar tags do contato

GET /companie/personTag/person/{personId}

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
personId	URL	string	sim

Respostas

Status	Descrição
200	Vínculos do contato com as tags.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Remover tag do contato

DELETE /companie/personTag/{id}

id é o id do vínculo (person_tag[].id no contato ou id em GET /companie/personTag/person/:personId), não o id da tag.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Tag removida.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_tag_not_exist: vínculo não encontrado. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger