🚚 Método `transshipment` – Transbordo de Negociação

✅ Descrição Geral

O método transshipment tem como objetivo realizar o transbordo de uma negociação, ou seja, duplicar uma negociação existente e transferi-la para outro funil e/ou estágio, podendo também ser atribuída a um novo responsável (usuário).
Essa operação é utilizada quando a negociação precisa mudar de contexto, sem perder seu histórico ou causar inconsistências nos dados originais.

A nova negociação herda os seguintes dados da original:

Campos customizados (customfields)

Produtos (com preço e quantidade)

Atividades agendadas

Anotações

Pessoas e organizações relacionadas

Responsável (podendo ser alterado)

Relacionamento com a negociação de origem (transshipmentOriginId)

📌 Casos de Uso

Cenário	Descrição
🔁 Funil de Qualificação → Vendas	Após o lead ser qualificado, ele é transbordado para o funil de vendas com o time comercial.
🧑‍💼 Troca de responsável	O responsável atual não é mais o ideal, e a negociação precisa ser movida para outro usuário e etapa.
🧭 Segmentação por área	Transbordar para funis/estágios diferentes com base no tipo de cliente ou segmento.
⚠️ Rastreabilidade de pipeline	O sistema mantém o vínculo entre a negociação original e a nova (`transshipmentOriginId`).

📥 Requisição

Método e Rota

⚙️ Regras e Funcionamento do Transbordo de Negociações

O processo de transbordo segue um conjunto de etapas bem definidas para garantir a integridade, consistência e rastreabilidade dos dados ao mover uma negociação para outro funil ou estágio.

🔍 1. Verificação Inicial dos Dados

Antes de iniciar o processo, o sistema valida se os dados informados são válidos:

Negociação de origem existe

Novo funil e estágio estão corretos

Se for indicado um novo responsável, verifica se o usuário existe

🧠 2. Consulta da Negociação Original

A negociação original é consultada para:

Confirmar que pertence à empresa do usuário autenticado

Coletar todas as informações necessárias, como:

Funil e estágio atuais

Anotações e atividades

Campos personalizados

Responsável atual

Pessoas e empresas associadas

Produtos vinculados

Motivo de perda (se houver)

🛡️ 3. Verificação de Acesso ao Novo Funil e Estágio

O sistema garante que o usuário tem permissão para acessar o novo funil e o estágio definidos para o transbordo.

👤 4. Validação do Novo Responsável (Se Informado)

Se um novo responsável for indicado para a nova negociação:

O sistema confirma que ele pertence à empresa

Caso não seja encontrado, o processo é interrompido e é emitida uma mensagem de erro

🔁 5. Verificação de Negociação Duplicada

Para evitar duplicações indevidas, o sistema analisa se há outra negociação no destino com os mesmos dados principais (como telefone e campos personalizados). Se detectada, a nova negociação é marcada como duplicada.

🧬 6. Criação da Nova Negociação

Uma nova negociação é criada com base na original, preservando:

Todos os dados principais

Vínculo com a negociação de origem

Data em que o transbordo foi realizado

Identificação como duplicada, se aplicável

🧷 7. Cópia de Informações Relacionadas

A nova negociação também herda:

Todos os campos personalizados

Todas as atividades vinculadas

Produtos adicionados

Anotações anteriores

Observações adicionais informando que se trata de uma negociação transbordada, com data e referência da original

📦 8. Revalidação Final dos Dados

O sistema recarrega todos os dados da nova negociação para garantir que tudo esteja completo e disponível:

Informações do funil e estágio

Campos personalizados

Atividades e produtos

Anotações

Pessoa e organização vinculadas

Responsável pela negociação

Motivo de perda (caso aplicável)

🔄 9. Integrações e Notificações

Se a empresa tiver integrações ativas (como CRMs, notificações externas, etc.), essas serão acionadas automaticamente.

Caso esteja habilitada a opção de envio de notificações via WhatsApp, o novo responsável será notificado (respeitando as permissões da empresa).

🛑 Possíveis Mensagens de Erro

Código	Mensagem	Explicação
404	Negociação não encontrada	A negociação de origem não existe
400	Usuário não encontrado	O novo responsável informado não foi localizado
400	Funil ou estágio inválido	Os dados de destino não existem ou não são válidos
500	Erro interno	Problema ao carregar os dados do responsável

🔎 Considerações Técnicas Importantes

O processo não altera nem remove a negociação original.

A nova negociação criada mantém uma ligação direta com a negociação de origem, permitindo rastreabilidade.

Notificações automáticas só são enviadas se configuradas corretamente pela empresa.

Campos importantes como o responsável devem estar corretamente carregados para evitar erros.

📎 Boas Práticas Recomendadas

Certifique-se de que o novo funil e estágio são válidos antes de iniciar o transbordo.

Sempre verifique se o novo responsável pertence à mesma empresa.

Mantenha os dados da negociação completos (pessoas, campos obrigatórios etc.).

Use o transbordo sempre que a negociação mudar de contexto para manter o histórico limpo e rastreável.

curl --location --request PUT 'https://api.cubosuite.com.br/deals/change/transshipment' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": 145, "pipeId": 10, "userId": 56, "stageId": 21 }'

