Configure propriedades de materiais e modelos para materiais de acabamento

Crie materiais de acabamento com base em cor ou textura, gerencie modelos de materiais e envie texturas que se associem corretamente aos materiais.

1. O modal Material Properties (usado ao criar/editar materiais de acabamento em SKUs) permite ao usuário escolher uma propriedade base de Cor ou Textura. Se Textura for selecionada, uma imagem deve realmente ser enviada — caso contrário, Salvar é bloqueado com 'Please upload a texture file'; voltar para Cor limpa qualquer mapa de textura enviado ao salvar. Os envios de textura são armazenados imediatamente na seleção (cada envio cria um ativo de textura), e sliders/inputs controlam propriedades no estilo PBR (rugosidade, metalicidade, transmissão etc.; alguns campos, como os dependentes de transmissão, mostram placeholders até que os valores habilitadores sejam definidos). Peculiaridade que vale conhecer: o toggle 'lock aspect ratio' de largura/altura da textura é persistido no localStorage do navegador por material — ele não sincroniza entre máquinas ou usuários, então o estado do toggle pode diferir entre computadores. Material Templates (presets nomeados dessas propriedades) são gerenciados separadamente: o nome do modelo é obrigatório ('Material Template name cannot be empty'), os modelos podem ser atualizados ou adicionados, e uma ação de restaurar reverte os valores editados para os valores armazenados no modelo. Os modelos importam para a criação em massa via CSV de SKUs de Acabamento/núcleo de painel, em que material_template_id deve referenciar um modelo existente da planilha de referência.

   ✓ Verificado no produto em 18 de outubro de 2026

2. Quando a propriedade base é Textura, o editor de material também oferece slots opcionais de mapa de relevo e mapa normal, além da textura base, para que profundidade possa ser adicionada sobre a textura enviada.

   ✓ Verificado no produto em 18 de outubro de 2026

3. O modelo determina quais propriedades de renderização o acabamento usa.

   ✓ Verificado no produto em 18 de outubro de 2026

4. Quando um material é criado ou atualizado (UI ou API empresarial), seu JSON de propriedades é validado em relação ao modelo de material vinculado: o modelo define o conjunto exato de nomes de propriedades permitidos (cor, opacidade, rugosidade, metalicidade, os slots de mapa de textura etc.). Qualquer chave não definida no modelo faz o salvamento falhar com PROPERTY_KEY_MISMATCH_WITH_MATERIAL_TEMPLATE_PROPERTY. Chaves ausentes NÃO são verificadas — um material pode ser salvo com apenas um subconjunto das propriedades do modelo, sem nenhum aviso. A falha clássica é um cliente reutilizar um payload de propriedades escrito para um modelo enquanto passa um material_template_id diferente: chaves válidas para o modelo antigo são rejeitadas no novo. Mecânicas da API que também confundem as pessoas: as propriedades devem ser enviadas como um objeto JSON em string — uma string não analisável falha com MATERIAL_CREATION_FAILURE (ou MATERIAL_UPDATE_FAILURE), e enviar um array em vez de um objeto falha com INVALID_PARAMS. Se o material_template_id não existir, o erro é MATERIAL_TEMPLATE_NOT_FOUND. Quando um cliente relatar um desses erros, peça que ele busque o modelo, liste os rótulos de propriedades dele e reduza o payload exatamente a essas chaves.

5. As texturas são enviadas como form-data com dois campos, file e name; os formatos suportados são jpeg, jpg e png. O envio cria um registro de imagem mais um registro de textura que a referencia, e a resposta retorna a textura com sua imagem embutida. Permissões: o envio exige direitos de gerente de catálogo na loja ou unidade de negócio, mas designers também são explicitamente permitidos — um designer pode adicionar texturas pelo aplicativo de design mesmo sem direitos de gerenciamento de catálogo. Para usar uma textura em um material, seu id vai na propriedade 'map' do material. Apenas esse mapa base é validado ao salvar o material: se o id do mapa não corresponder a uma textura existente, o salvamento falha (MATERIAL_CREATION_FAILURE / MATERIAL_UPDATE_FAILURE), e, em caso de sucesso, a imagem da textura se torna automaticamente a amostra de exibição do material. Os outros slots de mapa — mapas normal, de oclusão ambiente, de relevo, de metalicidade e de rugosidade — aceitam ids de textura, mas NÃO têm a existência verificada no momento do salvamento, então um id errado ali é salvo sem nenhum erro e simplesmente não é resolvido depois. Se um cliente disser que o mapa normal ou de rugosidade 'does nothing', verifique se o id aponta para uma textura real antes de depurar a renderização.