Prévia da remoção de um item

POST

/v1/knowledge/items/{itemId}/removal-preview

const url = 'https://developers.nexo.winningsales.com.br/v1/knowledge/items/example/removal-preview';
const options = {method: 'POST', 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 POST \
  --url https://developers.nexo.winningsales.com.br/v1/knowledge/items/example/removal-preview \
  --header 'Authorization: Bearer <token>'

O item e o que a remoção faz, sem remover nada. Devolve também uma confirmação, que o MCP exige para remover e para resolver com discard; pelo REST, o DELETE e o discard removem direto. Só administradores, como a Base de conhecimento na tela Calibração; o papel é relido a cada chamada, e para mudar o token precisa do escopo calibration:write.

Authorizations

bearer

Parameters

Path Parameters

itemId

required

Id do item

Responses

200

A prévia

application/json

object

item

required

O item que sairia da base

object

required

Id do item

string format: uuid

version

required

Versão do item

integer

type

required

Tipo do item

string

Allowed values: rule practice product_fact price proof

text

required

Texto curto do item

string

origin

required

De onde veio o item

string

Allowed values: material manual edited

status

required

Situação do item

string

Allowed values: in_use pending disabled superseded

pendingReason

required

Por que está pendente, ou null

string

nullable

Allowed values: conflict ambiguous proof

conflictWith

required

O outro lado do conflito, quando pendingReason é conflict

object

required

string format: uuid

text

required

string

source

required

object

materialId

required

Id do material de origem

string format: uuid

materialName

required

Nome do material

string

fileName

required

Nome do arquivo

string

page

required

Índice da página de origem

integer

nullable

pageLabel

required

Rótulo da página (“p. 3” ou “aba Preços”)

string

nullable

excerpt

required

Trecho literal que sustenta o item

string

rule

required

Campos estruturados, só para type rule

object

subject

required

Assunto da regra comercial

string

Allowed values: discount minimum_price deadline payment_terms integration scope implementation

condition

required

Condição que ativa a regra, ou null

string

nullable <= 240 characters

limit

required

Valor do limite, ou null

string

nullable <= 240 characters

exception

required

Exceção conhecida, ou null

string

nullable <= 240 characters

approver

required

Quem aprova uma exceção, ou null

string

nullable <= 120 characters

sources

required

Materiais e trechos que sustentam o item

Array<object>

object

materialId

required

Id do material de origem

string format: uuid

materialName

required

Nome do material

string

fileName

required

Nome do arquivo

string

page

required

Índice da página de origem

integer

nullable

pageLabel

required

Rótulo da página (“p. 3” ou “aba Preços”)

string

nullable

excerpt

required

Trecho literal que sustenta o item

string

withoutMaterial

required

Verdadeiro quando nenhuma fonte ativa sustenta mais o item

boolean

updatedAt

required

Quando o item mudou pela última vez

string format: date-time

usage

required

Reservado para o contador de uso (entrega futura)

effect

required

O que a remoção faz, em português, para mostrar à pessoa antes de confirmar

string

confirmation

required

A confirmação que a remoção pelo MCP exige

object

token

required

Passe este token na chamada que remove; ele só vale para esta remoção, desta pessoa

string

expiresAt

required

Até quando o token vale (10 minutos)

string format: date-time

Example

{
  "item": {
    "type": "rule",
    "origin": "material",
    "status": "in_use",
    "pendingReason": "conflict",
    "rule": {
      "subject": "discount"
    }
  }
}

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

Item inexistente ou já removido

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": "knowledge.item_not_found",
  "title": "ItemNotFoundError",
  "status": 404,
  "detail": "Item não encontrado na base de conhecimento.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "itemId": "019fcae7-3e54-755a-8458-bdb605b324dd"
  }
}

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