---
title: "Dynamic Filter Backend Contract Cheatsheet"
slug: "dynamic-filter-backend-contract-cheatsheet"
description: "Cheatsheet canônico do contrato backend do filtro dinamico, resumindo endpoints, formas de payload, ranges, erros e configuracoes do metadata-starter relevantes para hosts."
doc_type: "reference"
document_kind: "host-guide"
component: "table"
category: "integration"
audience:
  - "host"
  - "frontend"
  - "backend"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-filter"
  - "backend"
  - "cheatsheet"
  - "metadata-starter"
  - "payload"
order: 33
icon: "rule_folder"
toc: true
sidebar: true
search_boost: 1.18
reading_time: 14
estimated_setup_time: 20
version: "1.0"
related_docs:
  - "dynamic-filter-payload-contract"
  - "dynamic-filter-range-filters-guide"
  - "dynamic-fields-inline-filter-runtime-contract"
  - "dynamic-filter-troubleshooting-guide"
keywords:
  - "POST /filter"
  - "POST /filter/cursor"
  - "FILTER_PAYLOAD_INVALID"
source_of_truth:
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceQueryController.java"
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java"
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java"
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/rest/exceptionhandler/GlobalExceptionHandler.java"
  - "../praxis-metadata-starter/docs/examples/filter-dto.md"
  - "../praxis-metadata-starter/docs/guides/FILTROS-E-PAGINACAO.md"
last_updated: "2026-03-07"
---

# Dynamic Filter Backend Contract Cheatsheet

## Objetivo

Resumir, em formato operacional, o que um host precisa saber sobre o contrato backend do filtro dinâmico.

## Pré-requisitos

- Conhecimento básico de `GenericFilterDTO`.
- Leitura do contrato de payload e do guia de ranges.

## Quando usar

Use este documento como referência rápida em implementação, revisão de payload e troubleshooting.

## Endpoints principais

- `POST /filter`
- `POST /filter/cursor`
- `POST /locate`
- `POST /options/filter`

Todos pertencem à superfície resource-oriented padrão de `AbstractResourceQueryController`.

## Pipeline backend

1. request body chega ao controller;
2. `FilterRequestBodyAdvice` intercepta o body;
3. `RangePayloadNormalizer` canonicaliza ranges;
4. Jackson desserializa no `GenericFilterDTO`;
5. `GenericSpecificationsBuilder` monta a consulta;
6. erros retornam `400` quando houver violação de payload.

```mermaid
sequenceDiagram
  participant Host
  participant Controller as AbstractResourceQueryController
  participant Advice as FilterRequestBodyAdvice
  participant Normalizer as RangePayloadNormalizer
  participant DTO as GenericFilterDTO
  participant Builder as GenericSpecificationsBuilder

  Host->>Controller: POST /filter
  Controller->>Advice: intercept request body
  Advice->>Normalizer: canonicalize ranges
  Normalizer->>DTO: canonical payload ready
  DTO->>Builder: build specification
  Builder-->>Controller: query result or FILTER_PAYLOAD_INVALID
  Controller-->>Host: response payload or HTTP 400
```

## Shapes aceitos para range

### Lista canônica

- `[min]`
- `[min, max]`
- `[null, max]`

### Objeto canônico

- monetário: `{ minPrice, maxPrice, currency? }`
- data: `{ startDate, endDate }`
- numérico genérico: `{ min, max }`

## Formatos inválidos por padrão

- escalar puro: `1500`
- lista com 3 valores
- objeto sem nenhum limite efetivo
- fontes conflitantes para o mesmo bound

## Operações de range relevantes

- `BETWEEN`
- `BETWEEN_EXCLUSIVE`
- `NOT_BETWEEN`
- `OUTSIDE_RANGE`

Resumo:

- `BETWEEN`: inclusivo e aceita bound parcial;
- `BETWEEN_EXCLUSIVE`: exige dois bounds e usa exclusão;
- `NOT_BETWEEN`: nega o intervalo;
- `OUTSIDE_RANGE`: fora da faixa.

## Código de erro relevante

Para payload inválido de filtro:

- HTTP `400`
- `errors[].properties.code = FILTER_PAYLOAD_INVALID`

## Regras práticas para hosts

1. Envie DTO limpo, sem metadata de UI.
2. Prefira objeto ou lista canônica para range.
3. Não envie payload escalar para operações de range.
4. Não dependa de aliases alternativos como estilo principal.
5. Compare sempre a operação backend com o shape enviado.

## Exemplo curto

```json
{
  "salaryRange": {
    "minPrice": 6500,
    "maxPrice": 15000
  },
  "status": ["ACTIVE", "PENDING"]
}
```

Resultado esperado:

- `salaryRange` pode ser normalizado para `[6500,15000]`;
- `status` segue como lista para operação compatível;
- payload inválido resulta em `400`.