Negócios

deals_list

Carteira de negócios abertos. Os negócios abertos, com filtro por dono, etapa, fase, temperatura, atalhos (sem próximo passo, parados, commit, cliente devendo, sem forecast), classe de perfil e busca por nome do negócio ou da conta, com ordem e paginação. Traz o id de cada negócio para deal_get. O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.list — a mesma de GET /v1/deals
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
ownerId	string (uuid)	não	Dono do CRM cuja carteira ver (admin e líder). Ausente: todos os donos. O vendedor sempre vê só a própria
stageId	string (uuid)	não	Só os negócios nesta etapa do CRM
phase	"prospecting" | "discovery" | "qualification" | "solution" | "proposal" | "negotiation"	não	Só os negócios cuja etapa está nesta fase padronizada
temperature	"cold" | "warm" | "hot"	não	Só os negócios nesta faixa de temperatura (leitura); sem estado compilado não entra
flag	"no_next_step" | "stalled" | "commit" | "buyer_owing" | "no_forecast"	não	no_next_step: nenhum próximo passo lido nem no CRM; stalled: parado além do prazo da etapa e sem nada agendado (mesma regra do risco); commit: categoria de previsão commit ou upside; buyer_owing: cliente devendo — compromisso do cliente lido nas conversas, com prazo até hoje e sem resposta dele desde então (leitura); no_forecast: sem forecast — negócio a partir da etapa em que o funil pede a declaração, sem categoria ou sem data de fechamento de hoje em diante
profileClass	"inside" | "partial" | "outside" | "unknown"	não	Só os negócios nesta classe de perfil de cliente (raio X): inside dentro, partial parcial, outside fora, unknown sem dado; sem critério declarado nem sugerido para o funil do negócio, ele não entra em nenhuma classe
search	string	não	Parte do nome do negócio ou da conta (mín. 1 caractere; máx. 120 caracteres)
sort	"impact" | "stage" | "close_date" | "last_contact"	não	impact: valor × chance de referência da fase, maior primeiro; stage: fase mais avançada primeiro; close_date: fechamento mais próximo primeiro, sem data no fim; last_contact: contato mais antigo primeiro, nunca contatado antes (padrão "impact")
page	integer	não	Página, começando em 1 (mín. 1; padrão 1)
size	integer	não	Negócios por página (máximo 200) (mín. 1; máx. 200; padrão 50)

Resultado

O JSON da resposta de sucesso de GET /v1/deals, com os mesmos campos.

deal_get

Raio X do negócio. Tudo sobre um negócio: fatos do CRM, etapa lida nas conversas, temperatura com a conta e o diagnóstico, pessoas, reuniões com resumo, objeções, compromissos, próximo passo, processo de decisão, concorrentes, linha do tempo e sugestões de campo em revisão. Leituras vêm rotuladas como leitura. O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.get — a mesma de GET /v1/deals/{dealId}
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo, como deals_list ou deals_search devolvem

Resultado

O JSON da resposta de sucesso de GET /v1/deals/{dealId}, com os mesmos campos.

deal_state

Estado compilado do negócio. O que as conversas do negócio dizem, somado por regra: pessoas e papéis, objeções, compromissos, próximo passo, processo de decisão, sinais de compra, adiamentos, concorrentes e a etapa sustentada, cada item apontando a conversa e os trechos de origem, mais a temperatura (0 a 100). O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.state — a mesma de GET /v1/deals/{dealId}/state
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo, como deals_list ou deals_search devolvem

Resultado

O JSON da resposta de sucesso de GET /v1/deals/{dealId}/state, com os mesmos campos.

deal_conversations_list

