Carteira de negócios abertos

GET

/v1/deals

const url = 'https://developers.nexo.winningsales.com.br/v1/deals?phase=prospecting&temperature=cold&flag=no_next_step&profileClass=inside&sort=impact&page=1&size=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://developers.nexo.winningsales.com.br/v1/deals?phase=prospecting&temperature=cold&flag=no_next_step&profileClass=inside&sort=impact&page=1&size=50' \
  --header 'Authorization: Bearer <token>'

Os negócios abertos, com filtro por dono, etapa, fase, temperatura, sem próximo passo, parados, commit/upside e classe de perfil de cliente, busca por nome do negócio ou da conta, ordem e paginação. Fatos vêm do CRM; temperatura e próximo passo lido vêm do estado compilado pelo Nexo (leitura já pronta, sem custo de IA). O vendedor só enxerga os próprios negócios; admin e líder de vendas enxergam os da empresa, como no app.

Authorizations

bearer

Parameters

Query Parameters

ownerId

Dono do CRM cuja carteira ver (admin e líder). Ausente: todos os donos. O vendedor sempre vê só a própria

string format: uuid

Dono do CRM cuja carteira ver (admin e líder). Ausente: todos os donos. O vendedor sempre vê só a própria

stageId

Só os negócios nesta etapa do CRM

string format: uuid

Só os negócios nesta etapa do CRM

phase

Só os negócios cuja etapa está nesta fase padronizada

string

Allowed values: prospecting discovery qualification solution proposal negotiation

Só os negócios cuja etapa está nesta fase padronizada

temperature

Só os negócios nesta faixa de temperatura (leitura); sem estado compilado não entra

string

Allowed values: cold warm hot

Só os negócios nesta faixa de temperatura (leitura); sem estado compilado não entra

flag

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

string

Allowed values: no_next_step stalled commit buyer_owing no_forecast

profileClass

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

string

Allowed values: inside partial outside unknown

search

Parte do nome do negócio ou da conta

string

>= 1 characters <= 120 characters

Parte do nome do negócio ou da conta

sort

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

string

default: impact

Allowed values: impact stage close_date last_contact

page

Página, começando em 1

integer

default: 1 >= 1

Página, começando em 1

size

Negócios por página (máximo 200)

integer

default: 50 >= 1 <= 200

Negócios por página (máximo 200)

Responses

200

A página da carteira com as contagens dos atalhos

application/json

object

items

required

Negócios da página

Array<object>

object

required

Id do negócio no Nexo

string

name

required

Nome do negócio no CRM

string

accountName

required

Conta (empresa) do negócio no CRM

string

nullable

stageId

required

Etapa atual no CRM

string

nullable

stageLabel

required

Nome da etapa atual no CRM

string

nullable

phase

required

Fase padronizada da etapa; nula quando a etapa não foi mapeada

string

nullable

amountInCents

required

Valor no CRM, em centavos

integer

nullable

currency

required

Moeda do valor

string

temperature

required

Leitura do estado compilado; nula enquanto o negócio não tem estado

object

score

required

0 a 100

integer

band

required

Faixa da temperatura

string

Allowed values: cold warm hot

label

required

Frio, Morno ou Quente

string

nextStep

required

Próximo passo; nulo = nenhum combinado

object

text

required

O que foi combinado; nulo quando o CRM só tem a data da próxima atividade

string

nullable

dueDate

required

Data do próximo passo (AAAA-MM-DD)

string

nullable

source

required

Crm: campo do CRM; reading: lido nas conversas (rotular como leitura); seller: registrado por uma pessoa no Nexo (PUT /deals/{dealId}/next-step), que vale até uma conversa posterior trazer outro

string

Allowed values: crm reading seller

stalledDays

required

Dias desde a última movimentação: entrada na etapa, atividade no CRM ou contato do comprador

integer

stalled

required

Parado pela regra do risco: última atividade além do prazo da etapa e nenhuma atividade ou reunião agendada

boolean

lastBuyerContactAt

required

Último contato do comprador (reunião ou WhatsApp), do estado compilado

string

nullable

lastActivityAt

required

Última atividade registrada no CRM

string

nullable

expectedCloseDate

required

Data de fechamento (AAAA-MM-DD)

string

nullable

estimatedCloseDate

required

Data de fechamento estimada pelo Nexo (AAAA-MM-DD), só para negócio sem data no CRM: entrada na etapa mais a mediana até ganho, senão criação mais o ciclo mediano do funil; nunca vai para o CRM

string

nullable

closeDateEstimated

required

True quando estimatedCloseDate existe: mostrar rotulada como estimada

boolean

forecastCategory

required

