Modificadores de dados

Um modificador de dados é uma pequena regra que a importação de produtos aplica a um campo de todas as linhas do arquivo, antes de gravar. Em vez de editar a planilha do fornecedor, você diz "some 10% ao preço", "coloque o prefixo NOVO no nome" ou "troque Cx por Caixa na descrição". O fornecedor continua mandando o mesmo arquivo todo mês, e a regra continua valendo.

Esta rota apenas lista os tipos de modificador disponíveis (com nome, se pedem valor e a que tipo de campo se aplicam). Quem os aplica é o passo de execução da importação, que recebe a lista em options.data_modifiers.

Quando usar

• Margem sobre a tabela do fornecedor. percent_markup no campo price com value 30.
• Desconto de campanha. percent_discount no price com value 15.
• Preço de caixa para unidade. multiply no price com fator 0.1.
• Padronizar nomes. text_prefix ou text_suffix no name.
• Corrigir abreviações. text_replace na description.
• Forçar um valor em todas as linhas. set_value em status ou vendor_id.
• Arredondar. round no price depois de um multiply.

Listar os modificadores

Exemplo de requisição

curl "$BASE_URL/api/v1/admin/data-modifiers" \
  -H "Authorization: Bearer $TOKEN"

Resposta

[
  { "type": "none", "label": "No modifier", "label_pt": "Sem modificador", "needs_value": false, "needs_value2": false, "applies_to": "all" },
  { "type": "percent_markup", "label": "Increase by %", "label_pt": "Aumentar em %", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "percent_discount", "label": "Decrease by %", "label_pt": "Diminuir em %", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "fixed_add", "label": "Add fixed amount", "label_pt": "Adicionar valor fixo", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "fixed_subtract", "label": "Subtract fixed amount", "label_pt": "Subtrair valor fixo", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "multiply", "label": "Multiply by factor", "label_pt": "Multiplicar por fator", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "round", "label": "Round to N decimals", "label_pt": "Arredondar para N decimais", "needs_value": true, "needs_value2": false, "applies_to": "numeric" },
  { "type": "text_prefix", "label": "Add text prefix", "label_pt": "Adicionar prefixo de texto", "needs_value": true, "needs_value2": false, "applies_to": "text" },
  { "type": "text_suffix", "label": "Add text suffix", "label_pt": "Adicionar sufixo de texto", "needs_value": true, "needs_value2": false, "applies_to": "text" },
  { "type": "text_replace", "label": "Find and replace", "label_pt": "Localizar e substituir", "needs_value": true, "needs_value2": true, "applies_to": "text" },
  { "type": "set_value", "label": "Set fixed value", "label_pt": "Definir valor fixo", "needs_value": true, "needs_value2": false, "applies_to": "all" }
]

Erros

Como cada modificador transforma o valor

Cada item de data_modifiers tem este formato:

{ "type": "percent_markup", "value": "10", "value2": "", "field_key": "price" }

Regras que evitam surpresa:

• Texto de entrada. O modificador trabalha sobre o texto da célula. Os numéricos aceitam o formato brasileiro (1.234,56) e o prefixo R$.
• Saída numérica. Os numéricos devolvem sempre duas casas decimais com ponto (54.89), exceto round, que usa o número de casas pedido. Como a conversão acontece antes de a plataforma interpretar o preço, informe price_format (decimal ou cents) em vez de deixar auto, para o resultado ser lido do jeito que você espera.
• Célula vazia. Os modificadores numéricos deixam a célula vazia como está. set_value e os de texto agem mesmo assim.
• Ordem. Vários modificadores no mesmo field_key rodam na ordem da lista, cada um sobre o resultado do anterior. Faça multiply antes de round.
• Erro. Se a célula não for um número (ou o value não for válido), a linha registra um modifier error com o campo e o motivo, e o valor original é mantido.
• Percentuais. percent_markup e percent_discount recebem o percentual em value como número comum: 10 significa 10%.

Campos aceitos em field_key

sku, name, slug, price, list_price, cost_price, quantity, min_quantity, max_quantity, quantity_step, status, category_id, vendor_id, description, short_description, promo_text, weight, length, width, height, free_shipping, shipping_freight, meta_title, meta_description, meta_keywords, barcode, out_of_stock_actions, zero_price_action. Um field_key fora desta lista é ignorado em silêncio.

Veja também

• Webhooks e eventos
• Criar pedido