Documentação

Inserindo uma entidade de document

POST https://api.fbits.net/document/entities

Parâmetros para criação:

    • name - nome da entidade, único na loja e com até 100 caracteres;
    • schema - JSON Schema (draft 2020-12) dos documents da entidade, com raiz type: object e ao menos uma propriedade em properties;
    • publicOperations - operações públicas da entidade: CREATE, READ, UPDATE, DELETE (opcional);
    • allowAdditionalProperties - permite que os documents da entidade tenham propriedades não declaradas em properties (opcional, padrão false).
{
  "name": "ficha-tecnica",
  "schema": "{\"type\":\"object\",\"properties\":{\"sku\":{\"type\":\"string\",\"publicView\":true,\"filterable\":true},\"peso\":{\"type\":\"number\"}},\"required\":[\"sku\"]}",
  "publicOperations": ["READ"],
  "allowAdditionalProperties": true
}

Response body:

{
  "id": 12,
  "name": "ficha-tecnica",
  "schema": "{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"sku\":{\"type\":\"string\",\"publicView\":true,\"filterable\":true},\"peso\":{\"type\":\"number\",\"publicView\":false,\"filterable\":false}},\"required\":[\"sku\"]}",
  "publicOperations": ["READ"],
  "allowAdditionalProperties": true,
  "createdAt": "2026-07-27T13:45:10.123Z",
  "updatedAt": "2026-07-27T13:45:10.123Z"
}

Atributos por propriedade do schema

Cada item de properties aceita dois atributos próprios do Document Wake, ambos opcionais e válidos apenas no primeiro nível do objeto:

AtributoTipoPadrãoDescrição
publicViewbooleanofalseQuando true, a propriedade é devolvida nas leituras públicas do document (Storefront API)
filterablebooleanofalseQuando true, a propriedade pode ser usada como critério na busca por conteúdo e é materializada no índice de busca

Os dois são independentes: uma propriedade pode ser filterable: true com publicView: false, e vice-versa. A normalização do schema acrescenta ambos com false nas propriedades em que não foram informados — é por isso que o schema retornado traz mais atributos do que o enviado.

📘

É bom saber:

Com allowAdditionalProperties: true, um document desta entidade pode conter propriedades que não estão no schema, em qualquer profundidade. Com false ou ausente, a gravação de um document com propriedade não declarada retorna 400 indicando o caminho da propriedade (ex.: /peso, /cfg/extra, /tags/0/extra). Subschemas que não declaram nenhuma propriedade (ex.: {"type":"object"}) são trechos livres e aceitam qualquer conteúdo, independentemente desse campo.

🚧

Regras do filterable

  • A propriedade marcada com filterable: true deve declarar um type suportado pelo índice de busca: string, number, integer, boolean ou string com format de data. Tipo ausente, múltiplo ou não suportado (object, array) retorna 400;
  • Cada entidade aceita no máximo 8 propriedades com filterable: true. A partir da nona o schema é rejeitado com 400.
🚧

Importante saber

O retorno é 409 quando já existe uma entidade com o mesmo nome na loja, 400 quando o schema informado não é um JSON Schema válido, não declara type: object na raiz, não declara nenhuma propriedade em properties na raiz, marca como filterable uma propriedade de tipo não suportado ou excede o limite de 8 propriedades filtráveis, e 403 quando a funcionalidade documents não está habilitada para a loja.

Updated 12 days ago