Base de conhecimento

knowledge_search

Base de conhecimento. Os itens em uso da Base de conhecimento da empresa: regras comerciais (desconto, preço mínimo, prazo, forma de pagamento, integração, escopo, implantação), práticas de venda, fatos de produto, preços e planos e provas aprovadas, cada um com id, versão e fonte (arquivo e página). Consulte antes de afirmar condição comercial, preço, prazo, o que o produto inclui ou uma prova; sem item que responda, diga que a Base não cobre. É a mesma consulta que o copiloto do Nexo faz, na visibilidade da pessoa; não roda IA.

Operação	knowledge.search — consulta do copiloto, sem rota /v1
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
tipo	"rule" | "practice" | "product_fact" | "price" | "proof"	não	Tipo de item: rule (regra comercial), practice (prática de venda), product_fact (fato de produto), price (preço e plano) ou proof (prova). Sem ele, todos os tipos
assunto	"discount" | "minimum_price" | "deadline" | "payment_terms" | "integration" | "scope" | "implementation"	não	Assunto de regra comercial: discount, minimum_price, deadline, payment_terms, integration, scope ou implementation. Filtra só regra

Resultado

Um JSON compacto em português, o mesmo que o copiloto do Nexo recebe para esta consulta. Não há rota /v1 equivalente.

knowledge_items_list

Itens da base de conhecimento. Os itens curtos que a IA do Nexo usa (regras, práticas, fatos de produto, preços, provas), com a situação, as fontes e, num conflito, o outro lado. needsYou: true traz só as pendências (conflito, ambíguo, prova). Para buscar o que a base diz sobre um assunto, use knowledge_search. Só administradores, como a Base de conhecimento na Calibração.

Operação	knowledge.items.list — a mesma de GET /v1/knowledge/items
Escopo	context:read
Papéis	admin
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
page	integer	não	Página, começando em 1 (mín. 1; padrão 1)
pageSize	integer	não	Itens por página (mín. 1; máx. 100; padrão 25)
searchText	string	sim	Esta listagem não aceita busca (mín. 1 caractere; máx. 120 caracteres)
searchFields	string[]	sim	Esta listagem não aceita campo de busca
orderBy	string[]	sim	Esta listagem não aceita ordenação
type	"rule" | "practice" | "product_fact" | "price" | "proof"	não	Só os itens deste tipo
needsYou	boolean	não	Só os itens pendentes (precisam de alguém)

Resultado

O JSON da resposta de sucesso de GET /v1/knowledge/items, com os mesmos campos.

knowledge_item_create

Escrever um item à mão. Cria um item sem material de origem; entra em uso na hora em todas as análises. Para type rule, mande os campos da regra. Confirme o texto com a pessoa antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.create — a mesma de POST /v1/knowledge/items
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve

Entrada

Campo	Tipo	Obrigatório	Descrição
type	"rule" | "practice" | "product_fact" | "price" | "proof"	sim	Tipo do item
text	string	sim	Texto curto do item (mín. 1 caractere; máx. 240 caracteres)
rule	object | null	não	Campos estruturados, obrigatórios quando type é rule
rule.subject	"discount" | "minimum_price" | "deadline" | "payment_terms" | "integration" | "scope" | "implementation"	sim, se rule for enviado	Assunto da regra comercial
rule.condition	string | null	sim, se rule for enviado	Condição que ativa a regra, ou null (máx. 240 caracteres)
rule.limit	string | null	sim, se rule for enviado	Valor do limite, ou null (máx. 240 caracteres)
rule.exception	string | null	sim, se rule for enviado	Exceção conhecida, ou null (máx. 240 caracteres)
rule.approver	string | null	sim, se rule for enviado	Quem aprova uma exceção, ou null (máx. 120 caracteres)

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/items, com os mesmos campos.

knowledge_item_edit

