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 o atributo publicView com valor false caso não tenha sido informado.

🚧
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.

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
`value`	string	O document em JSON. Deve ser um objeto JSON válido 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.

Exemplo de schema de entidade

{
  "type": "object",
  "required": ["sku", "nome", "preco"],
  "properties": {
    "sku":          { "type": "string", "maxLength": 50, "publicView": true },
    "nome":         { "type": "string", "publicView": true },
    "preco":        { "type": "number", "minimum": 0, "publicView": 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.

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, `value` que não satisfaz o schema
`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

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 10 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 o atributo `publicView` com valor `false` caso não tenha sido informado.

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.

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.

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 o atributo publicView com valor false caso não tenha sido informado.

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.

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.

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 o atributo `publicView` com valor `false` caso não tenha sido informado.

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.

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