Document Wake

O Document Wake foi desenvolvido para permitir que a loja armazene e consulte dados estruturados próprios na plataforma, sem depender de um cadastro nativo para cada necessidade.

O recurso é organizado em dois conceitos:

Entidade de document — a definição do dado. É onde se declara o name da entidade e o schema (JSON Schema) que descreve o formato dos documents que ela aceita;
Document (valor) — o dado em si, gravado em JSON e validado contra o schema da entidade no momento da criação e da atualização.

Com essa funcionalidade é possível, por exemplo, manter tabelas auxiliares de integração, configurações de campanhas, dados complementares de produtos ou qualquer informação personalizada que a loja precise consumir depois.

📘
Vale a pena saber:
A validação do schema segue o dialeto JSON Schema draft 2020-12. A raiz do schema deve declarar type: object e conter ao menos uma propriedade em properties.

Entidades de document

Método	Rota	Descrição
`POST`	`/document/entities`	Cria uma entidade de document
`GET`	`/document/entities`	Lista as entidades da loja
`GET`	`/document/entities/{id}`	Retorna uma entidade pelo identificador
`GET`	`/document/entities/by-name/{name}`	Retorna uma entidade pelo nome
`PUT`	`/document/entities/{id}`	Atualiza uma entidade
`DELETE`	`/document/entities/{id}`	Remove uma entidade

Campos da entidade

Campo	Tipo	Descrição
`id`	inteiro	Identificador da entidade
`name`	string	Nome da entidade. Obrigatório, até 100 caracteres e único na loja
`schema`	string	JSON Schema (draft 2020-12) que descreve os documents aceitos. Obrigatório e com raiz `type: object`
`publicOperations`	array de string	Opcional. Operações liberadas para consumo público: `CREATE`, `READ`, `UPDATE`, `DELETE`. Quando ausente, nenhuma operação é pública
`allowAdditionalProperties`	booleano	Opcional. Quando `true`, os documents da entidade podem conter propriedades não declaradas em `properties`, em qualquer profundidade. Quando `false` ou ausente, a gravação de um document com propriedade não declarada é rejeitada com `400`
`createdAt`	data	Data de cadastro (UTC)
`updatedAt`	data	Data da última atualização (UTC)

📘
Com allowAdditionalProperties: false (padrão), a validação vale em qualquer profundidade — objetos aninhados e itens de array inclusive — e o erro 400 indica o caminho da propriedade rejeitada em JSON Pointer (ex.: /cfg/extra, /tags/0/extra). A exceção é o subschema que não declara nenhuma propriedade (ex.: {"type":"object"}): ele é um trecho livre, e a regra não incide nele nem abaixo dele.

📘
O schema é normalizado ao ser gravado: o $schema do dialeto draft 2020-12 é acrescentado quando ausente, o $id é descartado e cada item de properties recebe os atributos publicView e filterable com valor false caso não tenham sido informados.

🚧
O atributo publicView e a lista publicOperations controlam apenas o consumo público dos documents. As chamadas autenticadas pela API Pública sempre retornam o document completo, independentemente dessas marcações.

Atributos por propriedade do `schema`

Além das keywords do dialeto draft 2020-12, cada item de properties aceita dois atributos próprios do Document Wake. Ambos valem apenas no primeiro nível do objeto e são independentes entre si — uma propriedade pode ser filtrável sem ser pública, e vice-versa.

Atributo	Tipo	Padrão	Descrição
`publicView`	booleano	`false`	Quando `true`, a propriedade é devolvida nas leituras públicas do document (Storefront API)
`filterable`	booleano	`false`	Quando `true`, a propriedade pode ser usada como critério na busca por conteúdo e é materializada no índice de busca

🚧
Restrições do filterable

Toda propriedade com filterable: true deve declarar um type suportado: string, number, integer, boolean ou string com format de data. Tipo ausente, múltiplo ou não suportado (object, array) é rejeitado com 400;

Cada entidade pode ter no máximo 8 propriedades marcadas como filterable: true. Acima disso o schema é rejeitado com 400;

Alterar o conjunto de propriedades filterable de uma entidade dispara a reindexação dos documents dela de forma assíncrona — o PUT responde assim que o schema é gravado.

Documents (valores)

Método	Rota	Descrição
`POST`	`/document/values`	Cria um document informando o identificador da entidade
`POST`	`/document/values/by-entity-name/{name}`	Cria um document informando o nome da entidade
`GET`	`/document/values/{id}`	Retorna um document pelo identificador
`GET`	`/document/values/by-entity/{entityId}`	Lista os documents de uma entidade pelo identificador
`GET`	`/document/values/by-entity-name/{name}`	Lista, paginado por cursor, os documents de uma entidade pelo nome
`PUT`	`/document/values/{id}`	Atualiza um document
`DELETE`	`/document/values/{id}`	Remove um document

Campos do document

Campo	Tipo	Descrição
`id`	inteiro	Identificador do document
`documentEntityId`	inteiro	Entidade à qual o document pertence
`externalId`	string	Opcional. Identificador do document no sistema de origem da loja (ERP, folha, cadastro de vendedores). Nulo quando não informado na criação
`value`	string	O document em JSON. Deve ser um objeto JSON válido, ter no máximo 2.000 caracteres e satisfazer o schema da entidade
`createdAt`	data	Data de cadastro (UTC)
`updatedAt`	data	Data da última atualização (UTC)

📘
O value é enviado e retornado como string contendo o JSON do document. Ao montar a requisição, lembre-se de escapar as aspas internas.

