Como Usar VBA para Mala Direta a Partir de Fonte de Dados Personalizada

Quando o assistente de mala direta integrado do Word não consegue se conectar à sua fonte de dados específica, como um banco de dados personalizado, um endpoint de API ou um formato de arquivo proprietário, você precisa de uma abordagem mais flexível. O Visual Basic for Applications permite escrever código que extrai dados de praticamente qualquer fonte e cria documentos mesclados diretamente. Este artigo explica como usar VBA para ignorar as conexões de fonte de dados padrão e criar uma mala direta a partir de uma matriz na memória ou arquivo personalizado. Você aprenderá os principais objetos VBA, a estrutura de código passo a passo e como lidar com erros comuns quando os dados não vêm de uma fonte reconhecida pelo Word.

Entendendo a Mala Direta VBA com Dados Personalizados

O recurso de mala direta do Word é projetado para se conectar a fontes de dados por meio de drivers Open Database Connectivity, OLE DB ou diretamente para Excel, Access, contatos do Outlook e arquivos de texto. Quando seus dados residem em uma fonte personalizada, como um arquivo JSON, um banco de dados SQLite, uma resposta de serviço web ou um sistema ERP proprietário, o método padrão MailMerge.OpenDataSource não consegue interpretá-la. O VBA resolve isso permitindo que você leia os dados usando qualquer método, armazene-os em uma matriz ou coleção e, em seguida, percorra cada registro para criar documentos mesclados individuais. O segredo é que você não usa uma fonte de dados conectada. Em vez disso, insere campos de mesclagem no documento principal, executa a mesclagem em pausa e substitui cada campo pela próxima linha de dados manualmente. Essa abordagem funciona com qualquer formato de dados que o VBA possa analisar, incluindo arquivos de texto, recordsets ADODB ou até matrizes codificadas na macro.

Pré-requisitos para a Macro de Mala Direta VBA

Antes de escrever a macro, verifique o seguinte:

• Você tem um documento do Word com o conteúdo principal e os campos de mesclagem já inseridos. Para uma fonte de dados personalizada, você deve inserir os campos de mesclagem manualmente usando o diálogo Inserir > Partes Rápidas > Campo > MergeField, ou via código VBA.
• Sua fonte de dados personalizada está acessível a partir do VBA. Por exemplo, se os dados estiverem em um arquivo de texto, você pode usar a instrução Open e Line Input para lê-los. Se os dados estiverem em um banco de dados, você pode usar ADO com uma string de conexão.
• As macros estão habilitadas no Word. Vá em Arquivo > Opções > Central de Confiabilidade > Configurações da Central de Confiabilidade > Configurações de Macro e selecione Habilitar todas as macros para teste.
• Você conhece os nomes dos campos que usará no documento de mesclagem. Esses nomes devem corresponder às chaves em sua estrutura de dados personalizada.

Passos para Criar uma Mala Direta VBA a Partir de uma Fonte de Dados Personalizada

A macro a seguir lê dados de um arquivo de texto separado por vírgulas e cria um documento mesclado separado para cada registro. Você pode adaptar a parte de leitura para qualquer fonte de dados.

1. Abra o Editor Visual Basic
   Pressione Alt+F11 no Word para abrir o editor VBA. No Explorador de Projetos, localize o projeto do seu documento e insira um novo módulo clicando em Inserir > Módulo.
2. Declare variáveis e a sub-rotina principal
   Inicie a sub-rotina com as declarações de variáveis necessárias. O exemplo abaixo usa um arquivo de texto como fonte de dados. Substitua o caminho do arquivo pelo seu próprio arquivo de dados.
   Sub MailMergeFromCustomDataSource()
Dim wdDoc As Document
Dim wdMerge As MailMerge
Dim sData() As String
Dim vRecord As Variant
Dim i As Long
Dim sLine As String
Dim iFile As Integer
Dim aFields() As String
Dim sFieldNames() As String
Dim sFieldValues() As String
Dim j As Long
Set wdDoc = ActiveDocument
Set wdMerge = wdDoc.MailMerge
3. Leia o arquivo de dados personalizado em uma matriz
   Abra o arquivo de texto, leia todas as linhas e armazene-as em uma matriz. A primeira linha contém os nomes dos campos. As linhas subsequentes contêm valores de dados separados por vírgulas. Este exemplo assume que o arquivo está na mesma pasta do documento.
   iFile = FreeFile
Open ThisDocument.Path & "\data.txt" For Input As #iFile
sLine = Input(LOF(iFile), iFile)
Close #iFile
sData = Split(sLine, vbCrLf)
' Primeira linha são nomes dos campos
sFieldNames = Split(sData(0), ",")
' Remove linhas vazias no final
If Right(sData(UBound(sData)), 1) = vbCr Then
ReDim Preserve sData(UBound(sData) - 1)
End If
4. Insira campos de mesclagem no documento principal
   Se o documento ainda não tiver campos de mesclagem, insira-os no início. Este código adiciona campos para cada nome de coluna. Execute esta seção apenas uma vez por configuração de documento.
   ' Opcional: Insere campos de mesclagem no topo do documento
