# Como corrigir o erro de Export/Import com JSON corrompido no ACF PRO

O erro de export/import com JSON corrompido no ACF PRO ocorre quando o arquivo .json do grupo de campos chega malformado, sem a chave key esperada ou com modified inconsistente, fazendo o ACF recusar a importação ou não exibir a sincronizacao.

## O que é erro de Export/Import com JSON corrompido no ACF PRO?

O ACF PRO move grupos de campos entre sites e ambientes de três formas baseadas no mesmo formato JSON: o Export/Import manual em ACF -> Tools (baixa e envia um arquivo .json), o Local JSON automático na pasta acf-json do tema e os comandos wp acf json do WP-CLI. Cada grupo de campos vira um arquivo nomeado pela sua chave única (key), e o ACF usa o valor modified, um timestamp unix em GMT, para decidir o que esta desatualizado. O erro de export/import com JSON corrompido aparece quando esse arquivo chega quebrado: a importação falha, a aba de sincronizacao não surge ou o grupo importado não bate com o original.

A causa raiz quase sempre esta no próprio arquivo .json e no caminho que ele percorreu. Um editor que reescreve o arquivo com aspas tipograficas, uma codificacao diferente de UTF-8, um envio FTP em modo ASCII que corrompe bytes, ou uma edição manual que deixa virgula sobrando produzem JSON invalido que o ACF não consegue ler. Quando o JSON e valido mas falta a chave key, ou a pasta acf-json não existe e não e gravavel, o ACF também deixa de detectar e importar o grupo, segundo a documentação oficial.

## Como identificar

- Ao enviar o arquivo em ACF -> Tools -> Import Field Groups, a tela retorna a mensagem 'Invalid JSON file. Please try again.' e nada e importado.
- A aba 'Sync available' não aparece em ACF -> Field Groups mesmo após colocar o arquivo .json correto na pasta acf-json do tema.
- O grupo de campos importado aparece duplicado ou com a chave (key) diferente, em vez de atualizar o grupo existente.
- O comando wp acf json import retorna erro de parse do JSON ou 'no items to import' apontando para o arquivo enviado.
- Os campos importados perdem acentuacao ou exibem caracteres como ã e ç, indicando que o arquivo não esta em UTF-8.

**Antes de começar:** Antes de importar um arquivo de grupos de campos ou sincronizar o Local JSON em producao, faça um backup do banco de dados e teste primeiro em staging, porque a importação sobrescreve os grupos de campos existentes que tenham a mesma chave key.

## Como prevenir

- Versione a pasta acf-json no Git junto com o tema, para que cada grupo de campos tenha o .json rastreado e a sincronizacao reproduza o estado exato entre ambientes.
- Nunca abra o arquivo .json em editores de texto rico como o Word; use apenas editores de código que preservam UTF-8 e aspas retas.
- Transfira arquivos .json sempre em modo binario no FTP, ou prefira os comandos wp acf json export e import para evitar corrupcao na transferencia.
- Padronize o fluxo de deploy usando wp acf json status antes de publicar, para conferir o que esta dessincronizado sem editar JSON na mao.

Erros relacionados

