Skip to content

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

EscopoNecessário para
AI_CREDENTIAL_READVisualizar a credencial de IA configurada e listar drivers/modelos disponíveis.
AI_CREDENTIAL_WRITECriar, atualizar ou remover a credencial de IA.
AI_CHAT_READListar chats, listar mensagens e consultar a resposta de um turno.
AI_CHAT_WRITECriar, editar e remover chats, e enviar novas mensagens.

Documentação do Chat de IA (Uappi.AI)

Visão Geral

O Chat de IA é um assistente conversacional disponível para usuários autenticados do painel. O usuário mantém uma ou mais conversas (chats), cada uma com seu próprio histórico de mensagens.

Pré-requisito obrigatório: a loja precisa ter uma Credencial de IA configurada (driver, model e token). Sem ela, o envio de mensagens falha.

Fluxo assíncrono de envio de mensagem

O envio de mensagem não retorna a resposta do assistente na mesma requisição. O fluxo é:

1. Enviar: POST /ai/chat/user/{chatId}/message — grava a mensagem do usuário e responde imediatamente com 202 Accepted e um requestId. O processamento continua em background. 2. Consultar: GET /ai/chat/user/{chatId}/message/response — faça polling neste endpoint até obter 200 OK (turno pronto). Enquanto o assistente ainda estiver processando (podendo, inclusive, executar ferramentas internas em múltiplas etapas), o mesmo endpoint responde 202 Accepted.

1Cliente                          API                          Background
2   │  POST .../message              │                              │
3   │ ───────────────────────────────▶                              │
4   │        202 { status: processing, requestId }                  │
5   │ ◀───────────────────────────────                               │
6   │                                 │  processa turno (LLM + tools)│
7   │                                 │ ─────────────────────────────▶
8   │  GET .../message/response       │                              │
9   │ ───────────────────────────────▶                              │
10   │        202 { status: processing }  (ainda não terminou)        │
11   │ ◀───────────────────────────────                               │
12   │  GET .../message/response  (poll novamente após um intervalo)  │
13   │ ───────────────────────────────▶                              │
14   │        200 { status: ready, message: {...} }                  │
15   │ ◀───────────────────────────────                               │

Recomenda-se fazer o polling com um intervalo curto (ex.: 1-2s) e um backoff progressivo, respeitando o limite de 60 requisições/minuto deste endpoint.

Como o assistente responde

Durante o processamento de um turno, o assistente pode consultar ou operar sobre dados da loja (ex.: detalhar um pedido, listar produtos) usando as mesmas capacidades descritas na documentação de MCP, sempre restritas ao que o usuário autenticado já teria acesso (mesmas regras de escopo/permissão do painel).

Trava de concorrência

Um chat só processa um turno por vez. Se uma nova mensagem for enviada enquanto o turno anterior ainda está em processamento (janela de até 15 minutos), a API responde com o erro UAPPI_AGENT_CHAT_BUSY (409).

Entidades

  • Chat: id, title, userId, userName, userEmail, createdAt, updatedAt.
  • Mensagem: id, role (user/assistant), message, toolCallId, toolName, sequence (cursor de ordenação, não é timestamp), createdAt. A listagem de mensagens (GET .../message) expõe apenas mensagens de user e respostas de texto do assistant — chamadas/resultados internos de ferramenta não aparecem no histórico visível ao usuário.
  • Turno: retornado pelos endpoints de envio/consulta de resposta — status (processing/ready), chatId, requestId, message (preenchido apenas quando status = ready).

Escopos de permissão

EscopoNecessário para
AI_CHAT_READListar chats, listar mensagens de um chat, consultar a resposta de um turno.
AI_CHAT_WRITECriar, editar e remover chats, e enviar novas mensagens.

Limites (rate limit)

EndpointLimite
POST /ai/chat/user/{chatId}/message10 requisições/minuto
GET /ai/chat/user/{chatId}/message/response60 requisições/minuto

Endpoints deste módulo

MétodoEndpointDescrição
GET/ai/chat/user/allLista os chats do usuário autenticado
POST/ai/chat/userCria um novo chat
PUT/ai/chat/user/{chatId}Edita o título de um chat
DELETE/ai/chat/user/{chatId}Remove um chat
GET/ai/chat/user/{chatId}/messageLista as mensagens de um chat
POST/ai/chat/user/{chatId}/messageEnvia uma nova mensagem (assíncrono)
GET/ai/chat/user/{chatId}/message/responseConsulta a resposta do último turno

Listagem de Chats

GET /ai/chat/user/all

Retorna a lista paginada de chats pertencentes ao usuário autenticado, na loja atual.

Descrição

Retorna os chats do usuário autenticado na loja atual. Um usuário nunca vê chats de outro usuário, mesmo dentro da mesma loja.

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

---

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Paginação

ParâmetroTipoObrigatórioDescrição
limitintegerNãoQuantidade de registros por página
offsetintegerNãoDeslocamento inicial da página

