Documentação

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.

📘

A validação do schema segue o dialeto JSON Schema draft 2020-12 e a raiz do schema deve declarar type: object.

Entidades de document

MétodoRotaDescrição
POST/document/entitiesCria uma entidade de document
GET/document/entitiesLista 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

CampoTipoDescrição
idinteiroIdentificador da entidade
namestringNome da entidade. Obrigatório, até 100 caracteres e único na loja
schemastringJSON Schema (draft 2020-12) que descreve os documents aceitos. Obrigatório e com raiz type: object
publicOperationsarray de stringOpcional. Operações liberadas para consumo público: CREATE, READ, UPDATE, DELETE. Quando ausente, nenhuma operação é pública
createdAtdataData de cadastro (UTC)
updatedAtdataData da última atualização (UTC)
📘

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étodoRotaDescrição
POST/document/valuesCria 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

CampoTipoDescrição
idinteiroIdentificador do document
documentEntityIdinteiroEntidade à qual o document pertence
valuestringO document em JSON. Deve ser um objeto JSON válido e satisfazer o schema da entidade
createdAtdataData de cadastro (UTC)
updatedAtdataData 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 }
  }
}

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 about 4 hours ago