Pedir o envio de um material

POST

/v1/knowledge/materials

const url = 'https://developers.nexo.winningsales.com.br/v1/knowledge/materials';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"fileName":"example","sizeInBytes":1,"category":"policy","name":"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/materials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "fileName": "example", "sizeInBytes": 1, "category": "policy", "name": "example" }'

Confere formato, tamanho e espaço livre, cria o material e devolve uma URL assinada, válida por 15 minutos, para enviar o arquivo direto ao armazenamento com PUT, com o Content-Type devolvido. Depois do envio, confirme a versão: só então o material entra na base e é lido. Um pedido nunca confirmado some sozinho. O arquivo nunca passa pela API: o envio e o download são por link assinado do armazenamento, e cada link gasta a classe file (60 por minuto na empresa, 30 por token). 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

fileName

required

Nome do arquivo com a extensão. A extensão define o formato: pdf, docx, pptx, xlsx, md ou txt

string

>= 1 characters <= 255 characters

sizeInBytes

required

Tamanho do arquivo em bytes, como o navegador informa. O limite é 25 MB

integer

category

required

Tipo do material: policy (política), playbook, pricing (preços), product (produto), case, presentation (apresentação) ou other (outro)

string

Allowed values: policy playbook pricing product case presentation other

name

Nome do material na base. Ausente: o nome do arquivo

string

nullable >= 1 characters <= 200 characters

Responses

201

Material criado e URL de envio

application/json

object

material

required

O material criado, ainda aguardando o arquivo. Só aparece na lista depois da confirmação

object

required

Id do material

string format: uuid

name

required

Nome do material na base

string

category

required

Tipo do material: policy (política), playbook, pricing (preços), product (produto), case, presentation (apresentação) ou other (outro)

string

Allowed values: policy playbook pricing product case presentation other

fileName

required

Nome do arquivo da versão atual, usado no download

string

format

required

Formato da versão atual

string

Allowed values: pdf docx pptx xlsx md txt

sizeInBytes

required

Tamanho da versão atual em bytes. Antes da confirmação, o tamanho informado no pedido

integer

version

required

Número da versão atual, começando em 1

integer

status

required

Awaiting_upload: o arquivo ainda não foi confirmado; stored: guardado; rejected: recusado na confirmação

string

Allowed values: awaiting_upload stored rejected

uploadedAt

required

Quando a versão atual foi guardada, ou pedida quando ainda não chegou

string format: date-time

uploadedBy

required

Quem subiu a versão atual. Null quando a pessoa não está mais na empresa

object

required

Id de quem subiu

string format: uuid

name

required

Nome de quem subiu

string

versionId

required

Id da versão a confirmar depois do envio

string format: uuid

upload

required

Como enviar o arquivo: PUT do corpo cru na URL, com estes cabeçalhos

object

url

required

URL assinada para enviar o arquivo direto ao armazenamento

string format: uri

method

required

Método HTTP do envio

string

Allowed values: PUT

headers

required

Cabeçalhos obrigatórios do envio

object

Content-Type

required

Tipo do conteúdo que o envio precisa mandar, igual ao assinado

string

expiresAt

required

Quando a URL de envio deixa de funcionar (15 minutos)

string format: date-time

Example

{
  "material": {
    "category": "policy",
    "format": "pdf",
    "status": "awaiting_upload"
  },
  "upload": {
    "method": "PUT"
  }
}

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

422

Formato não aceito, arquivo acima de 25 MB ou base sem espaç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": "knowledge.unsupported_format",
  "title": "UnsupportedMaterialFormatError",
  "status": 422,
  "detail": "O arquivo Proposta.key não é aceito. Suba em PDF, DOCX, PPTX, XLSX, MD ou TXT.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "fileName": "Proposta.key",
    "accepted": "PDF, DOCX, PPTX, XLSX, MD ou TXT"
  }
}

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

502

O armazenamento não assinou a URL de envio

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

Pedir o envio de um material

Authorizations

Request Bodyrequired

Responses

201

Example

400

Example generated

401

Example

403

Example

422

Example

429

Example

502

Example generated

Request Body^required

Example ^generated

Example ^generated