Registrar o próximo passo do negócio

PUT

/v1/deals/{dealId}/next-step

const url = 'https://developers.nexo.winningsales.com.br/v1/deals/example/next-step';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"what":"example","dueDate":"example","owedBy":"seller","note":"example"}'
};

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

curl --request PUT \
  --url https://developers.nexo.winningsales.com.br/v1/deals/example/next-step \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "what": "example", "dueDate": "example", "owedBy": "seller", "note": "example" }'

O próximo passo do Radar do Vendedor em 2 cliques: o que foi combinado, a data e quem deve (o vendedor ou o cliente), com uma observação opcional (“Combinado por telefone? Registre aqui”). O Nexo guarda cada registro com quem, quando e por onde, e o próximo passo passa a valer na hora no estado do negócio: o Radar (Sem próximo passo, Próximo passo vencido) e Negócios já leem ele na próxima chamada, até uma conversa posterior trazer outro. Em segundo plano, o texto vai para o campo de próximo passo do CRM (hs_next_step no HubSpot) e a data para o campo de data mapeado para o próximo passo, numa escrita só; sem campo de data mapeado, a data vai no texto. Sem o campo de próximo passo mapeado ou sem escrita no CRM, o registro fica só no Nexo (crm.status nexo_only). A observação nunca sobe para o CRM. O vendedor registra nos próprios negócios; admin e líder de vendas, nos negócios do time. Exige o escopo deals:write, que nenhum token recebe por padrão; cada registro fica na atividade da empresa.

Authorizations

bearer

Parameters

Path Parameters

dealId

required

string

Id do negócio no Nexo

Request Body^required

application/json

object

what

required

O que foi combinado com o cliente

string

>= 1 characters <= 500 characters

dueDate

required

Data do próximo passo, AAAA-MM-DD; de hoje em diante, no fuso da empresa

string

/^\d{4}-\d{2}-\d{2}$/

owedBy

required

Quem deve o próximo passo: seller = o vendedor (Você); client = o cliente

string

Allowed values: seller client

note

Observação opcional (“Combinado por telefone? Registre aqui”); fica no Nexo e não sobe para o CRM

string

nullable <= 2000 characters

Responses

200

O próximo passo do negócio depois do registro

application/json

object

dealId

required

Id do negócio

string

current

required

O último próximo passo registrado por uma pessoa; nulo se ninguém registrou

object

required

Id do registro

string

what

required

O que foi combinado

string

dueDate

required

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

string

owedBy

required

Quem deve o próximo passo: seller = o vendedor (Você); client = o cliente

string

Allowed values: seller client

note

required

Observação de quem registrou

string

nullable

setAt

required

Quando foi registrado

string

setByUserId

required

Quem registrou

string

nullable

surface

required

Por onde foi registrado: app, API (rest), CLI ou MCP

string

Allowed values: app rest cli mcp

crm

required

O que aconteceu com o registro no CRM

object

status

required

Pending: subindo para o CRM em segundo plano; written: gravado no CRM; nexo_only: o CRM não tem o campo de próximo passo mapeado ou não aceita escrita, então fica só no Nexo; failed: o CRM recusou (motivo em detail); superseded: um registro mais novo substituiu este antes de subir

string

Allowed values: pending written nexo_only failed superseded

detail

required

Por que não subiu, quando não subiu

string

nullable

writtenAt

required

Quando foi gravado no CRM

string

nullable

inEffect

required

True quando o último registro ainda é o próximo passo do negócio no Radar e em Negócios; false quando uma conversa posterior trouxe outro próximo passo, ou quando ninguém registrou

boolean

history

required

Os registros mais recentes, do mais novo para o mais antigo (até 10)

Array<object>

object

required

Id do registro

string

what

required

O que foi combinado

string

dueDate

required

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

string

owedBy

required

Quem deve o próximo passo: seller = o vendedor (Você); client = o cliente

string

Allowed values: seller client

note

required

Observação de quem registrou

string

nullable

setAt

required

Quando foi registrado

string

setByUserId

required

Quem registrou

string

nullable

surface

required

Por onde foi registrado: app, API (rest), CLI ou MCP

string

Allowed values: app rest cli mcp

crm

required

O que aconteceu com o registro no CRM

object

status

required

string

Allowed values: pending written nexo_only failed superseded

detail

required

Por que não subiu, quando não subiu

string

nullable

writtenAt

required

Quando foi gravado no CRM

string

nullable

Example

{
  "current": {
    "owedBy": "seller",
    "surface": "app",
    "crm": {
      "status": "pending"
    }
  },
  "history": [
    {
      "owedBy": "seller",
      "surface": "app",
      "crm": {
        "status": "pending"
      }
    }
  ]
}

400

Entrada inválida (detalhes do zod em meta.errors)

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"
  }
}

404

Negócio inexistente ou fora da visibilidade do dono do token

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": "deals.not_found",
  "title": "DealNotFoundError",
  "status": 404,
  "detail": "Negócio não encontrado.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "dealId": "019fcae7-3e54-755a-8458-bdb605b324aa"
  }
}

409

O negócio já foi fechado

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": "deals.next_step_deal_closed",
  "title": "NextStepDealClosedError",
  "status": 409,
  "detail": "Este negócio já foi fechado; o próximo passo só é registrado em negócio aberto.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "dealId": "019fcae7-3e54-755a-8458-bdb605b324aa"
  }
}

422

A data do próximo passo já passou

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": "deals.next_step_due_past",
  "title": "NextStepDuePastError",
  "status": 422,
  "detail": "A data do próximo passo (2026-10-01) já passou. Escolha uma data a partir de hoje (2026-10-09).",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "dueDate": "2026-10-01",
    "today": "2026-10-09"
  }
}

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
  }
}

Registrar o próximo passo do negócio

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

400

Example generated

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

Request Body^required

Example ^generated