# Sincronizar metafields

Este guia explica como sincronizar metafields da sua Source store para a sua Destination store no app Tipo.

### ℹ️ O que são metafields?

* **Metafields de produto**
* **Metafields de variante** (se você ativar essa opção)

O app Tipo pode sincronizar metafields de:

* material, tabela de medidas, especificações
* selos personalizados (por exemplo, “best\_seller”)
* detalhes extras de produtos usados por temas ou apps

Metafields são campos personalizados no Shopify usados para armazenar dados extras de produtos, como:

***

### ✅ **Tipos de metafield suportados**

* Texto de várias linhas
* Rich text
* Inteiro
* Decimal
* Data e hora
* Data
* Dimensão
* Volume
* Peso
* Verdadeiro ou falso
* Avaliação
* URL
* Dinheiro
* Link
* JSON

🚫 **Ainda não suportados:**\
Tipos de referência (por exemplo, referência de produto, referência de coleção) não são suportados no momento.

***

### 🛠️ Etapa 1: configurar os metafields na Source Store

1. Abra o app > clique em **Settings** > ative **Share Metafields**
2. Escolha o recurso que você quer compartilhar:
   * **Product resource** – compartilhar metafields de produto.
   * **Variant resource** – compartilhar metafields de variante.
3. Adicione definições de metafield específicas para limitar quais metafields são compartilhados.
   * Clique no ícone **Browse metafields**, ou
   * Digite a definição do metafield no formato:

     ```
     namespace.key
     ```

Por exemplo:

     ```
     custom.materialseo.titlespecifications.weight
     ```
4. Click **Save** to update the changes

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

***

### 🛠️ Etapa 2: configurar os metafields na Destination Store

1. Abra o app > clique em **Stores** > clique na URL da loja de origem para abrir os detalhes da conexão

<figure><img src="/media/b99e7e334515ad4e086d.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. Ative **Metafields sync**
3. Escolha o que sincronizar

Em **Allow data**, selecione um ou ambos:

* **Product Resource** → sincroniza metafields de produto
   * **Variant Resource** → sincroniza metafields de variante
4. Clique no ícone de pesquisa à direita para ver todos os metafields suportados > clique no botão **Select valid metafield to sync**&#x20;

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

5. Clique em **Save** para atualizar as alterações

***

### &#x20;🔄 O que acontece durante a sincronização

#### **1) Se a Destination store não tiver a definição do metafield**

O app criará automaticamente a definição do metafield na Destination store (quando necessário).

Depois de criado, os valores sincronizados do metafield aparecerão no produto/variante da Destination store.

#### **2) Se os metafields existirem, mas não estiverem “estruturados” (metafields não estruturados)**

Em alguns casos, os metafields podem ser sincronizados mesmo que não tenham sido totalmente definidos/estruturados na Destination store.

Para revisá-los no Shopify Admin:

* **ab**ra as **Settings → Metafields and metaobjects** da loja
* Escolha **Product** (ou **Variant**)
* Abra **View unstructured metafields**

💡 Dica: você pode definir/estruturar esses metafields manualmente depois para manter os dados da sua loja limpos e consistentes.

<figure><img src="/media/755ea231da077f6819c8.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **3) Se a Source store não tiver valor, a Destination não será sobrescrita**

Se um metafield existir na Destination, mas o valor da Source estiver vazio, o Tipo Sync não sobrescreverá o valor da Destination.

#### **4) Os tipos de dados devem coincidir (muito importante)**

Os tipos de dados dos metafields devem coincidir exatamente entre a Source e a Destination.

Exemplos de incompatibilidade de tipos de dados:

* `single_line_text_field` vs `multi_line_text_field`
* `number_integer` vs `number_decimal`
* `product_reference` vs `text`

⚠️ Se os tipos de dados não coincidirem, a sincronização pode falhar ou ignorar esse metafield.

***

### 📌 Exemplo: sincronizando um metafield de produto – “Material”

Você quer sincronizar um **metafield personalizado de produto** chamado **Material** (por exemplo, “Algodão”, “Couro”, “Lã”) da sua **Source Store** para a sua **Destination Store** usando nosso app.

