DOCX Reader

1. Visão Geral

O componente DOCX Reader (docx-reader) lê e manipula arquivos Word (.docx): extrai o texto, extrai metadados do documento, ou preenche um modelo substituindo marcadores por valores (interpolação).

Use quando o fluxo precisa ler o conteúdo de um documento Word recebido, ou gerar um novo documento a partir de um modelo Word preenchendo campos automaticamente. Só funciona como ação de saída — não como gatilho de entrada.

2. Pré-requisitos

O arquivo .docx precisa estar disponível na mensagem antes deste componente rodar (por exemplo, resultado de um upload anterior no fluxo).

3. Autenticação e Conexão

Não aplicável — não há conexão com sistemas externos.

4. Configuração / Operações Suportadas

Campo	Obrigatório	Tipo	Descrição	Exemplo
operation	Sim	Texto: EXTRACT_TEXT, GET_METADATA ou INTERPOLATE	Operação a ser executada.	"EXTRACT_TEXT"
docxFile	Sim	Texto	Nome da propriedade da mensagem onde está o arquivo .docx.	"contrato"

EXTRACT_TEXT — extrair o texto do documento

Campo	Obrigatório	Tipo	Descrição	Exemplo
format	Não	Texto: text ou markdown	Formato do texto extraído. Valor padrão: "text".	"markdown"

Resposta: {"text":..., "format":..., "length":..., "paragraphs":..., "tables":...}.

GET_METADATA — extrair metadados do documento

Sem campos extras. Resposta: {"title":..., "subject":..., "creator":..., "description":..., "keywords":..., "category":..., "created":..., "modified":..., "paragraphs":..., "tables":..., "images":..., "wordCount":...}.

INTERPOLATE — preencher um modelo com valores

Campo	Obrigatório	Tipo	Descrição	Exemplo
payload	Sim	Texto (JSON)	Dados usados para substituir os marcadores do modelo. Suporta chaves aninhadas com ponto (ex.: cliente.nome).	{"cliente": {"nome": "Maria Silva"}}
pattern	Não	Texto (regex)	Padrão usado para identificar os marcadores no documento. Valor padrão: marcadores no formato ${nome}.	"\\$\\{([a-zA-Z0-9_\\.\\-]+)\\}"
output	Não	Texto	Nome do arquivo .docx gerado. Valor padrão: um nome gerado automaticamente.	"contrato-preenchido.docx"

Resposta: {"file":..., "placeholdersPattern":...}. O documento gerado fica disponível como propriedade da mensagem, com o nome definido em output.

5. Exemplos Práticos

Exemplo simples: extrair o texto de um contrato recebido em .docx.

Entrada:

{
  "contrato": "<arquivo .docx, disponibilizado por um passo anterior>"
}

Configuração do componente:

{
  "componentName": "docx-reader",
  "configurations": {
    "operation": "EXTRACT_TEXT",
    "docxFile": "contrato"
  }
}

Resposta:

{
  "text": "CONTRATO DE PRESTAÇÃO DE SERVIÇOS\n\nEntre as partes...",
  "format": "text",
  "length": 3200,
  "paragraphs": 24,
  "tables": 1
}

Exemplo avançado: preencher um modelo de contrato com dados do cliente, gerando um novo .docx.

Entrada:

{
  "modeloContrato": "<arquivo .docx modelo, com marcadores como ${cliente.nome}>",
  "cliente": { "nome": "Maria Silva", "cpf": "123.456.789-00" }
}

Configuração do componente:

{
  "componentName": "docx-reader",
  "configurations": {
    "operation": "INTERPOLATE",
    "docxFile": "modeloContrato",
    "payload": "{\"cliente\": {\"nome\": \"{$.body.cliente.nome}\", \"cpf\": \"{$.body.cliente.cpf}\"}}",
    "output": "contrato-maria-silva.docx"
  }
}

Resposta:

{
  "file": "contrato-maria-silva.docx",
  "placeholdersPattern": "\\$\\{([a-zA-Z0-9_\\.\\-]+)\\}"
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"operation is required"	O campo operation não foi preenchido.	Preencher operation com um dos valores suportados.
"Unsupported operation: [valor]"	O valor de operation não é reconhecido.	Usar EXTRACT_TEXT, GET_METADATA ou INTERPOLATE.
"docxFile parameter is required"	O campo docxFile não foi preenchido.	Preencher docxFile com o nome da propriedade que contém o arquivo.
"File [nome] not found inside the execution context."	O arquivo referenciado não está disponível na mensagem com esse nome.	Confirmar que um passo anterior disponibilizou o arquivo com esse nome exato.
"payload parameter is required"	A operação INTERPOLATE foi usada sem o campo payload.	Preencher payload com os dados a substituir nos marcadores.
"Invalid payload JSON: ..."	O texto de payload não é um JSON válido.	Revisar a sintaxe do JSON em payload.