Editar um item. Troca o texto ou os campos da regra de um item. Gera uma revisão nova, e o item nunca mais é sobrescrito pela compilação do material. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.edit — a mesma de PATCH /v1/knowledge/items/{itemId}
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento
text	string	não	Novo texto (mín. 1 caractere; máx. 240 caracteres)
rule	object	não	Novos campos estruturados
rule.subject	"discount" | "minimum_price" | "deadline" | "payment_terms" | "integration" | "scope" | "implementation"	sim, se rule for enviado	Assunto da regra comercial
rule.condition	string | null	sim, se rule for enviado	Condição que ativa a regra, ou null (máx. 240 caracteres)
rule.limit	string | null	sim, se rule for enviado	Valor do limite, ou null (máx. 240 caracteres)
rule.exception	string | null	sim, se rule for enviado	Exceção conhecida, ou null (máx. 240 caracteres)
rule.approver	string | null	sim, se rule for enviado	Quem aprova uma exceção, ou null (máx. 120 caracteres)

Resultado

O JSON da resposta de sucesso de PATCH /v1/knowledge/items/{itemId}, com os mesmos campos.

knowledge_item_disable

Desativar um item. Tira o item de uso sem apagar; knowledge_item_enable o volta. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.disable — a mesma de POST /v1/knowledge/items/{itemId}/disable
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/items/{itemId}/disable, com os mesmos campos.

knowledge_item_enable

Reativar um item. Volta a em uso um item desativado. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.enable — a mesma de POST /v1/knowledge/items/{itemId}/enable
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/items/{itemId}/enable, com os mesmos campos.

knowledge_item_resolve

Resolver uma pendência da base. choose escolhe este lado de um conflito (o outro vira substituído); approve aprova uma prova; use aceita um item ambíguo como está; rewrite reescreve (com text) e aceita; discard descarta o item de vez, como remover, e por isso exige o confirmationToken de knowledge_item_removal_preview deste item. Mostre os dois lados e pergunte à pessoa antes: escolher ou descartar tira um item de uso. Nunca remova sem a pessoa ter visto a prévia e dito sim nesta conversa: mostre o que sai de uso, pergunte, e só então chame com o confirmation.token. O token vale 10 minutos, só para aquele item ou material, e cai se alguém mudá-lo antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.resolve — a mesma de POST /v1/knowledge/items/{itemId}/resolve
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente · destrutiva: o cliente deve pedir confirmação

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento
action	"choose" | "approve" | "use" | "rewrite" | "discard"	sim	choose escolhe este lado do conflito; approve aprova a prova; use aceita o ambíguo; rewrite reescreve; discard descarta
text	string	não	Texto novo, usado só com rewrite (mín. 1 caractere; máx. 240 caracteres)
confirmationToken	string	não	O confirmation.token que a prévia da remoção deste mesmo item ou material devolveu; vale 10 minutos (mín. 1 caractere; máx. 4096 caracteres)

Resultado

O mesmo JSON de POST /v1/knowledge/items/{itemId}/resolve: o item resolvido. Diferente da rota, descartar (action: discard) exige o confirmationToken de knowledge_item_removal_preview.

knowledge_item_removal_preview

Prévia da remoção de um item. Primeiro passo para remover um item: o item e o que a remoção faz, sem remover nada, e um confirmation.token para knowledge_item_remove (ou para knowledge_item_resolve com discard, que também tira o item de vez). Nunca remova sem a pessoa ter visto a prévia e dito sim nesta conversa: mostre o que sai de uso, pergunte, e só então chame com o confirmation.token. O token vale 10 minutos, só para aquele item ou material, e cai se alguém mudá-lo antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.preview — a mesma de POST /v1/knowledge/items/{itemId}/removal-preview
Escopo	calibration:write
Papéis	admin
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/items/{itemId}/removal-preview, com os mesmos campos.

knowledge_item_remove

Remover um item. Segundo passo: remove o item que knowledge_item_removal_preview mostrou, com o confirmation.token dela. O item some das análises e não volta com o mesmo trecho do material. Nunca remova sem a pessoa ter visto a prévia e dito sim nesta conversa: mostre o que sai de uso, pergunte, e só então chame com o confirmation.token. O token vale 10 minutos, só para aquele item ou material, e cai se alguém mudá-lo antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.items.delete — a mesma de DELETE /v1/knowledge/items/{itemId}
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente · destrutiva: o cliente deve pedir confirmação