Campos de Ordenação Disponíveis (order)

CampoDescrição
titleTítulo do chat
created_atData de criação
updated_atData da última atualização (padrão: desc, se nenhuma ordenação for informada)
> Este endpoint não aceita filtros de condição (condition) — a listagem sempre retorna todos os chats do usuário autenticado na loja atual.

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/ai/chat/user/all?limit=10&offset=0" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
5      "title": "Como configurar frete grátis",
6      "userId": 42,
7      "userName": "Gabriel Domiciano",
8      "userEmail": "gabriel@loja.com.br",
9      "createdAt": "2026-07-30 14:02:11",
10      "updatedAt": "2026-08-01 09:47:03"
11    }
12  ],
13  "pagination": {
14    "limit": 10,
15    "offset": 0,
16    "pages": 1,
17    "registers": 1
18  }
19}

⚠️ Possíveis erros:

Esta rota não possui erros específicos de regra de negócio. Quando o usuário não possui chats, a listagem retorna registers vazio.

Criação de Chat

POST /ai/chat/user

Cria uma nova conversa vazia, pronta para receber mensagens.

Descrição

Cria um novo chat vazio, pertencente ao usuário autenticado na loja atual. Depois de criado, envie mensagens através de POST /ai/chat/user/{chatId}/message.

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

---

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros do Corpo (Body)

ParâmetroTipoObrigatórioDescrição
titlestringSimTítulo do chat. Máximo de 255 caracteres.

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/ai/chat/user \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "title": "Dúvidas sobre frete"
6  }'

✅ Resposta de Sucesso (201 Created)

1{
2  "id": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
3  "title": "Dúvidas sobre frete",
4  "userId": 42,
5  "userName": "Gabriel Domiciano",
6  "userEmail": "gabriel@loja.com.br",
7  "createdAt": "2026-08-05 10:00:00",
8  "updatedAt": "2026-08-05 10:00:00"
9}

⚠️ Possíveis erros:

Esta rota não possui erros específicos de regra de negócio além da validação padrão (título ausente ou maior que 255 caracteres retorna 422).

Edição de Chat

PUT /ai/chat/user/{chatId}

Atualiza o título de um chat existente.

Descrição

Atualiza o título de um chat já existente, pertencente ao usuário autenticado. Não é possível editar chats de outro usuário.

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

---

Parâmetros

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
chatIdstring (uuid)SimIdentificador do chat a ser editado.

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros do Corpo (Body)

ParâmetroTipoObrigatórioDescrição
titlestringSimNovo título do chat. Máximo de 255 caracteres.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/ai/chat/user/0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "title": "Frete grátis - resolvido"
6  }'

✅ Resposta de Sucesso

1{
2  "id": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
3  "title": "Frete grátis - resolvido",
4  "userId": 42,
5  "userName": "Gabriel Domiciano",
6  "userEmail": "gabriel@loja.com.br",
7  "createdAt": "2026-07-30 14:02:11",
8  "updatedAt": "2026-08-05 10:05:00"
9}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_AGENT_CHAT_NOT_FOUND404O chat informado não existe ou não pertence ao usuário autenticado.

Remoção de Chat

DELETE /ai/chat/user/{chatId}

Remove um chat do usuário autenticado, junto com todo o seu histórico de mensagens.

Descrição

Remove permanentemente um chat pertencente ao usuário autenticado, incluindo todo o seu histórico de mensagens. A ação não pode ser desfeita.

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

---

Parâmetros

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
chatIdstring (uuid)SimIdentificador do chat a ser removido.

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/ai/chat/user/0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1true

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_AGENT_CHAT_NOT_FOUND404O chat informado não existe ou não pertence ao usuário autenticado.

Listagem de Mensagens de um Chat

GET /ai/chat/user/{chatId}/message

Retorna o histórico de mensagens visíveis de um chat (mensagens do usuário e respostas em texto do assistente).

Descrição

Retorna o histórico de mensagens de um chat pertencente ao usuário autenticado.

Apenas mensagens visíveis ao usuário são retornadas: mensagens enviadas pelo próprio usuário e respostas de texto do assistente. Chamadas e resultados internos de ferramentas (usados pelo assistente para consultar/operar dados durante o processamento de um turno) não aparecem nesta listagem.

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

---

Parâmetros

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
chatIdstring (uuid)SimIdentificador do chat.

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Paginação

ParâmetroTipoObrigatórioDescrição
limitintegerNãoQuantidade de registros por página
offsetintegerNãoDeslocamento inicial da página

Campos de Ordenação Disponíveis (order)

