feat: add asynchronous lookup method to KonectyClient

KonectySdkPython/lib/client.py

@@ -477,6 +477,35 @@ async def find(self, module: str, options: KonectyFindParams) -> List[KonectyDic
                 raise KonectyAPIError(errors)
             data = result.get("data", [])
             return cast(List[KonectyDict], data)
+
+    async def lookup(self, module: str, lookup_field: str, options: KonectyFindParams, search: str = "") -> List[KonectyDict]:
+        params: Dict[str, str] = {}
+        for key, value in options.model_dump(exclude_none=True).items():
+            params[key] = (
+                json.dumps(value, default=json_serial)
+                if key != "fields"
+                else ",".join(value)
+            )
+        if search:
+            params["search"] = search
+
+        print(f"params: {params}")
+        async with (
+            aiohttp.ClientSession() as session,
+            session.get(
+                f"{self.base_url}/rest/data/{module}/lookup/{lookup_field}",
+                params=params,
+                headers={"Authorization": self.headers["Authorization"]},
+            ) as response,
+        ):
+            response.raise_for_status()
+            result = await response.json()
+            if not result.get("success", False):
+                errors = result.get("errors", [])
+                logger.error(errors)
+                raise KonectyAPIError(errors)
+            data = result.get("data", [])
+            return cast(List[KonectyDict], data)
 
     def find_sync(self, module: str, options: KonectyFindParams) -> List[KonectyDict]:
         """Versão síncrona de find."""

docs/api.md

@@ -22,6 +22,7 @@ Quando `success` é falso, o SDK converte a resposta em exceção `KonectyAPIErr
 | Endpoint                                                          | Método | Propósito                                                                                                              | Uso no SDK                                          |
 | ----------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
 | `/rest/data/{module}/find`                                        | GET    | Buscar registros com filtro, ordenação, paginação e projeção de campos.                                                | `find`, `find_sync`, `count_documents` em client.py |
+| `/rest/data/{module}/lookup/{lookup_field}`                       | GET    | Buscar opções de lookup por campo de relacionamento com os mesmos parâmetros de find e termo livre de busca.         | `lookup` em client.py                               |
 | `/rest/data/{module}/{id}`                                        | GET    | Obter um registro pelo identificador.                                                                                  | `find_by_id` em client.py                           |
 | `/rest/data/{module}`                                             | POST   | Criar um novo registro. Corpo: objeto com os campos do documento.                                                      | `create` em client.py                               |
 | `/rest/data/{module}`                                             | PUT    | Atualizar um ou mais registros. Corpo: objeto com `ids` (lista de `_id` e `_updatedAt`) e `data` (campos a atualizar). | `update_one`, `update` em client.py                 |
@@ -43,6 +44,16 @@ Os parâmetros são enviados como query string. O SDK monta esses parâmetros a
 
 A API do Konecty aceita ainda parâmetros opcionais como `displayName`, `displayType` e `withDetailFields`; o SDK atual não os expõe diretamente nos métodos de find.
 
+## Parâmetros do lookup (GET /rest/data/{module}/lookup/{lookup_field})
+
+O método assíncrono `lookup` usa a mesma estrutura de parâmetros de `KonectyFindParams` (filter, start, limit, sort e fields), com serialização idêntica ao find:
+
+- **fields:** enviado como lista separada por vírgula.
+- **demais parâmetros estruturados:** enviados em JSON na query string.
+- **search:** string opcional para busca textual livre no lookup.
+
+O endpoint retorna uma lista no campo `data` e segue o mesmo contrato de erros (`success` e `errors`) dos demais endpoints de dados.
+
 ## Formato de filtro (Konecty)
 
 O filtro segue o modelo do Konecty (Filter/KonFilter): `match` (and ou or), `conditions` (array de condições com term, operator, value, disabled) e `filters` (array de filtros aninhados com a mesma estrutura). Operadores típicos incluem equals, not_equals, in, not_in, less_than, greater_than, between, exists, etc., alinhados ao enum `FilterOperator` no SDK.
@@ -122,4 +133,4 @@ Além das consultas salvas, o Konecty expõe execução direta de consultas cros
 
 ## Outros endpoints do Konecty (não utilizados pelo SDK)
 
-O Konecty expõe ainda, entre outros: Menu (list, documents), Data (lookup, history, relations, queue, lead/save), File (delete), Auth, health, process, etc. A documentação acima cobre o que o SDK utiliza e o contrato da query customizada.
+O Konecty expõe ainda, entre outros: Menu (list, documents), Data (history, relations, queue, lead/save), File (delete), Auth, health, process, etc. A documentação acima cobre o que o SDK utiliza e o contrato da query customizada.

docs/changelog/2026-03-25_documentacao-lookup-assincrono.md

@@ -0,0 +1,39 @@
+# Documentação do lookup assíncrono
+
+## Resumo
+
+Atualiza a documentação para refletir a inclusão do método assíncrono de lookup no cliente do SDK.
+
+## Motivação
+
+O último commit adicionou suporte de lookup assíncrono no `KonectyClient`; a documentação precisava ficar alinhada ao comportamento atual da API exposta.
+
+## O que mudou
+
+- Inclusão do endpoint de lookup na tabela de endpoints utilizados pelo SDK.
+- Criação de seção específica descrevendo parâmetros e contrato de resposta do lookup.
+- Ajuste da seção de endpoints não utilizados para remover `lookup` da lista.
+
+## Impacto técnico
+
+A documentação técnica passa a representar corretamente o uso de `/rest/data/{module}/lookup/{lookup_field}` pelo SDK, reduzindo divergência entre implementação e referência.
+
+## Impacto externo
+
+Consumidores do SDK e mantenedores passam a ter orientação explícita para uso do método `lookup` assíncrono.
+
+## Como validar
+
+- Confirmar em `docs/api.md` a presença do endpoint de lookup na tabela principal.
+- Confirmar em `docs/api.md` a seção de parâmetros do lookup com `search` opcional.
+- Verificar que `lookup` não aparece mais na lista de endpoints não utilizados pelo SDK.
+
+## Arquivos afetados
+
+- `docs/api.md`
+- `docs/changelog/2026-03-25_documentacao-lookup-assincrono.md`
+- `docs/changelog/README.md`
+
+## Existe migração?
+
+Não.

docs/changelog/README.md

@@ -4,6 +4,7 @@ Histórico de alterações do Konecty SDK Python. Cada entrada é um arquivo mar
 
 ## Índice por data
 
+- [2026-03-25 — Documentação do lookup assíncrono](2026-03-25_documentacao-lookup-assincrono.md)
 - [2025-03-13 — Criador de query tipado para query/json (QueryJson, QueryRelation, etc.)](2025-03-13_criador-query-json-tipado.md)
 - [2025-03-13 — Implementação das features do plano (stream, files, export, KPI, graph, pivot, comments, subscriptions, notifications, change user, query, saved queries)](2025-03-13_implementacao-features-sdk.md)
 - [2025-03-13 — Documentação do SDK e da API](2025-03-13_documentacao-sdk-e-api.md)