Categoria de previsão em vigor: a declarada no Nexo, senão a do CRM

string

nullable

Allowed values: commit upside pipeline omitted

forecast

required

A coluna “Forecast · compromisso e data” da carteira

object

asked

required

O funil já pede a declaração nesta etapa

boolean

pending

required

Pedida e ainda sem categoria ou sem data de hoje em diante

boolean

declaredInNexo

required

A categoria e a data vêm de uma declaração feita no Nexo

boolean

reason

required

O que falta, quando pendente

string

nullable

Allowed values: missing_category missing_date date_passed

pendingDays

required

Dias sem declaração válida, quando pendente

integer

nullable

escalation

required

Degrau da cobrança: tarefa no Meu dia, e-mail diário, atrasado para o gestor e pauta do 1:1

string

nullable

Allowed values: task email late

atRisk

required

Risco pelas regras do CRM; nulo quando nenhuma dispara

object

code

required

Regra de risco de maior peso (closeDateOverdue, closeDateSlipped, noNextActivity)

string

label

required

Nome da regra, pronto para a tela

string

reason

required

O motivo com os fatos, ex.: “última reunião há 12 dias, nada agendado, prazo da etapa 4 dias”

string

profileClass

required

Classe de perfil de cliente do negócio; nula quando não há critério declarado nem sugerido para o funil

object

profileClass

required

Dentro, parcial, fora ou sem dado

string

Allowed values: inside partial outside unknown

source

required

Declared: critérios do admin; suggested: lidos do histórico pelo Nexo

string

Allowed values: declared suggested

ownerId

required

Dono do negócio no CRM

string

nullable

ownerName

required

Nome do dono do negócio

string

nullable

ownerKind

required

Tipo do dono: person, queue (rotular como fila) ou system; nulo sem dono

string

nullable

Allowed values: person queue system

hubspotUrl

required

Link do negócio no HubSpot

string

nullable

total

required

Negócios que atendem a todos os filtros

integer

page

required

Página atual

integer

size

required

Negócios por página

integer

ownerId

required

Dono da carteira; nulo quando admin ou líder vê todos

string

nullable

ownerName

required

Nome do dono da carteira

string

nullable

ownerKind

required

Tipo do dono da carteira: person, queue (rotular como fila) ou system; nulo quando vê todos

string

nullable

Allowed values: person queue system

chips

required

Contagens dos atalhos sobre a carteira com os filtros de dono, etapa, fase e busca, sem temperatura nem flag

object

all

required

Todos

integer

noNextStep

required

Sem próximo passo

integer

stalled

required

Parados além do prazo da etapa, sem nada agendado

integer

cold

required

Frios (leitura)

integer

commit

required

Commit e upside

integer

buyerOwing

required

Cliente devendo: compromisso do cliente lido nas conversas, vencido e sem resposta dele

integer

noForecast

required

Sem forecast: pedido a partir da etapa do funil e ainda não declarado

integer

Example

{
  "items": [
    {
      "temperature": {
        "band": "cold"
      },
      "nextStep": {
        "source": "crm"
      },
      "forecastCategory": "commit",
      "forecast": {
        "reason": "missing_category",
        "escalation": "task"
      },
      "profileClass": {
        "profileClass": "inside",
        "source": "declared"
      },
      "ownerKind": "person"
    }
  ],
  "ownerKind": "person"
}

400

Filtro, ordem ou paginação inválidos

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "requestId": "example",
  "meta": {
    "additionalProperty": "example"
  }
}

401

Token ausente, inválido, expirado ou revogado

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.invalid_credential",
  "title": "InvalidCredentialError",
  "status": 401,
  "detail": "Token de acesso inválido, expirado ou revogado. Crie um novo token de acesso no Nexo.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb"
}

403

Papel, escopo do token ou plano não permitem a operação

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.insufficient_scope",
  "title": "InsufficientScopeError",
  "status": 403,
  "detail": "Este token não tem o escopo conversations:read, exigido por esta operação. Gere um token com esse escopo.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "operation": "conversations.reading",
    "scope": "conversations:read"
  }
}

429

Limite de chamadas da empresa ou do token atingido

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.rate_limited",
  "title": "PublicRateLimitedError",
  "status": 429,
  "detail": "Muitas chamadas em pouco tempo. Tente de novo em 12 segundos.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "class": "content",
    "limitedBy": "company",
    "limit": 120,
    "windowSeconds": 60,
    "retryAfterSeconds": 12
  }
}

Carteira de negócios abertos

Authorizations

Parameters

Query Parameters

Responses

200

Example

400

Example generated

401

Example

403

Example

429

Example

Example ^generated