Neppo Chat API — Guia de Busca, Filtros e Paginação

📘 Documentação Neppo Chat API  |  🏠 Visão Geral (índice)  ·  🔎 Guia de Busca  ·  📦 Modelos de Dados

• 1. Autenticação — como usar o token
• 2. Estrutura geral do corpo de busca
• 3. Anatomia de uma condition
• 4. Operadores válidos
• 5. Lógica de combinação (AND / OR)
• 6. Paginação
• 7. Exemplo completo e funcional
• 8. Erros e códigos de status

1. Autenticação — como usar o token

A API utiliza OAuth2 (no gateway WSO2, combinada com basic auth e API key), conforme descrito na página de Visão Geral. Todas as chamadas autenticadas devem enviar o token no cabeçalho:

Authorization: Bearer <SEU_TOKEN>

Os endpoints declaram escopos read / write / delete conforme a operação.

2. Estrutura geral do corpo de busca

O corpo de uma busca paginada (CustomPageRequest) tem o seguinte formato:

[VERIFICAR: confirmar se o backend exige conditions não-vazio e se há validação que torne page/size obrigatórios na desserialização.]

3. Anatomia de uma condition

Cada item de conditions é um objeto Condition com os campos:

4. Operadores válidos

Valores aceitos no campo operator (enum Operator):

5. Lógica de combinação (AND / OR)

O campo logic aceita dois valores (enum LogicEnum):

As conditions são avaliadas na ordem em que aparecem. A primeira inicia o filtro; cada condition seguinte é combinada com o resultado acumulado de acordo com o seu próprio logic. Quando uma condition possui subgrupo (and/or/conditions), esse subgrupo é resolvido recursivamente e combinado pelo mesmo logic.

6. Paginação

A resposta de listagem segue o modelo PageResponse:

7. Exemplo completo e funcional

Busca que retorna registros cujo status não é nulo E que, em um subgrupo, têm maxChatChannels = 5 OU status = OFFLINE, trazendo a primeira página com 10 itens:

{
  "conditions": [
    {
      "key": "status",
      "operator": "NOT_NULL",
      "logic": "AND",
      "and": [
        { "key": "maxChatChannels", "value": "5", "operator": "EQNUM" },
        { "key": "status", "value": "OFFLINE", "operator": "EQ", "logic": "OR" }
      ]
    }
  ],
  "page": 0,
  "size": 10
}

Chamada (salve o JSON acima como busca.json):

curl -X POST "https://hml-chat-api.neppo.com.br/api/v1/agent" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d @busca.json

Exemplo de resposta (200 OK — PageResponse):

{
  "page": 0,
  "size": 10,
  "results": [
    {
      "id": 42,
      "name": "Maria Silva",
      "status": "OFFLINE",
      "maxChatChannels": 5
    }
  ]
}

Exemplo simples (um único filtro)

Buscar contatos cujo nome contenha "maria":

{
  "conditions": [
    { "key": "name", "value": "maria", "operator": "LIKE" }
  ],
  "page": 0,
  "size": 20
}

8. Erros e códigos de status

[VERIFICAR: confirmar o catálogo de códigos de erro de negócio específicos da plataforma (módulo Custom Error) e suas mensagens.]