🚧
Limite de tamanho do value
O value é limitado a 2.000 caracteres, contados no JSON como recebido. O limite é verificado antes das demais validações de conteúdo: um document acima do limite retorna 400 informando o tamanho, sem que o schema seja avaliado.
Documents gravados acima desse limite antes da sua introdução continuam podendo ser lidos e removidos, mas falham na próxima atualização enquanto não forem reduzidos.

O identificador externo (`externalId`)

O externalId guarda, em coluna própria (fora do value), o identificador que o document tem no sistema de origem da loja. Ele serve para localizar o document depois, sem depender do id gerado pela plataforma.

É opcional. Ausente, nulo ou composto apenas de espaços em branco é gravado como nulo;
Os espaços das bordas são removidos antes de gravar, e o valor já aparado deve ter no máximo 50 caracteres — acima disso o retorno é 400;
É único entre os documents ativos da mesma entidade. Repetir o identificador de um document ativo retorna 409. Documents com externalId nulo não participam da unicidade: podem coexistir em qualquer quantidade;
A mesma entidade é a fronteira da unicidade: o mesmo externalId pode existir em entidades diferentes;
Remover um document libera o externalId dele para reuso em uma nova criação na mesma entidade;
É imutável: definido apenas na criação. O PUT não recebe o campo e nunca o altera ou anula, mas devolve o valor gravado na resposta;
É retornado em todas as leituras do document, inclusive nas públicas — a projeção por publicView recai apenas sobre o value.

Exemplo de schema de entidade

{
  "type": "object",
  "required": ["sku", "nome", "preco"],
  "properties": {
    "sku":          { "type": "string", "maxLength": 50, "publicView": true, "filterable": true },
    "nome":         { "type": "string", "publicView": true },
    "preco":        { "type": "number", "minimum": 0, "publicView": true, "filterable": true },
    "custoInterno": { "type": "number", "minimum": 0 },
    "metadados":    { "type": "object" }
  }
}

No exemplo acima, metadados não declara nenhuma propriedade: é um trecho livre e aceita qualquer conteúdo, mesmo com allowAdditionalProperties: false. As propriedades sku e preco foram marcadas como filterable, portanto podem ser usadas como critério na busca por conteúdo.

Respostas de erro comuns

Status	Quando ocorre
`400`	Dados inválidos: schema fora do draft 2020-12, sem `type: object` ou sem `properties` na raiz, propriedade `filterable` com tipo não suportado, mais de 8 propriedades `filterable`, `value` acima de 2.000 caracteres ou que não satisfaz o schema, `externalId` acima de 50 caracteres, filtro de listagem inválido
`401`	Token ausente ou inválido
`403`	A funcionalidade documents não está habilitada para a loja
`404`	Entidade ou document não encontrado na loja
`409`	Já existe uma entidade com o mesmo nome na loja, ou já existe um document ativo com o mesmo `externalId` na entidade

Permissões do token

As operações do Document Wake exigem que o token da API Pública tenha as permissões correspondentes liberadas:

[
  "post/document/entities",
  "get/document/entities",
  "get/document/entities/{id}",
  "get/document/entities/by-name/{name}",
  "put/document/entities/{id}",
  "delete/document/entities/{id}",
  "post/document/values",
  "get/document/values/by-entity/{entityId}",
  "get/document/values/by-entity-name/{name}",
  "get/document/values/{id}",
  "put/document/values/{id}",
  "delete/document/values/{id}"
]

Updated 12 days ago

Document Wake

Vale a pena saber:

Entidades de document

Campos da entidade

O `schema` é normalizado ao ser gravado: o `$schema` do dialeto draft 2020-12 é acrescentado quando ausente, o `$id` é descartado e cada item de `properties` recebe os atributos `publicView` e `filterable` com valor `false` caso não tenham sido informados.

O atributo `publicView` e a lista `publicOperations` controlam apenas o consumo público dos documents. As chamadas autenticadas pela API Pública sempre retornam o document completo, independentemente dessas marcações.

Atributos por propriedade do `schema`

Restrições do `filterable`

Documents (valores)

Campos do document

O `value` é enviado e retornado como string contendo o JSON do document. Ao montar a requisição, lembre-se de escapar as aspas internas.

Limite de tamanho do `value`

O identificador externo (`externalId`)

Exemplo de schema de entidade

Respostas de erro comuns

Permissões do token

Vale a pena saber:

Entidades de document

Campos da entidade

O schema é normalizado ao ser gravado: o $schema do dialeto draft 2020-12 é acrescentado quando ausente, o $id é descartado e cada item de properties recebe os atributos publicView e filterable com valor false caso não tenham sido informados.

O atributo publicView e a lista publicOperations controlam apenas o consumo público dos documents. As chamadas autenticadas pela API Pública sempre retornam o document completo, independentemente dessas marcações.

Atributos por propriedade do schema

Restrições do filterable

Documents (valores)

Campos do document

O value é enviado e retornado como string contendo o JSON do document. Ao montar a requisição, lembre-se de escapar as aspas internas.

Limite de tamanho do value

O identificador externo (externalId)

Exemplo de schema de entidade

Respostas de erro comuns

Permissões do token

O `schema` é normalizado ao ser gravado: o `$schema` do dialeto draft 2020-12 é acrescentado quando ausente, o `$id` é descartado e cada item de `properties` recebe os atributos `publicView` e `filterable` com valor `false` caso não tenham sido informados.

O atributo `publicView` e a lista `publicOperations` controlam apenas o consumo público dos documents. As chamadas autenticadas pela API Pública sempre retornam o document completo, independentemente dessas marcações.

Atributos por propriedade do `schema`

Restrições do `filterable`

O `value` é enviado e retornado como string contendo o JSON do document. Ao montar a requisição, lembre-se de escapar as aspas internas.

Limite de tamanho do `value`

O identificador externo (`externalId`)