Itens da base de conhecimento

GET

/v1/knowledge/items

curl --request GET \
  --url 'https://developers.nexo.winningsales.com.br/v1/knowledge/items?page=1&pageSize=25&type=rule' \
  --header 'Authorization: Bearer <token>'

Os itens curtos que a IA do Nexo usa: compilados dos materiais, escritos à mão ou editados, com a situação (em uso, pendente, desativado, substituído), as fontes e, num conflito, o outro lado. Filtre por tipo e por needsYou (as pendências que esperam alguém). 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

Query Parameters

page

Página, começando em 1

integer

default: 1 >= 1

Página, começando em 1

pageSize

Itens por página

integer

default: 25 >= 1 <= 100

Itens por página

searchText

Esta listagem não aceita busca

string

>= 1 characters <= 120 characters

Esta listagem não aceita busca

searchFields

Esta listagem não aceita campo de busca

Array<string>

Esta listagem não aceita campo de busca

orderBy

Esta listagem não aceita ordenação

Array<string>

Esta listagem não aceita ordenação

type

Só os itens deste tipo

string

Allowed values: rule practice product_fact price proof

Só os itens deste tipo

needsYou

Só os itens pendentes (precisam de alguém)

boolean

Só os itens pendentes (precisam de alguém)

Responses

200

Página de itens

Media typeapplication/json

object

data

required

Records of the current page

Array<object>

object

id

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

id

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)

pagination

required

object

page

required

Current page (1-based)

integer

pageSize

required

Records per page

integer

totalRecords

required

Total records matching the filters

integer

totalPages

required

Total pages for the current pageSize

integer

Example

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

400

Filtro inválido

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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
  }
}