#### **Etapa 1: definir o metafield no Shopify**

Na sua **Source Store**:

1. Acesse **Shopify Admin >** abra as **Settings > Metafields and metaobjects** da loja > escolha **Product** (ou **Variant**)
2. Clique em **Add definition** (se ainda não estiver criada) > preencha a definição do metafield:
   * **Name**: Material
   * **Namespace**: `custom`
   * **Key**: `material`
   * **Type**: Single line text

\=>  Isso gera a chave completa do metafield: `custom.material`

Repita esta etapa na sua **Destination Store** (deve coincidir com a mesma chave e o mesmo tipo).

<figure><img src="/media/e68676d721f26cb93ef7.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **Etapa 2: adicionar dados de metafield aos produtos**

Na sua **Source Store**, acesse um produto, role até **Metafields** > em **Material**, digite: `Cotton`

Este produto agora tem o metafield `custom.material = "Cotton"`.

<figure><img src="/media/97a6ddb98ed50e435682.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **Etapa 3: configurar a sincronização no app Tipo**&#x20;

* Abra nosso app na **Destination Store** > acesse Connect Configuration **> Metafield Sync**
* Escolha **Specific Metafields > digite** a chave do metafield exatamente como: `custom.material`&#x20;

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

**Resultado**

* Nosso app encontrará `custom.material` na Source Store
* Se ele **não existir** no produto da Destination, o app o **criará**\
  \=>   Resultado: `custom.material = "Cotton"` nas duas lojas
* Se ele existir na Destination, mas estiver vazio na Source, **não substituímos** o valor

***

### ❓Perguntas frequentes

#### P1: como definir `namespace.key` na sua loja?

Para sincronizar um metafield específico, você precisará digitar a **chave da definição do metafield** neste formato: `namespace.key` (por exemplo: `custom.color`).

Veja como encontrá-la no seu admin do Shopify:

1. Acesse seu Shopify Admin > vá em **Settings > Custom Data > Products**
2. Clique no metafield que você quer sincronizar\
   → Você verá os valores **Namespace** e **Key**
3. Combine-os neste formato: `namespace.key`\
   → Exemplo: `custom.description`

#### P2: por que meus metafields não estão sincronizando?

Se seus metafields não estiverem sincronizando corretamente, pode ser por um dos seguintes motivos:

1. **A sincronização de metafields não está ativada**\
   Certifique-se de que a sincronização de metafields esteja ativada nas duas lojas:
   * Ative **Share Metafields** na **Source Store**.
   * Ative **Receive Metafields** na **Destination Store**.

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. **A chave da definição do metafield não foi adicionada**

Além de ativar a sincronização de metafields, você também precisa adicionar a **chave da definição do metafield (namespace.key)** que deseja sincronizar.

* Acesse **Settings → Share Metafields**
* Certifique-se de que **Enable** esteja marcado
* Em **Allow data**, adicione a definição do metafield neste formato:\
  `namespace.key`\
  Exemplo: `custom.material`&#x20;

<figure><img src="/media/f4d2b012b6b982aa41e6.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

3. **Tipos de metafield não suportados**\
   Alguns tipos de dados de metafield não são suportados, como **tipos de referência** ou **MetaObjects**.

Vermelho: metafields não suportados que não podem ser sincronizados pelo app

<figure><img src="/media/85f75cd1117f373c78df.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

4. **Tipos de metafield diferentes entre as lojas**\
   O metafield na Source e na Destination deve ter **o mesmo tipo de dados e a mesma estrutura**.\
   Incompatibilidades comuns incluem:

* Um metafield é **Single line text**, enquanto o outro é **Multi-line text**.
* Um metafield usa **Single value**, enquanto o outro usa **List of values**.

Para corrigir esses problemas, confirme que os metafields nas duas lojas têm o mesmo **namespace**, a mesma **key** e o mesmo **tipo de dado**, e depois tente sincronizar novamente.

***

**🙋 Ainda precisa de suporte?**

Se ainda precisar de ajuda, entre em contato conosco pelo e-mail <hi@tipo.io>. Teremos prazer em ajudar você.