CampoDescrição
sequenceCursor de ordenação da mensagem — opaco, não representa um timestamp real. Padrão: desc (mensagem mais recente primeiro), se nenhuma ordenação for informada.

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/ai/chat/user/0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44/message?limit=20&offset=0" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": "0198f2c1-1a2b-7c31-9b21-3a6f2c1d9e55",
5      "role": "assistant",
6      "message": "O frete grátis pode ser configurado em Configurações > Frete...",
7      "toolCallId": null,
8      "toolName": null,
9      "sequence": 2,
10      "createdAt": "2026-07-30 14:03:40"
11    },
12    {
13      "id": "0198f2b0-9f1a-7c31-9b21-3a6f2c1d9e44",
14      "role": "user",
15      "message": "Como configuro frete grátis para pedidos acima de R$200?",
16      "toolCallId": null,
17      "toolName": null,
18      "sequence": 1,
19      "createdAt": "2026-07-30 14:02:11"
20    }
21  ],
22  "pagination": {
23    "limit": 20,
24    "offset": 0,
25    "pages": 1,
26    "registers": 2
27  }
28}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_AGENT_CHAT_NOT_FOUND404O chat informado não existe ou não pertence ao usuário autenticado.

Envio de Mensagem no Chat

POST /ai/chat/user/{chatId}/message

Grava a mensagem do usuário e inicia o processamento assíncrono da resposta do assistente.

Descrição

Envia uma nova mensagem em um chat existente. Este endpoint é assíncrono: ele grava a mensagem do usuário e retorna imediatamente 202 Accepted com um requestId — a resposta do assistente não vem nesta requisição.

Para obter a resposta, faça polling em GET /ai/chat/user/{chatId}/message/response até receber status: ready.

Pré-requisito: a loja precisa ter uma Credencial de IA configurada.

Um chat só processa um turno por vez: se já houver um turno em processamento para o mesmo chat, esta requisição falha com UAPPI_AGENT_CHAT_BUSY (409).

Este endpoint é limitado a 10 requisições por minuto.

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

---

Parâmetros

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
chatIdstring (uuid)SimIdentificador do chat.

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros do Corpo (Body)

ParâmetroTipoObrigatórioDescrição
messagestringSimConteúdo da mensagem do usuário. Máximo de 1000 caracteres.

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/ai/chat/user/0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44/message \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "message": "Como configuro frete grátis para pedidos acima de R$200?"
6  }'

✅ Resposta de Sucesso (202 Accepted)

1{
2  "status": "processing",
3  "chatId": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
4  "requestId": "7f0e6a1c-4b2d-4e9a-8c3f-1d2e3f4a5b6c",
5  "message": null
6}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_AGENT_CHAT_NOT_FOUND404O chat informado não existe ou não pertence ao usuário autenticado.
UAPPI_AGENT_CHAT_BUSY409Já existe um turno em processamento para este chat — aguarde a conclusão antes de enviar outra mensagem.
UAPPI_AGENT_CREDENTIAL_NOT_FOUND404A loja não possui uma Credencial de IA configurada.
UAPPI_AGENT_CHAT_LAUNCH_FAILED500Não foi possível iniciar o processamento em background do turno.

Consulta de Resposta do Turno

GET /ai/chat/user/{chatId}/message/response

Retorna o status do último turno do chat — 202 enquanto processa, 200 quando a resposta está pronta.

Descrição

Consulta o status do último turno de um chat. Use este endpoint em polling, após enviar uma mensagem, até obter a resposta final do assistente.

O HTTP status da resposta indica o estado do turno:

  • 202 Accepted — o turno ainda está em processamento (status: "processing"); o campo message vem null.
  • 200 OK — o turno terminou (status: "ready"); o campo message traz a resposta do assistente.

Este endpoint é limitado a 60 requisições por minuto. Utilize um intervalo curto entre chamadas (ex.: 1-2s) com backoff progressivo.

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

---

Parâmetros

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
chatIdstring (uuid)SimIdentificador do chat.

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/ai/chat/user/0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44/message/response \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta — turno em processamento (202 Accepted)

1{
2  "status": "processing",
3  "chatId": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
4  "requestId": "",
5  "message": null
6}

✅ Resposta — turno pronto (200 OK)

1{
2  "status": "ready",
3  "chatId": "0198f2b0-6e2a-7c31-9b21-3a6f2c1d9e44",
4  "requestId": "",
5  "message": {
6    "id": "0198f2c1-1a2b-7c31-9b21-3a6f2c1d9e55",
7    "role": "assistant",
8    "message": "O frete grátis pode ser configurado em Configurações > Frete...",
9    "toolCallId": null,
10    "toolName": null,
11    "sequence": 2,
12    "createdAt": "2026-07-30 14:03:40"
13  }
14}

> O campo requestId desta consulta sempre vem vazio ("") — ele só é preenchido na resposta do próprio POST de envio de mensagem.

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_AGENT_CHAT_NOT_FOUND404O chat informado não existe ou não pertence ao usuário autenticado.
UAPPI_AGENT_CHAT_RESPONSE_NOT_FOUND404O chat ainda não possui nenhuma mensagem (nenhuma mensagem foi enviada ainda).

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;