wdDoc.Range.InsertBefore "Prezado "
For j = 0 To UBound(sFieldNames)
wdDoc.MailMerge.Fields.Add wdDoc.Range, sFieldNames(j)
If j < UBound(sFieldNames) Then wdDoc.Range.InsertText ", "
Next j
wdDoc.Range.InsertParagraphAfter
5. Percorra cada linha de dados e crie documentos mesclados
   Para cada linha de dados após o cabeçalho, divida os valores e execute a mesclagem com Pause=True para inserir os valores manualmente. A mesclagem cria um novo documento para cada registro.
   For i = 1 To UBound(sData)
If Len(sData(i)) > 0 Then
sFieldValues = Split(sData(i), ",")
With wdMerge
.Destination = wdSendToNewDocument
.Execute Pause:=True
End With
' A mesclagem pausada abre um novo documento com campos de mesclagem
' Substitua cada campo de mesclagem pelo valor correspondente
For j = 0 To UBound(sFieldNames)
With wdDoc.MailMerge.DataSource
.FindRecord FindText:=sFieldNames(j), Field:=sFieldNames(j)
If .Found Then
.SetAllIncludedFlags False
.SetAllIncludedFlags True
End If
End With
Next j
' Salve ou imprima o novo documento conforme necessário
ActiveDocument.SaveAs2 FileName:=ThisDocument.Path & "\Merged_" & i & ".docx"
ActiveDocument.Close
End If
Next i
6. Limpe e finalize a sub-rotina
   Libere as referências de objeto e exiba uma mensagem de conclusão.
   Set wdDoc = Nothing
Set wdMerge = Nothing
MsgBox "Mala direta concluída. Criados " & (UBound(sData)) & " documentos."
End Sub

Problemas Comuns ao Usar VBA para Mala Direta com Dados Personalizados

O Word Congela ou Trava ao Executar a Macro

Isso geralmente acontece quando o arquivo de dados é muito grande e a macro tenta processar milhares de registros em um único loop. Para evitar isso, processe registros em lotes de 100 e chame DoEvents após cada lote para liberar recursos do sistema. Além disso, certifique-se de que o documento principal não contenha formatação complexa ou imagens que retardem a mesclagem.

Os Campos de Mesclagem Não São Substituídos pelos Dados

Se o documento mesclado ainda mostrar códigos de campo como “{ MERGEFIELD FirstName }” em vez de valores reais, o método Execute Pause:=True pode não estar funcionando como esperado. Em vez de usar Pause, você pode substituir manualmente os campos no novo documento após a conclusão da mesclagem. Use um loop que percorra todos os campos no novo documento e substitua cada um pelo valor correspondente da sua matriz.

O Arquivo de Dados Contém Cabeçalhos ou Espaços Extras

Se sua fonte de dados personalizada tiver uma linha de cabeçalho que não deve ser tratada como dados, pule a primeira linha no loop. Use Trim em cada valor de campo para remover espaços iniciais e finais. Para arquivos CSV com campos entre aspas, use um analisador CSV adequado ou substitua vírgulas dentro de aspas por um espaço reservado antes de dividir.

Mala Direta VBA com Dados Personalizados vs Mala Direta Padrão

Recurso	Mala Direta Padrão	Fonte de Dados Personalizada VBA
Tipos de fonte de dados	Excel, Access, Outlook, arquivos de texto, SQL Server	Qualquer dado que o VBA possa ler: JSON, API, banco personalizado, matrizes
Complexidade de configuração	Usar assistente ou OpenDataSource	Escrever e depurar código VBA
Desempenho com grandes volumes	Rápido, gerenciado internamente pelo Word	Mais lento, cada registro processado individualmente
Tratamento de erros	Mensagens de erro integradas	Deve adicionar instruções On Error manualmente
Flexibilidade	Limitada aos conectores suportados	Controle total sobre leitura e transformação de dados

Para a maioria dos usuários empresariais, o assistente de mala direta padrão é suficiente quando os dados estão no Excel ou Access. Use a abordagem VBA apenas quando sua fonte de dados não for suportada pelos conectores integrados do Word ou quando precisar aplicar transformações complexas nos dados antes da mesclagem.

Agora você pode criar uma macro de mala direta que lê dados de qualquer fonte acessível ao VBA, como um arquivo de texto, uma consulta de banco de dados ou uma matriz. Comece testando a macro com uma pequena amostra de registros para verificar se os nomes dos campos de mesclagem correspondem às chaves dos seus dados. Para uma solução mais avançada, considere usar o método MailMerge.DataSource.EditRecord para editar registros programaticamente em vez de pausar a mesclagem. Uma dica concreta: ao ler dados CSV, use a biblioteca Microsoft Scripting Runtime com o FileSystemObject para ler arquivos linha por linha, o que lida com arquivos grandes de forma mais eficiente do que a instrução Input.