---
updatedAt: 2026-10-09T22:07:51.000Z
agentTools:
  projectIndex: https://wakecommerce.readme.io/llms.txt
---

# 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

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

<details>
<summary>Mostrar resposta</summary>
<br />

```json Response

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

</details>

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

<Callout icon="🚧" theme="warn">
  ### 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.
</Callout>

<Callout icon="📘" theme="info">
  ### O identificador externo (`externalId`) não é definido por esta mutation

  O `externalId` de um document — usado como filtro na query [Documents](https://wakecommerce.readme.io/docs/documents) — é informado apenas na criação pela API Pública, em [Inserindo um document](https://wakecommerce.readme.io/docs/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.
</Callout>

### Enviando um arquivo

Com arquivo, a requisição segue a [especificação de requisições multipart do GraphQL](https://github.com/jaydenseric/graphql-multipart-request-spec): 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.

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

Com curl:

```json
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 0=@ficha-abc-123.pdf
```

No navegador, com `FormData`

```json
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.](https://wakecommerce.readme.io/docs/document-wake-vis%C3%A3o-geral)