diff --git a/KonectySdkPython/lib/client.py b/KonectySdkPython/lib/client.py index 5a082e9..3f3eb1c 100644 --- a/KonectySdkPython/lib/client.py +++ b/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.""" diff --git a/docs/api.md b/docs/api.md index 7a10c37..55492be 100644 --- a/docs/api.md +++ b/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. diff --git a/docs/changelog/2026-03-25_documentacao-lookup-assincrono.md b/docs/changelog/2026-03-25_documentacao-lookup-assincrono.md new file mode 100644 index 0000000..763cd02 --- /dev/null +++ b/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. diff --git a/docs/changelog/README.md b/docs/changelog/README.md index 95be19d..4cae1d1 100644 --- a/docs/changelog/README.md +++ b/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)