Entrada

Campo	Tipo	Obrigatório	Descrição
itemId	string (uuid)	sim	Id do item da base de conhecimento
confirmationToken	string	sim	O confirmation.token que a prévia da remoção deste mesmo item ou material devolveu; vale 10 minutos (mín. 1 caractere; máx. 4096 caracteres)

Resultado

{ "removed": true, "itemId": "<id>" }. A rota DELETE /v1/knowledge/items/{itemId} responde 204 sem corpo e remove direto; a ferramenta só remove com o confirmationToken de knowledge_item_removal_preview.

knowledge_materials_list

Materiais da base de conhecimento. Os materiais guardados (política, playbook, preços, cases), do mais novo para o mais antigo. Só administradores, como a Base de conhecimento na Calibração.

Operação	knowledge.materials.list — a mesma de GET /v1/knowledge/materials
Escopo	context:read
Papéis	admin
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
page	integer	não	Página, começando em 1 (mín. 1; padrão 1)
pageSize	integer	não	Itens por página (mín. 1; máx. 100; padrão 25)
searchText	string	sim	Busca em name (mín. 1 caractere; máx. 120 caracteres)
searchFields	string[]	sim	campo de busca. Permitidos: name
orderBy	string[]	sim	Esta listagem não aceita ordenação
category	"policy" | "playbook" | "pricing" | "product" | "case" | "presentation" | "other"	não	Só os materiais deste tipo

Resultado

O JSON da resposta de sucesso de GET /v1/knowledge/materials, com os mesmos campos.

knowledge_usage

Espaço usado pela base de conhecimento. Bytes guardados, versões anteriores incluídas, contra o limite de 1 GB da empresa. Só administradores, como a Base de conhecimento na Calibração.

Operação	knowledge.materials.usage — a mesma de GET /v1/knowledge/materials/usage
Escopo	context:read
Papéis	admin
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Nenhum argumento.

Resultado

O JSON da resposta de sucesso de GET /v1/knowledge/materials/usage, com os mesmos campos.

knowledge_material_upload

Pedir o envio de um material. Primeiro passo para subir um arquivo (PDF, DOCX, PPTX, XLSX, MD ou TXT, até 25 MB): cria o material e devolve upload.url, assinada por 15 minutos. Quem tem o arquivo faz PUT do corpo cru nessa URL com o Content-Type devolvido; depois chame knowledge_material_confirm. 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 Calibração. Exige o escopo calibration:write.

Operação	knowledge.materials.upload — a mesma de POST /v1/knowledge/materials
Escopo	calibration:write
Papéis	admin
Classe de limite	file
Auditada	sim
Comportamento	escreve

Entrada

Campo	Tipo	Obrigatório	Descrição
fileName	string	sim	Nome do arquivo com a extensão. A extensão define o formato: pdf, docx, pptx, xlsx, md ou txt (mín. 1 caractere; máx. 255 caracteres)
sizeInBytes	integer	sim	Tamanho do arquivo em bytes, como o navegador informa. O limite é 25 MB (mín. 0)
category	"policy" | "playbook" | "pricing" | "product" | "case" | "presentation" | "other"	sim	Tipo do material: policy (política), playbook, pricing (preços), product (produto), case, presentation (apresentação) ou other (outro)
name	string | null	não	Nome do material na base. Ausente: o nome do arquivo (mín. 1 caractere; máx. 200 caracteres)

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/materials, com os mesmos campos.

knowledge_material_confirm

Confirmar o envio de um material. Segundo passo, depois do PUT: confere o conteúdo, guarda o material e o põe na leitura, que compila os itens. Confirmar de novo uma versão guardada devolve o material sem refazer nada. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.materials.confirm — a mesma de POST /v1/knowledge/materials/{materialId}/versions/{versionId}/confirm
Escopo	calibration:write
Papéis	admin
Classe de limite	file
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
materialId	string (uuid)	sim	Id do material devolvido no pedido de envio
versionId	string (uuid)	sim	Id da versão devolvido no pedido de envio

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/materials/{materialId}/versions/{versionId}/confirm, com os mesmos campos.