- [Como corrigir a incompatibilidade do ACF PRO com o editor Gutenberg](https://full.services/wp-fixer/corrigir-compatibilidade-gutenberg-acf-pro/)
- [Como corrigir o Clone Field que não duplica campos no ACF PRO](https://full.services/wp-fixer/corrigir-clone-field-acf-pro/)
- [Como corrigir o WYSIWYG Editor que não carrega no ACF PRO](https://full.services/wp-fixer/corrigir-wysiwyg-editor-acf-pro/)

## Causa

- O arquivo .json foi aberto e salvo em um editor que converteu aspas retas em aspas tipograficas ou trocou a codificacao para algo diferente de UTF-8, tornando o JSON invalido para o parser do ACF.
- O envio do arquivo por FTP foi feito em modo ASCII em vez de binario, corrompendo quebras de linha e bytes do .json durante a transferencia para a pasta acf-json.
- Uma edição manual no JSON deixou virgula sobrando antes de uma chave de fechamento ou removeu uma aspa, quebrando a sintaxe que o ACF exige para importar o grupo.
- O objeto do grupo de campos perdeu a propriedade key (a chave única que o ACF usa para nomear o arquivo e casar o grupo), entao a importação cria um grupo novo em vez de atualizar o existente.
- A pasta acf-json não existe no tema ativo ou não tem permissão de escrita (a doc recomenda 755), entao o Local JSON não salva nem detecta o arquivo para sincronizar.
- O valor modified do arquivo .json e menor ou igual ao post_modified do grupo no banco, e por isso o ACF não oferece a sincronizacao, segundo a regra de comparacao de timestamp da documentação.

## Como resolver

1. Valide a sintaxe do arquivo .json antes de importar: Abra o arquivo em um editor de texto puro e cole o conteúdo em um validador de JSON para localizar virgula sobrando, aspa faltando ou aspas tipograficas. O ACF recusa o arquivo com a mensagem Invalid JSON file quando a sintaxe esta quebrada.

```
Abra o arquivo em um editor de código (VS Code, Notepad++), nunca no Word
Cole o conteúdo em https://jsonlint.com para apontar a linha do erro de sintaxe
Substitua aspas tipograficas por aspas retas e remova qualquer virgula antes de } ou ]
```

2. Garanta a codificacao UTF-8 sem BOM: O ACF gera e espera o JSON em UTF-8. Reabra o arquivo e salve novamente como UTF-8 sem BOM para corrigir acentuacao quebrada e bytes invisiveis que travam o parser ao importar o grupo de campos.

```
No VS Code, clique na codificacao na barra inferior -> Save with Encoding -> UTF-8
No Notepad++, menu Codificacao -> Converter para UTF-8 (sem BOM) e salve
```

3. Importe pela tela Tools com o arquivo limpo: Com o JSON valido, use a importação oficial do ACF em vez de copiar para a pasta na mao. Selecione o arquivo e importe; a tela mostra os grupos detectados antes de gravar no banco.

```
Painel WP -> ACF -> Tools -> aba Import Field Groups
Clique em Selecionar arquivo, escolha o .json validado e clique em Import File
```

4. Confira a chave key e o caminho da pasta acf-json: Se o grupo importou duplicado, confirme que o objeto mantem a propriedade key original, pois o ACF nomeia o arquivo e casa o grupo por essa chave. Para o Local JSON, garanta a pasta acf-json no tema ativo e gravavel.

```
No arquivo, confirme uma linha como "key": "group_5f3a1b2c3d4e" no topo do objeto
Crie a pasta acf-json na raiz do tema ativo (mesmo nível do functions.php)
Ajuste a permissão da pasta para 755 e envie o .json por FTP em modo binario
```

5. Force a detecção de sincronizacao pelo WP-CLI: Quando a aba Sync available não aparece, verifique o status pelo WP-CLI e rode a importação por linha de comando, que mostra o erro de parse exato. Isso exige ACF 6.8 ou superior e WP-CLI 2.0 ou superior, conforme a documentação.

```
wp acf json status
wp acf json import --type=field-group
wp acf json sync
```


## Código

```php
<?php
// Aponta o Local JSON para uma pasta dedicada e versionada no tema.
add_filter( 'acf/settings/save_json', 'full_acf_json_save_point' );
function full_acf_json_save_point( $path ) {
    return get_stylesheet_directory() . '/acf-json';
}

// Permite carregar o JSON de mais de um caminho (tema + plugin), evitando duplicar grupos.
add_filter( 'acf/settings/load_json', 'full_acf_json_load_point' );
function full_acf_json_load_point( $paths ) {
    $paths[] = get_stylesheet_directory() . '/acf-json';
    return $paths;
}
```

## Perguntas frequentes

### Por que o ACF mostra Invalid JSON file ao importar

Essa mensagem indica que o arquivo enviado não e um JSON valido. Quase sempre ha virgula sobrando, aspa faltando ou aspas tipograficas inseridas por um editor de texto rico. Valide o conteúdo em um validador de JSON, corrija a sintaxe e salve o arquivo em UTF-8 antes de importar de novo.

### O que e a chave key no arquivo de grupo de campos do ACF

A key e a chave única do grupo de campos. Segundo a documentação, o ACF usa essa chave para nomear o arquivo na pasta acf-json e para casar o grupo do JSON com o do banco. Se a key for removida ou alterada, a importação cria um grupo novo em vez de atualizar o existente.

### Por que a aba Sync available não aparece no ACF

O ACF so oferece sincronizacao quando o grupo não existe no banco pela mesma key ou quando o valor modified do arquivo .json e maior que o post_modified registrado no banco. Se o timestamp modified for igual ou menor, a aba não surge. Confira também se a pasta acf-json existe no tema ativo e e gravavel.

### Onde fica a pasta acf-json e qual permissão ela precisa

A pasta acf-json deve ficar na raiz do tema ativo, no mesmo nível do functions.php. A documentação recomenda que ela seja gravavel pelo servidor, e na maioria dos casos a permissão 755 funciona bem para o Local JSON salvar e carregar os arquivos.

### Como importar grupos de campos do ACF pela linha de comando

O ACF oferece os comandos wp acf json export, wp acf json import, wp acf json status e wp acf json sync. Use wp acf json status para ver o que esta dessincronizado e wp acf json import com o tipo field-group para importar. Esses comandos exigem ACF 6.8 ou superior e WP-CLI 2.0 ou superior.

### Por que os campos importados perdem acentuacao

Acentos virando caracteres como ã e ç são sinal de que o arquivo não esta em UTF-8 ou foi enviado por FTP em modo ASCII. Salve novamente o .json como UTF-8 sem BOM no editor de código e transfira em modo binario para preservar os bytes originais.

### Posso editar o arquivo .json do ACF na mao

Pode, mas com cuidado. Use um editor de código, preserve a key e o valor modified, e valide a sintaxe antes de importar. Para evitar erros, o caminho mais seguro e exportar e importar pela tela Tools ou pelos comandos wp acf json, que geram o JSON no formato correto.

### A importação de JSON sobrescreve meus grupos de campos atuais

Sim, quando a key do arquivo casa com a de um grupo já existente, a importação atualiza esse grupo. Por isso faça backup do banco e teste em staging antes de importar em producao, para não perder ajustes locais que ainda não estavam no arquivo.

**Fonte:** [Advanced Custom Fields — Local JSON](https://www.advancedcustomfields.com/resources/local-json/)