Negociação

Visão Geral

A entidade Negociação representa negociações dentro de um funil, vinculadas a empresas, usuários, pessoas e organizações, com suporte a campos personalizados, produtos e anotações.

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
`id`	number	Identificador único da negociação	✅ (auto)
`pipeId`	number	ID do pipeline associado	✅
`stageId`	number	ID da etapa atual	✅
`userId`	number	ID do usuário responsável	✅
`peopleId`	number	ID da pessoa associada	✅
`organizationId`	number	ID da organização associada	❌
`price`	number	Valor da negociação	❌
`status`	enum	Status da negociação (`open`, `won`, `lost`)	✅
`createdAt`	DateTime	Data/hora de criação	✅ (auto)
`updatedAt`	DateTime	Data/hora da última atualização	✅ (auto)
`transshipmentOriginId`	number	ID da negociação de origem (transbordo)	❌
`duplicatedId`	number	ID da negociação duplicada	❌

Relacionamentos

Funil: Vinculada a um empresa.

Estágio: Vinculada a uma etapa do funil.

Usuário: Responsável pela negociação.

Pessoa: Pessoa associada à negociação.

Organização: Organização associada (opcional).

Campos personalizados: Campos personalizados.

Produtos: Produtos associados.

Anotações: Anotações da negociação.

Status Disponíveis

Status	Descrição
`open`	Negociação em andamento
`won`	Negociação ganha
`lost`	Negociação perdida

Casos de Uso Detalhados

1. Gestão de Negociações

Cenário: Uma empresa deseja gerenciar negociações de vendas.

Fluxo:

Cria uma negociação com pessoa, organização e produtos.

Associa a um pipeline e etapa.

Atualiza status, move entre etapas e adiciona anotações.

Envia notificações automáticas via WhatsApp.

Benefícios: Controle detalhado do funil de vendas e automação de comunicações.

Regras de Negócio

Criação de Negociações

Vinculação automática à empresa do usuário.

Validação de campos obrigatórios por etapa.

Detecção de duplicatas com base em campos personalizados.

Controle de Acesso

Usuários só gerenciam negociações de sua empresa.

Usuários comuns só acessam suas próprias negociações.

Isolamento por empresa (multi-tenancy).

Segurança

Anotações automáticas para alterações e transbordos.

Validação de integridade em movimentações e atualizações.

Operações Disponíveis

Operação	Descrição	Método HTTP
Listar	Recupera negociações com paginação	GET
Criar	Cria uma nova negociação	POST
Visualizar	Exibe detalhes de uma negociação	GET
Atualizar	Modifica a negociação	PUT/PATCH
Excluir	Remove uma negociação	DELETE
Transbordo	Transfere negociação para outro pipeline	POST

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Validar campos obrigatórios por etapa.

Usar transações para transbordos e atualizações.

Para Usuários

Associar negociações a pessoas e organizações relevantes.

Monitorar duplicatas para evitar redundâncias.

Usar anotações para registrar interações.

Limitações e Restrições

Negociações são específicas por empresa e funil.

Campos obrigatórios devem ser preenchidos ao mover etapas.

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Status Disponíveis#

Casos de Uso Detalhados#

1. Gestão de Negociações#

Regras de Negócio#

Criação de Negociações#

Controle de Acesso#

Segurança#

Operações Disponíveis#

Fluxo de Uso#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#