knowledge_material_download

Link para baixar um material. URL assinada da versão atual de um material, válida por 5 minutos, com o nome original do arquivo. Vale para todo o time, como no app, porque a busca na base cita materiais. 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).

Operação	knowledge.materials.download — a mesma de POST /v1/knowledge/materials/{materialId}/download-url
Escopo	context:read
Papéis	admin, líder de vendas, vendedor
Classe de limite	file
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
materialId	string (uuid)	sim	Id do material da base de conhecimento

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/materials/{materialId}/download-url, com os mesmos campos.

knowledge_material_change

Renomear ou trocar o tipo de um material. Muda o nome ou o tipo de um material; o arquivo não muda. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.materials.change — a mesma de PATCH /v1/knowledge/materials/{materialId}
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
materialId	string (uuid)	sim	Id do material da base de conhecimento
name	string	não	Novo nome do material (mín. 1 caractere; máx. 200 caracteres)
category	"policy" | "playbook" | "pricing" | "product" | "case" | "presentation" | "other"	não	Tipo do material: policy (política), playbook, pricing (preços), product (produto), case, presentation (apresentação) ou other (outro)

Resultado

O JSON da resposta de sucesso de PATCH /v1/knowledge/materials/{materialId}, com os mesmos campos.

knowledge_material_removal_preview

Prévia da remoção de um material. Primeiro passo para remover um material: quantos itens dependem só dele e sairiam de uso, quantos continuam por outras fontes, sem remover nada, e um confirmation.token para knowledge_material_remove. Nunca remova sem a pessoa ter visto a prévia e dito sim nesta conversa: mostre o que sai de uso, pergunte, e só então chame com o confirmation.token. O token vale 10 minutos, só para aquele item ou material, e cai se alguém mudá-lo antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.materials.preview — a mesma de POST /v1/knowledge/materials/{materialId}/removal-preview
Escopo	calibration:write
Papéis	admin
Classe de limite	read
Auditada	não
Comportamento	somente leitura · idempotente

Entrada

Campo	Tipo	Obrigatório	Descrição
materialId	string (uuid)	sim	Id do material da base de conhecimento

Resultado

O JSON da resposta de sucesso de POST /v1/knowledge/materials/{materialId}/removal-preview, com os mesmos campos.

knowledge_material_remove

Remover um material. Segundo passo: remove o material que knowledge_material_removal_preview mostrou, com o confirmation.token dela. Apaga os arquivos de todas as versões e tira de uso os itens que dependiam só dele; não dá para desfazer. Nunca remova sem a pessoa ter visto a prévia e dito sim nesta conversa: mostre o que sai de uso, pergunte, e só então chame com o confirmation.token. O token vale 10 minutos, só para aquele item ou material, e cai se alguém mudá-lo antes. Só administradores, como a Base de conhecimento na Calibração. Exige o escopo calibration:write.

Operação	knowledge.materials.delete — a mesma de DELETE /v1/knowledge/materials/{materialId}
Escopo	calibration:write
Papéis	admin
Classe de limite	write
Auditada	sim
Comportamento	escreve · idempotente · destrutiva: o cliente deve pedir confirmação

Entrada

Campo	Tipo	Obrigatório	Descrição
materialId	string (uuid)	sim	Id do material da base de conhecimento
confirmationToken	string	sim	O confirmation.token que a prévia da remoção deste mesmo item ou material devolveu; vale 10 minutos (mín. 1 caractere; máx. 4096 caracteres)

Resultado

{ "removed": true, "materialId": "<id>" }. A rota DELETE /v1/knowledge/materials/{materialId} responde 204 sem corpo e remove direto; a ferramenta só remove com o confirmationToken de knowledge_material_removal_preview.