Conversas do negócio, em cartões. As conversas do negócio, das mais novas para as mais antigas: reuniões gravadas e cada conversa vinculada (WhatsApp, e-mail, notas e ligações do CRM), com título, período, duração, mensagens, pessoas com o lado, áudio e transcrição disponíveis, a linha do Nexo e qual ferramenta baixa a transcrição (transcriptDownload: meeting → download_meeting_transcript, whatsapp_session → download_whatsapp_transcript, email_thread → download_email_transcript), sempre com o conversationId; nulo, e sem áudio, quando a pessoa não pode baixar aquela conversa pela regra de escopo dos downloads. Filtre por canal e busque com q, que procura também no que foi dito nas conversas que a pessoa pode abrir. Exige o escopo conversations:read. O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.conversations — a mesma de GET /v1/deals/{dealId}/conversations
Escopo	conversations:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	sim
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo
page	integer	não	Página, a partir de 1 (mín. 1; padrão 1)
pageSize	integer	não	Cartões por página, até 100 (mín. 1; máx. 100; padrão 24)
channel	"meeting" | "whatsapp" | "email" | "note" | "call" | "crm_whatsapp"	não	Só um canal: meeting, whatsapp, email (caixa conectada e CRM), note, call ou crm_whatsapp
q	string	não	Busca, sem diferenciar maiúsculas e acentos, no título, nas pessoas (nome ou e-mail), na linha do Nexo e no que foi dito ou escrito na conversa, este só nas conversas que a pessoa pode abrir (mín. 1 caractere; máx. 120 caracteres)

Resultado

O JSON da resposta de sucesso de GET /v1/deals/{dealId}/conversations, com os mesmos campos. Por trazer conteúdo de conversa, o resultado vem com dois itens de texto: primeiro o aviso de conteúdo de terceiros, depois o JSON.

deal_next_step_get

Próximo passo registrado no negócio. O último próximo passo registrado por uma pessoa no negócio (o que foi combinado, data, quem deve, observação), se ele ainda vale (inEffect: false quando uma conversa posterior trouxe outro), o histórico com quem registrou e por onde, e o que aconteceu no CRM (crm.status). O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.nextstep.get — a mesma de GET /v1/deals/{dealId}/next-step
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo, como deals_list ou deals_search devolvem

Resultado

O JSON da resposta de sucesso de GET /v1/deals/{dealId}/next-step, com os mesmos campos.

deal_next_step_set

Registrar o próximo passo do negócio. Registra o próximo passo de um negócio, como o Radar do Vendedor: o que foi combinado (what), a data (dueDate, AAAA-MM-DD, de hoje em diante), quem deve (owedBy: seller = o vendedor, client = o cliente) e uma observação opcional (note, por exemplo o que foi combinado por telefone; fica só no Nexo). Vale na hora no Radar (Sem próximo passo, Próximo passo vencido) e em Negócios, e sobe para o HubSpot em segundo plano: o texto em hs_next_step (o campo de próximo passo mapeado) e a data no campo de data mapeado, ou no texto quando não há. Sobrescreve o próximo passo que está no CRM: antes de chamar, mostre à pessoa o que vai ser gravado e espere o sim dela. Exige o escopo deals:write. O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa.

Operação	deals.nextstep.set — a mesma de PUT /v1/deals/{dealId}/next-step
Escopo	deals:write
Papéis	admin, líder de vendas, vendedor
Classe de limite	crm_write
Auditada	sim
Comportamento	escreve · destrutiva: o cliente deve pedir confirmação

Entrada

Campo	Tipo	Obrigatório	Descrição
what	string	sim	O que foi combinado com o cliente (mín. 1 caractere; máx. 500 caracteres)
dueDate	string	sim	Data do próximo passo, AAAA-MM-DD; de hoje em diante, no fuso da empresa (formato ^\d{4}-\d{2}-\d{2}$)
owedBy	"seller" | "client"	sim	Quem deve o próximo passo: seller = o vendedor (Você); client = o cliente
note	string | null	não	Observação opcional (“Combinado por telefone? Registre aqui”); fica no Nexo e não sobe para o CRM (máx. 2000 caracteres)
dealId	string (uuid)	sim	Id do negócio no Nexo, como deals_list ou deals_search devolvem

Resultado

O JSON da resposta de sucesso de PUT /v1/deals/{dealId}/next-step, com os mesmos campos.

deal_context

Contexto do negócio como o modelo do Nexo lê. A seção do negócio exatamente como qualquer análise do Nexo a recebe: fatos do CRM, campos personalizados em uso, pessoas e próximo passo, mais o significado de cada campo. Só admin e líder de vendas.

