Documentação de Inteligência Artificial

Visão Geral

O módulo de Inteligência Artificial (IA) da plataforma Uappi V3 expõe dois recursos principais:

• Chat de IA (Uappi.AI): um assistente conversacional, disponível para usuários autenticados do painel, capaz de consultar e operar sobre os dados da própria loja (pedidos, produtos, clientes, etc.) através de ferramentas internas.
• Credencial de IA: o cadastro do provedor/modelo/token que autentica a loja junto ao provedor de IA e habilita o chat.

Ambos os recursos dependem de uma Credencial de IA configurada e ativa — sem ela, o chat não pode iniciar uma conversa.

Provedores suportados (driver)

A plataforma suporta dois provedores de IA (driver):

• open-ai — modelos GPT/O da OpenAI.
• anthropic — modelos Claude da Anthropic.

Cada driver aceita apenas um subconjunto específico de model. Consulte o endpoint GET /ai/credential/drivers para obter, em tempo real, a lista de drivers e modelos válidos suportados pela versão atual da API — não assuma uma lista fixa, pois novos modelos são adicionados com frequência.

Como o chat funciona

O envio de uma mensagem no chat é assíncrono:

1. POST /ai/chat/user/{chatId}/message grava a mensagem do usuário e retorna imediatamente 202 Accepted, sem aguardar a resposta do assistente. 2. Um processo em background consulta o provedor de IA configurado, eventualmente executa ferramentas internas (consultas/ações sobre pedidos, produtos, clientes, etc., restritas ao escopo do usuário autenticado) e grava a resposta final do assistente. 3. O cliente deve fazer polling em GET /ai/chat/user/{chatId}/message/response até receber 200 OK (resposta pronta) — enquanto o turno ainda está em processamento, este mesmo endpoint responde 202 Accepted.

Entidades Envolvidas

• Credencial de Agente: armazena driver, model e token (chave de API) usados para autenticar a loja junto ao provedor de IA. Existe no máximo uma credencial por loja. Por segurança, o token nunca é reexibido pela API depois de salvo — a consulta (GET /ai/credential) sempre retorna este campo como uma string vazia.
• Chat: uma conversa pertencente a um usuário, com título editável.
• Mensagem de Chat: cada turno de uma conversa (mensagem do usuário ou resposta do assistente), ordenada por um cursor de sequência.

Escopos de permissão

Detalhes da Credencial de IA

Descrição

Este endpoint permite que o administrador da loja visualize a configuração atual da integração de IA. 📋

Através deste recurso, é possível conferir qual provedor de tecnologia está sendo utilizado (driver) e qual modelo de linguagem foi selecionado (ex: gpt-4.1-mini, claude-sonnet-5).

Por segurança, o campo token é sempre retornado como uma string vazia ("") — o valor real da chave de API nunca é reexibido pela API depois de salvo, mesmo para quem tem permissão de leitura.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão AI_CREDENTIAL_READ. 🔒

Consulte a listagem de drivers e modelos (GET /ai/credential/drivers) para saber quais valores de driver/model são válidos antes de configurar a credencial.

---

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/ai/credential \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "driver": "open-ai",
3  "model": "gpt-4.1-mini",
4  "token": "",
5  "createdAt": "2026-05-04 18:00:00",
6  "updatedAt": "2026-07-10 09:15:00"
7}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Listagem de Drivers e Modelos de IA

Descrição

Este endpoint retorna, em tempo real, todos os provedores de IA suportados (driver) e os modelos válidos (model) para cada um. 📋

Use esta consulta para montar dinamicamente a tela de configuração de credencial (PUT /ai/credential) em vez de fixar uma lista de modelos no cliente — novos modelos são adicionados com frequência e uma lista fixa fica desatualizada rapidamente.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão AI_CREDENTIAL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/ai/credential/drivers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1[
2  {
3    "driver": "open-ai",
4    "models": [
5      "gpt-4",
6      "gpt-4-turbo",
7      "gpt-4o",
8      "gpt-4o-mini",
9      "gpt-4.1-nano",
10      "gpt-4.1-mini",
11      "gpt-4.1",
12      "gpt-5-nano",
13      "gpt-5-mini",
14      "gpt-5",
15      "o1",
16      "o1-pro",
17      "o3",
18      "o3-mini",
19      "o4-mini"
20    ]
21  },
22  {
23    "driver": "anthropic",
24    "models": [
25      "claude-fable-5",
26      "claude-opus-5",
27      "claude-sonnet-5",
28      "claude-haiku-4-5-20251001"
29    ]
30  }
31]

> A lista de modelos acima é ilustrativa. Consulte sempre a resposta real deste endpoint — ela reflete exatamente os enums suportados pela versão da API em produção, que evoluem ao longo do tempo.

⚠️ Possíveis erros:

Esta rota não possui erros específicos de regra de negócio.

Configuração de Credencial de IA

Descrição

Este endpoint é o ponto de ativação das funcionalidades de Inteligência Artificial na plataforma. 🛡️

Através dele, o lojista configura os dados necessários para que a Uappi consiga se autenticar junto ao provedor de IA escolhido (OpenAI ou Anthropic).

O processo de configuração é unificado: se a credencial não existir, ela será criada; caso já exista, os valores serão substituídos por completo (não há atualização parcial — envie sempre driver, model e token).

Cada driver só aceita um subconjunto específico de model; um model incompatível com o driver informado é rejeitado. Use o endpoint GET /ai/credential/drivers para obter a lista atual e válida de combinações antes de montar esta requisição.

Recomenda-se cautela ao atualizar o token ou o modelo em horários de pico, pois qualquer erro nas chaves fornecidas pelo provedor interromperá o funcionamento do chat de IA para todos os usuários da loja.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão AI_CREDENTIAL_WRITE. 🔒

Consulte a listagem de drivers e modelos (GET /ai/credential/drivers) para obter a lista atual e válida de combinações.

---

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo (Body)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/ai/credential \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "driver": "anthropic",
6    "model": "claude-sonnet-5",
7    "token": "sk-ant-your-api-key-here"
8  }'

✅ Resposta de Sucesso

1{
2  "driver": "anthropic",
3  "model": "claude-sonnet-5",
4  "token": "sk-ant-your-api-key-here",
5  "createdAt": "2026-05-04 18:00:00",
6  "updatedAt": "2026-07-10 09:15:00"
7}

> A resposta deste endpoint de escrita retorna o token enviado. Já a consulta (GET /ai/credential) sempre mascara o campo como string vazia — não reutilize a resposta deste endpoint para exibir a credencial em tela.

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Remoção de Credencial de IA

Descrição

Este endpoint permite a desativação completa das funcionalidades de IA na plataforma. 🗑️

Ao remover a credencial, o sistema apaga permanentemente o token de acesso e as definições de driver/modelo.

Como consequência imediata, o chat de IA deixa de funcionar para todos os usuários da loja — o envio de novas mensagens passa a exigir uma nova credencial configurada.

Este recurso deve ser utilizado caso o lojista deseje encerrar o uso de serviços de IA ou precise limpar as configurações para realizar uma nova integração do zero. ⚠️

Uma vez removida, a credencial não pode ser recuperada. Para reativar o recurso, será necessário realizar um novo processo de configuração através do endpoint de salvamento (PUT /ai/credential).

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão AI_CREDENTIAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/ai/credential \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1true

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.