{ "id": 987654, "title": "Negociação Transbordada - Cliente Exemplo", "value": 7500, "status": "open", "transshipmentOriginId": 123456, "transshipmentDate": "2025-07-07T15:35:00.000-03:00", "pipeId": 3, "stageId": 9, "userId": 4501, "expectClosingDate": "2025-07-30", "customfields": [ { "id": 101, "customfieldId": 22, "value": "Instagram", "customfield": { "name": "Canal de Aquisição", "context": "deal", "companyId": 88, "type": "text", "status": "active", "showCard": true, "createdAt": "2024-12-01T10:00:00.000-03:00", "updatedAt": "2025-05-01T10:00:00.000-03:00" } } ], "activities": [ { "id": 777, "type": "call", "description": "Ligação para agendamento", "status": "done", "dueDate": "2025-07-06T15:00:00.000-03:00" } ], "annotations": [ { "id": 2001, "type": "alteration", "text": "Data de transbordo: 'Sem informação' → 07/07/2025 15:35:00 (ID da negociação de origem #123456)", "userId": 4501 }, { "id": 2002, "type": "observation", "text": "Negociação transbordada (ID da negociação gerada #987654)", "userId": 4501 } ], "products": [ { "id": 501, "name": "Consultoria Digital", "meta": { "pivot_price": 7500, "pivot_quantity": 1 } } ], "user": { "id": 4501, "name": "Carlos Tech", "phone": "+55 11 91234-5678", "email": "carlos.tech@empresaexemplo.com", "status": "active", "type": "consultor", "picture": null, "companyId": 88, "sendNotificationWhatsapp": true, "company": { "id": 88, "name": "TechNova Solutions", "status": "active", "segment": "Serviços de TI", "completedOnboarding": 1, "createdAt": "2023-01-01T00:00:00.000-03:00", "updatedAt": "2025-07-07T15:00:00.000-03:00" }, "meta": { "messagesAtOnce": 50, "send_evolution_notification": 1 } }, "organization": { "id": 321, "name": "Cliente Exemplo LTDA", "cnpj": "12.345.678/0001-90" }, "people": { "id": 654, "name": "João Exemplo", "phone": "+55 11 98888-0000", "email": "joao@clienteexemplo.com" }, "pipe": { "id": 3, "name": "Pós-Venda", "users": [ { "id": 4501, "name": "Carlos Tech" } ], "stages": [ { "id": 9, "name": "Aguardando Contrato" }, { "id": 10, "name": "Em Implantação" } ] }, "stage": { "id": 9, "name": "Aguardando Contrato" }, "lostReason": null, "createdAt": "2025-07-07T15:35:00.000-03:00", "updatedAt": "2025-07-07T15:35:00.000-03:00" }

Requisição

Authorization

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

Parâmetros Header

Content-Type

string

requerido

Exemplo:

application/json

Parâmetros Bodyapplication/json

integer

requerido

pipeId

integer

requerido

userId

integer

requerido

stageId

integer

opcional

Examples

Respostas

🟢200Success

application/json

Body

integer

requerido

title

string

requerido

value

integer

requerido

status

string

requerido

transshipmentOriginId

integer

requerido

transshipmentDate

string

requerido

pipeId

integer

requerido

stageId

integer

requerido

userId

integer

requerido

expectClosingDate

string

requerido

customfields

array [object {4}]

requerido

integer

opcional

customfieldId

integer

opcional

value

string

opcional

customfield

object

opcional

activities

array [object {5}]

requerido

integer

opcional

type

string

opcional

description

string

opcional

status

string

opcional

dueDate

string

opcional

annotations

array [object {4}]

requerido

integer

requerido

type

string

requerido

text

string

requerido

userId

integer

requerido

products

array [object {3}]

requerido

integer

opcional

name

string

opcional

Transborda uma negociação específica

🚚 Método transshipment – Transbordo de Negociação#

✅ Descrição Geral#

📌 Casos de Uso#

📥 Requisição#

Método e Rota#

⚙️ Regras e Funcionamento do Transbordo de Negociações#

🔍 1. Verificação Inicial dos Dados#

🧠 2. Consulta da Negociação Original#

🛡️ 3. Verificação de Acesso ao Novo Funil e Estágio#

👤 4. Validação do Novo Responsável (Se Informado)#

🔁 5. Verificação de Negociação Duplicada#

🧬 6. Criação da Nova Negociação#

🧷 7. Cópia de Informações Relacionadas#

📦 8. Revalidação Final dos Dados#

🔄 9. Integrações e Notificações#

🛑 Possíveis Mensagens de Erro#

🔎 Considerações Técnicas Importantes#

📎 Boas Práticas Recomendadas#

Requisição

Respostas

🚚 Método `transshipment` – Transbordo de Negociação

✅ Descrição Geral

📌 Casos de Uso

📥 Requisição

Método e Rota

⚙️ Regras e Funcionamento do Transbordo de Negociações

🔍 1. Verificação Inicial dos Dados

🧠 2. Consulta da Negociação Original

🛡️ 3. Verificação de Acesso ao Novo Funil e Estágio

👤 4. Validação do Novo Responsável (Se Informado)

🔁 5. Verificação de Negociação Duplicada

🧬 6. Criação da Nova Negociação

🧷 7. Cópia de Informações Relacionadas

📦 8. Revalidação Final dos Dados

🔄 9. Integrações e Notificações

🛑 Possíveis Mensagens de Erro

🔎 Considerações Técnicas Importantes

📎 Boas Práticas Recomendadas