documentCreate

A mutation DocumentCreate permite criar um document em uma entidade, identificada pelo nome.

O document é validado contra o schema da entidade antes de ser gravado. A operação exige que a entidade declare CREATE em publicOperations.

Opcionalmente, a mutation recebe um arquivo (imagem ou PDF), gravado na mesma operação que o document.

Parâmetros

Argumento	Tipo	Obrigatório	Descrição
entityName	String!	Sim	Nome da entidade. Não diferencia maiúsculas de minúsculas
value	Any	Sim	O document, como um objeto JSON. Limitado a 2.000 caracteres
file	Upload	Não	Arquivo a anexar ao document: `jpg, jpeg, png, gif, webp ou pdf,` até 5 MB

Campos de retorno

Os campos de retorno são os do document criado.

Campo	Tipo	Descrição
id	String	Identificador do document criado, em hash
data	Any	O document gravado, com os campos públicos projetados
files	[DocumentFileNode]	Arquivos anexados ao document. Lista vazia quando não há nenhum
files.url	String	URL pública do arquivo
files.createdAt	DateTime	Data em que o arquivo foi vinculado ao document, em UTC

Exemplo

mutation {
  documentCreate(
    entityName: "ficha-tecnica"
    value: { sku: "ABC-123", cor: "Azul", custo: 42.5 }
  ) {
    id
    data
  }
}

Mostrar resposta


{
  "data": {
    "documentCreate": {
      "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
      "data": {
        "sku": "ABC-123",
        "cor": "Azul"
      }
    }
  }
}

O document é gravado por completo, inclusive os campos não públicos, mas o retorno traz somente os campos com publicView: true — no exemplo, custo é gravado e omitido na resposta.

🚧
Limite de tamanho
O document é limitado a 2.000 caracteres de JSON. O limite é verificado antes da validação contra o schema: um document acima dele retorna WDC101 informando o tamanho, com o motivo na extensão detail. O arquivo não entra nesse limite.

📘
O identificador externo (externalId) não é definido por esta mutation
O externalId de um document — usado como filtro na query Documents — é informado apenas na criação pela API Pública, em Inserindo um document. Documents criados pelo Storefront API ficam sem identificador externo e, por isso, não são retornados quando o filtro externalIds é informado.

Enviando um arquivo

Com arquivo, a requisição segue a especificação de requisições multipart do GraphQL: a operação vai no campo operations, com file: null nas variáveis; o campo map liga a parte do arquivo à variável file; o arquivo vai numa parte própria. Sem arquivo, a requisição JSON de sempre continua válida.

mutation ($value: Any, $file: Upload) {
  documentCreate(entityName: "ficha-tecnica", value: $value, file: $file) {
    id
    data
    files {
      url
      createdAt
    }
  }
}

Com curl:

curl https://storefront-api.fbits.net/graphql \
  -H "TCS-Access-Token: <token-da-loja>" \
  -F operations='{"query":"mutation ($value: Any, $file: Upload) { documentCreate(entityName: \"ficha-tecnica\", value: $value, file: $file) { id data files { url createdAt } } }","variables":{"value":{"sku":"ABC-123","cor":"Azul"},"file":null}}' \
  -F map='{"0":["variables.file"]}' \
  -F [email protected]

No navegador, com FormData

const operations = {
  query: `mutation ($value: Any, $file: Upload) {
    documentCreate(entityName: "ficha-tecnica", value: $value, file: $file) {
      id
      files { url createdAt }
    }
  }`,
  variables: { value: { sku: "ABC-123", cor: "Azul" }, file: null },
};

const form = new FormData();
form.append("operations", JSON.stringify(operations));
form.append("map", JSON.stringify({ 0: ["variables.file"] }));
form.append("0", inputArquivo.files[0]);

// Não defina Content-Type: o navegador monta o boundary do multipart.
const resposta = await fetch("https://storefront-api.fbits.net/graphql", {
  method: "POST",
  headers: { "TCS-Access-Token": token },
  body: form,
});

Códigos de erro

Código	Mensagem	Descrição
`WDC108`	Arquivo inválido	Arquivo recusado antes do envio: vazio, sem extensão, com extensão não aceita ou acima de 5 MB. O motivo vem na extensão `detail`
`WDC101`	Documento inválido	O document não é um objeto JSON válido, excede 2.000 caracteres ou não atende ao `schema` da entidade ou o arquivo foi recusado pelo serviço de arquivos (tipo não aceito, conteúdo que não corresponde à extensão ou tamanho acima do máximo
`WDC109`	O serviço de arquivos está indisponível	O armazenamento de arquivos está indisponível. Ocorre apenas em escritas com arquivo; a mesma operação sem arquivo pode ser feita

Veja a tabela completa em Document Wake - visão geral.

Parâmetros

Campos de retorno

Exemplo

Limite de tamanho

O identificador externo (externalId) não é definido por esta mutation

Enviando um arquivo

Códigos de erro

O identificador externo (`externalId`) não é definido por esta mutation