Operação	deals.context — a mesma de GET /v1/deals/{dealId}/context
Escopo	context:read
Papéis	admin, líder de vendas
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo

Resultado

O JSON da resposta de sucesso de GET /v1/deals/{dealId}/context, com os mesmos campos.

tasks_today

O que fazer hoje. A lista do dia do vendedor, gerada por regra às 7h no fuso da empresa e a cada mudança relevante: reuniões do dia, compromissos vencendo, follow-ups sem resposta, fechamento escorregando, negócios parados, campos esperando revisão. O vendedor vê só o próprio dia; admin e líder escolhem o vendedor por ownerId.

Operação	tasks.today — a mesma de GET /v1/tasks/today
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
ownerId	string (uuid)	não	Dono do CRM de quem ver o dia; só admin e líder escolhem, o vendedor sempre vê o próprio

Resultado

O JSON da resposta de sucesso de GET /v1/tasks/today, com os mesmos campos.

review_queue

Negócios com campos esperando revisão. Um cartão por negócio com cada sugestão de campo do CRM em aberto: o que o Nexo leu, o que o CRM tem e a situação. Só leitura: nada é aprovado nem escrito no CRM por aqui. O vendedor vê os próprios negócios; admin e líder de vendas veem todos e podem filtrar por dono.

Operação	review.queue — a mesma de GET /v1/review/suggestions
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
ownerId	string (uuid)	não	Show only the deals of this owner; managers only

Resultado

O JSON da resposta de sucesso de GET /v1/review/suggestions, com os mesmos campos.

review_deal

Sugestões de campo de um negócio. Cada sugestão em aberto de um negócio: a propriedade do CRM com tipo e opções, o valor no CRM agora, o valor que o Nexo leu, o motivo e as evidências. O vendedor vê os próprios negócios; admin e líder de vendas veem todos e podem filtrar por dono.

Operação	review.deal — a mesma de GET /v1/review/deals/{dealId}
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
dealId	string (uuid)	sim	Id do negócio no Nexo

Resultado

O JSON da resposta de sucesso de GET /v1/review/deals/{dealId}, com os mesmos campos.

deals_search

Buscar negócios. Busca negócios no CRM por parte do nome, vendedor, situação (aberto, ganho, perdido) e falta de próxima atividade. Devolve o total encontrado e os maiores por valor, com etapa, vendedor, valor e datas. Use o id devolvido para abrir um negócio. É a mesma consulta que o copiloto do Nexo faz, na visibilidade da pessoa; não roda IA.

Operação	deals.search — consulta do copiloto, sem rota /v1
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
busca	string	não	Parte do nome do negócio, como aparece no CRM (mín. 2 caracteres; máx. 120 caracteres)
vendedor	string	não	Nome do vendedor como aparece na lista do time. Sem ele, a consulta é do time inteiro (mín. 1 caractere; máx. 120 caracteres)
situacao	"aberto" | "ganho" | "perdido"	não	Sem ela, qualquer situação
semProximaAtividade	boolean	não	true = só negócios sem próxima atividade marcada no CRM
limite	integer	não	Quantos negócios listar, até 20 (padrão 10) (mín. 1; máx. 20)

Resultado

Um JSON compacto em português, o mesmo que o copiloto do Nexo recebe para esta consulta. Não há rota /v1 equivalente.

deals_at_risk

Negócios em risco. Negócios abertos em risco pelas regras do CRM (data de fechamento vencida, data adiada duas vezes ou mais, sem próxima atividade), com os dez de maior impacto, o motivo de cada um e quanto do pipeline aberto está em risco. Do time ou de um vendedor. É a mesma consulta que o copiloto do Nexo faz, na visibilidade da pessoa; não roda IA.

Operação	deals.risks — consulta do copiloto, sem rota /v1
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
vendedor	string	não	Nome do vendedor como aparece na lista do time. Sem ele, a consulta é do time inteiro (mín. 1 caractere; máx. 120 caracteres)

Resultado

Um JSON compacto em português, o mesmo que o copiloto do Nexo recebe para esta consulta. Não há rota /v1 equivalente.