Escrever um item à mão

POST

/v1/knowledge/items

const url = 'https://developers.nexo.winningsales.com.br/v1/knowledge/items';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"type":"rule","text":"example","rule":{"subject":"discount","condition":"example","limit":"example","exception":"example","approver":"example"}}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "rule", "text": "example", "rule": { "subject": "discount", "condition": "example", "limit": "example", "exception": "example", "approver": "example" } }'

Cria um item sem material de origem, como na tela; entra em uso na hora. 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

Request Body^required

application/json

object

type

required

Tipo do item

string

Allowed values: rule practice product_fact price proof

text

required

Texto curto do item

string

>= 1 characters <= 240 characters

rule

Campos estruturados, obrigatórios quando 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

Responses

201

Item criado

application/json

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)

Example

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

400

Payload inválido (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"
  }
}

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

Escrever um item à mão

Authorizations

Request Bodyrequired

Responses

201

Example

400

Example generated

401

Example

403

Example

429

Example

Request Body^required

Example ^generated