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.
• Vínculo do document — um document pode ser vinculado a um carrinho ou a um produto do carrinho. Quando o pedido é finalizado, o vínculo passa para o pedido. Veja Vínculo com carrinho e pedido.

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 vínculo com carrinho não tem permissão própria. Para criar o document já vinculado, vale o CREATE do documentCreate. O documentLink aceita documents de entidades sem READ público, porque apenas confirma que o document existe e não devolve o conteúdo. Para anexar o arquivo depois da compra, a entidade precisa de UPDATE.

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.

Vínculo com carrinho e pedido

Um document pode ser vinculado a um carrinho (vale para o pedido inteiro) ou a um produto do carrinho. O vínculo é feito de duas formas:

• na criação, informando checkoutId (e, opcionalmente, productVariantId) no documentCreate;
• depois da criação, com documentLink. O documentUnlink desfaz o vínculo.

Regras do vínculo:

• O vínculo só pode ser feito ou desfeito com o carrinho aberto. Em um carrinho finalizado, a operação retorna WDC110;
• Para vincular a um produto, o produto precisa estar no carrinho. Caso contrário, a operação retorna WDC111. O vínculo vale para todas as unidades daquele produto no carrinho e acompanha a mudança de quantidade: as unidades acrescentadas com checkoutAddProduct recebem o vínculo, e o checkoutRemoveProduct o mantém nas unidades que sobram. Se o produto sair do carrinho por inteiro, o vínculo sai junto;
• Cada produto do carrinho aceita até 5 documents vinculados, e o carrinho aceita outros 5 (veja Limite de documents vinculados);
• Ao finalizar o pedido, os vínculos do carrinho passam para o pedido, e os vínculos dos produtos passam para os produtos do pedido. Depois disso, o vínculo do pedido não muda;
• Um document tem no máximo 1 arquivo. Um mesmo document pode ser vinculado a vários produtos (um documentLink por produto), e um produto ou carrinho aceita vários documents;
• Atualizar o document com documentUpdate, inclusive trocando ou incluindo o arquivo, mantém o vínculo, porque o id do document não muda. Isso vale também depois de o pedido ser finalizado;
• Remover o document com documentDelete não remove o vínculo. O id continua listado em documentIds, e a query document com esse id retorna null. Quem exibe os documents deve tratar esse caso;
• Checkout online: quando o pagamento é recusado e o carrinho é recriado para o mesmo cliente, os vínculos acompanham o carrinho novo;
• Carrinho clonado sem os dados do cliente (checkoutClone sem copyUser, como ao compartilhar um carrinho): os vínculos não são copiados, porque o carrinho novo pode ser de outra pessoa.

Os documents vinculados aparecem no campo documentIds, com os mesmos ids (hash) aceitos pelas queries document e documents:

• documentIds é sempre uma lista e vem vazia ([]) quando não há vínculo;
• O vínculo também aparece em metadata do carrinho e do produto como um metadado privado, com a chave _wdoc_{número} e o valor igual a esse número — o id interno do document no Document Wake, e não o id em hash do Storefront API. Esse metadado é exclusivo das mutations de document: as mutations de metadado do carrinho recusam chaves com o prefixo _wdoc_, com qualquer token, e retornam VAL121. Isso vale para checkoutAddMetadata, checkoutAddMetadataForProductVariant, checkoutRemoveMetadata e os metadados de produto do checkoutAddProduct. Para ler os documents vinculados, use documentIds.

query {
  customer(customerAccessToken: "<token-do-cliente>") {
    orders {
      nodes {
        orderId
        documentIds
        products {
          productVariantId
          documentIds
        }
      }
    }
  }
}

Limite de documents vinculados

• Cada produto tem o próprio limite, então um carrinho com vários produtos pode ter documents em todos eles;
• O limite reserva espaço para outros dados internos do carrinho e do produto, como identificação de kit, Click to Pay e venda assistida;
• Ao atingir o limite, documentCreate e documentLink retornam WDC114, com o limite na extensão limit. No documentCreate, o document não é criado;
• Vincular de novo um document que já está vinculado não conta para o limite. Para liberar espaço, use documentUnlink;
• Para receitas e outros documents ligados a um item, prefira o vínculo no produto: cada produto tem o próprio limite, e o pedido indica a qual produto o document se refere.

Exemplo: receita enviada depois da compra

Quando um produto exige receita e o cliente ainda não tem o arquivo no momento da compra:

1. Antes de finalizar o pedido, a loja cria o document sem arquivo, já vinculado ao produto (documentCreate com checkoutId e productVariantId, sem file). O document pode guardar um status, como "pendente";
2. O pedido é finalizado, e o produto do pedido passa a listar esse document em documentIds;
3. Depois, por exemplo no Minha Conta, a loja anexa o arquivo com documentUpdate (mesmo id, value completo e file). O pedido continua apontando para o mesmo document, agora com arquivo.

Como não é possível vincular documents a um pedido já finalizado, esse é o caminho quando o arquivo chega depois da compra. A entidade precisa liberar CREATE e UPDATE e, para exibir o document, READ.

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.

{
  "errors": [
    {
      "message": "O documento foi criado, mas não foi possível vinculá-lo ao carrinho",
      "path": ["documentCreate"],
      "extensions": {
        "code": "WDC113",
        "documentId": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9"
      }
    }
  ],
  "data": {
    "documentCreate": {
      "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
      "data": { "status": "pendente", "aceiteTermo": true },
      "files": []
    }
  }
}

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

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

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