O Storefront API permite consultar e manter os documents da loja — dados estruturados próprios, definidos pelo lojista e validados por um JSON Schema — diretamente pelo GraphQL, sem passar pela API Pública.

O recurso é composto por dois conceitos:

• Entidade de document — a definição do dado: o nome da entidade, o schema que descreve o formato dos documents e as permissões de acesso público;
• Document — o dado em si, gravado em JSON e validado contra o schema da entidade.
• Arquivo do document — imagem ou PDF anexado ao document. Fica fora do JSON e não é validado contra o schema.

Pelo Storefront API são expostos apenas os documents. A criação e a manutenção das entidades são feitas pela API Pública — veja Document Wake na seção API Pública.

Operações disponíveis

Permissões da entidade

O Storefront API acessa os documents como consumidor público. Isso significa que a entidade precisa liberar explicitamente cada operação, e que os documents retornam apenas os campos marcados como públicos:

• publicOperations — a entidade declara quais operações são públicas (CREATE, READ, UPDATE, DELETE). Uma operação não declarada retorna o erro WDC103;
• publicView — cada propriedade do schema declara se é visível publicamente. Apenas as propriedades com publicView: true aparecem no campo data dos documents retornados.
• O arquivo segue as permissões do document: anexar exige CREATE ou UPDATE, e ler exige READ. Não há publicView para arquivo: sempre que o document é legível, a URL aparece em files.

O identificador dos documents

O id de um document é exposto como uma hash (padrão de identificação global do Storefront API), e não como um número:

eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9

Essa mesma hash é usada como cursor na paginação da query documents e como argumento id em document, documentUpdate e documentDelete. Uma hash inválida ou de outra entidade retorna o erro Identificador de documento inválido.

O campo data

O conteúdo do document é retornado no campo data, um escalar dinâmico (Any): ele carrega o objeto JSON do document e, por isso, não recebe seleção de subcampos na query. O id fica sempre fora do data, no nível do nó.

Para limitar o retorno a campos específicos, use o argumento fields, disponível em documents e document.

O campo files

O campo files traz os arquivos anexados ao document, numa lista de DocumentFileNode com url e createdAt. Ele fica ao lado de data, e não dentro.

• Quando o document não tem arquivo, a lista vem vazia ( [ ] ), nunca null;

• files não é afetado por fields nem por publicView;
• createdAt é a data em que o arquivo foi vinculado ao document, em UTC;
• Na query documentsSearch, a lista vem sempre vazia;
• Use a url exatamente como retornada.

Arquivos do document

documentCreate e documentUpdate aceitam um arquivo opcional no argumento file.

Filtrando a listagem

A query documents aceita, além dos argumentos de paginação, três filtros opcionais: externalIds, createdAt_gte e createdAt_lte. Eles são combinados entre si e com a paginação por E (AND), e precisam ser reenviados a cada página — os cursores carregam apenas a posição, não o critério.

Veja os detalhes em Documents.

Exemplo utilizado nesta seção

Os exemplos a seguir usam uma entidade chamada ficha-tecnica, que libera as quatro operações públicas e cujo schema declara três propriedades:

Como custo não é público, ele nunca aparece no data retornado pelo Storefront API.

Códigos de erro

Os erros seguem o padrão do Storefront API: a operação retorna null (ou isSuccess: false, em documentDelete) e o detalhamento vem no array errors, com o código em extensions.code.

Exemplo de resposta com WDC108

{
  "errors": [
    {
      "message": "Arquivo inválido",
      "path": ["documentCreate"],
      "extensions": {
        "code": "WDC108",
        "detail": "Extensão \"svg\" não permitida. Aceitos: jpg, jpeg, png, gif, webp, pdf."
      }
    }
  ],
  "data": {
    "documentCreate": null
  }
}

Nas operações de criação e atualização, quando o document viola o schema da entidade, a extensão detail traz a violação específica:

{
  "errors": [
    {
      "message": "Documento inválido",
      "path": ["documentCreate"],
      "extensions": {
        "code": "WDC101",
        "detail": "O documento não está de acordo com o schema da entidade: /custo Value is \"string\" but should be \"number\""
      }
    }
  ],
  "data": {
    "documentCreate": null
  }
}

Na listagem, a extensão detail é o que distingue um filtro de data malformado de um excesso de valores em externalIds:

{
  "errors": [
    {
      "message": "Filtro de documentos inválido",
      "path": ["documents"],
      "extensions": {
        "code": "WDC106",
        "detail": "O filtro createdTo não corresponde a um formato de data aceito."
      }
    }
  ],
  "data": {
    "documents": null
  }
}

Consulte também Códigos de erros mapeados na API.

Demais documentações:

https://wakecommerce.readme.io/docs/document

https://wakecommerce.readme.io/docs/documents

https://wakecommerce.readme.io/docs/documentcreate

https://wakecommerce.readme.io/docs/documentupdate

https://wakecommerce.readme.io/docs/documentdelete