Changelog
Back to All
Added

Document Wake: filtros na consulta, identificador de origem e busca por conteúdo

7 days ago by Natali Maciel

O Document Wake — o recurso que permite à loja armazenar e consultar dados estruturados próprios na plataforma — passa a oferecer filtros na consulta. Até agora, localizar um registro específico exigia percorrer a listagem completa da entidade, página por página. Agora a loja consulta diretamente o que precisa: por um identificador vindo do sistema de origem, por data de cadastro ou pelo próprio conteúdo do documento.

As novidades estão disponíveis na API Pública e no Storefront API.

Identificador de origem (externalId)

Cada document pode carregar o código que aquele registro já tem no sistema da loja — código do vendedor, matrícula, SKU do ERP. O campo é gravado em coluna própria, fora do value, e devolvido em todas as leituras.

{
  "documentEntityId": 12,
  "value": "{\"nome\":\"Maria Silva\",\"filial\":\"SP-01\"}",
  "externalId": "VEND-0042"
}
  • Opcional, com até 50 caracteres (os espaços das bordas são removidos);
  • Único entre os documents ativos de uma mesma entidade — repetir retorna 409. Documents sem externalId podem coexistir em qualquer quantidade;
  • Imutável depois de criado: o PUT não recebe o campo e nunca o altera;
  • Liberado para reuso quando o document é removido.

Filtros na listagem por nome da entidade

A rota GET /document/values/by-entity-name/{name} passa a aceitar três filtros opcionais, combinados entre si e com a paginação por cursor:

FiltroDescrição
externalIdRepetível, com até 50 valores por chamada (?externalId=A&externalId=B)
createdFromLimite inferior da data de cadastro, em UTC
createdToLimite superior da data de cadastro, em UTC
GET /document/values/by-entity-name/vendedores?externalId=VEND-0042
GET /document/values/by-entity-name/vendedores?createdFrom=2026-08-01&createdTo=2026-08-31

As datas aceitam data pura (2026-08-31), data com horário (2026-08-31T10:30:00), sufixo Z ou offset explícito. Uma data pura em createdTo cobre o dia inteiro; com horário, vale o instante exato.

No Storefront API, a query documents recebeu os equivalentes: externalIds, createdAt_gte e createdAt_lte.

🚧

Reenvie os filtros a cada página

Os cursores carregam apenas a posição, não o critério. Pedir a página seguinte informando somente o after devolve uma consulta sem filtros, sem erro algum.

Busca por conteúdo

Os documents passaram a ser indexados, e a loja declara no schema da entidade quais propriedades são pesquisáveis, com o atributo filterable (até 8 por entidade). Com isso, é possível consultar pelo valor das propriedades:

{
  "filters": [
    { "field": "cor", "op": "eq", "value": "azul" },
    { "field": "preco", "op": "range", "gte": 100, "lte": 200 }
  ],
  "limit": 20
}
  • API Pública: POST /document/values/by-entity-name/{name}/search
  • Storefront API: query documentsSearch

Os operadores são eq (igualdade), in (lista de valores) e range (faixa numérica ou de data), com até 10 condições por requisição, todas combinadas por AND. A paginação é apenas para frente.

📘

Listagem e busca têm fontes diferentes

A listagem é atendida pelo banco da loja e é imediatamente consistente: um document criado aparece nela na chamada seguinte. A busca é atendida pelo índice, alimentado de forma assíncrona, e é eventualmente consistente: um document recém-criado ou recém-atualizado pode demorar alguns instantes para aparecer nela. Uma indisponibilidade do índice afeta apenas a busca — todas as demais operações seguem funcionando.

No Storefront API, uma propriedade só pode ser critério de busca se for filterable: true e publicView: true. Filtrar por uma propriedade revela informação sobre ela mesmo sem devolvê-la, então campos privados não são aceitos como critério no consumo público. Pelas chamadas autenticadas da API Pública, qualquer propriedade filterable é válida.

Propriedades fora do schema

A entidade pode declarar allowAdditionalProperties: true, liberando a gravação de propriedades que não estão no schema, em qualquer profundidade. Com false (padrão), a gravação é rejeitada com 400 indicando o caminho exato da propriedade recusada (ex.: /cfg/extra, /tags/0/extra).

Mensagens de erro mais específicas

  • Loja sem a funcionalidade documents habilitada passa a receber 403 com mensagem própria (WDC105 no Storefront API), em vez de um erro genérico;
  • Filtro de data em formato não aceito, mais de 50 valores em externalId ou cursores conflitantes retornam um erro próprio da listagem (WDC106 no Storefront API), que aponta o parâmetro errado em vez de sugerir que o problema está no documento enviado;
  • A recusa de uma condição de busca informa qual condição está errada e por quê — propriedade não filtrável, operador incompatível com o tipo declarado, range sem limite ou excesso de condições.

Atenção: limite de tamanho do value

O conteúdo de cada document passa a ser limitado a 2.000 caracteres, validado na criação e na atualização, antes das demais validações de conteúdo.

Documents já gravados acima desse limite continuam podendo ser lidos e removidos normalmente, mas falham na próxima atualização enquanto não forem reduzidos. Se a sua integração grava documents grandes, revise-a antes de continuar.

Documentação