Uso de SFTP

Esta página orienta como usar os serviços automáticos de importação via SFTP para Templates e Campanhas no Maestro.

Configuração

A configuração de SFTP é feita em Configurações > Empresa > Transferência de Arquivos. A Gerente do Ambiente decide se as assessorias podem usar um SFTP próprio ou apenas o gerenciado pela Robbu.

SFTP Robbu

A Robbu disponibiliza um servidor SFTP gerenciado, pronto para uso imediato. Ao habilitar, o sistema fornece servidor, porta, nome de usuário e senha.

SFTP Próprio

A própria empresa gerencia seu SFTP.

Essa opção deve ser habilitada pela Gerente do Ambiente nas configurações de Ambiente. Se algum parâmetro estiver em branco ou inválido, a importação será ignorada.

Segurança

Mantenha as credenciais em segurança.
Garanta o uso correto de porta e endereço do servidor.
A proteção desses dados garante a integridade dos arquivos durante as transferências.

Diretórios

Uso	Caminho SFTP
Templates a serem importados	`/maestro/templates`
Campanhas a serem importadas	`/maestro/campaigns`

Dentro de cada diretório acima, duas pastas são criadas automaticamente:

/processed — arquivos importados com sucesso
/error — importações que falharam, com sinalização do erro encontrado

Esses diretórios são criados automaticamente após a conexão do servidor SFTP na tela de configuração, mas pode levar até 10 minutos para aparecerem.

Importar campanhas

Nome do arquivo

Não há nomenclatura obrigatória — o nome do arquivo será o nome do Público importado, então recomenda-se um nome descritivo.

Verifique se a extensão não está duplicada, como em arquivo.csv.csv.

Colunas do arquivo

TIPO_DE_REGISTRO,VALOR_DO_REGISTRO,CANAL,CODIGO_TEMPLATE,CODIGO_TEMPLATE_EXTERNO,SEGMENTO,CPF_CNPJ,COD_CONTRATO,
REMETENTE,DATA_HORA_DISPARO,NOME_CLIENTE,NOME_ARQUIVO_ANEXO,Var1,Var2,...,Var20,SMS_FLASH,BROKER

Campo	Obrigatório	Descrição
`TIPO_DE_REGISTRO`	✅	Tipo de contato (`TELEFONE` ou `EMAIL`).
`VALOR_DO_REGISTRO`	✅	Valor do contato (número com DDD ou e-mail).
`CANAL`	✅	`whatsapp`, `email`, `sms` ou `rcs`.
`CODIGO_TEMPLATE`	✅	Código do template aprovado no Maestro (ex.: `W0003`, `E0001`).
`CODIGO_TEMPLATE_EXTERNO`	✅	Código externo do template (ex.: ID no sistema do cliente).
`SEGMENTO`	✅	Nome do segmento cadastrado no Maestro.
`CPF_CNPJ`	✅	Documento do cliente.
`COD_CONTRATO`	✅	Código do contrato do cliente.
`REMETENTE`	apenas WhatsApp	Número de envio no WhatsApp ou remetente configurado.
`DATA_HORA_DISPARO`	❌	Formato `yyyy-MM-dd HH:mm:ss`.
`NOME_CLIENTE`	❌	Nome do cliente, para referência.
`NOME_ARQUIVO_ANEXO`	apenas E-mail	Arquivo inserido na mesma pasta do CSV no SFTP, adicionado como anexo.
`SMS_FLASH`	apenas SMS	Ativa SMS Flash, se a conta tiver a opção disponível.
`BROKER`	apenas SMS/RCS	Nome do provedor cadastrado, exatamente como em Configurações > Integração com provedores (ex.: `Pontal`, `Classe A`). Vazio → roteamento por segmento. Demais canais ignoram o campo.
`Var1`…`Var20`	❌	Variáveis dinâmicas que alimentam os placeholders do template.

Não é necessário manter a ordem sugerida das colunas, mas os nomes devem ser exatamente como documentado.

Exemplo:

TIPO_DE_REGISTRO,VALOR_DO_REGISTRO,CANAL,CODIGO_TEMPLATE,CODIGO_TEMPLATE_EXTERNO,SEGMENTO,CPF_CNPJ,COD_CONTRATO,REMETENTE,DATA_HORA_DISPARO,NOME_CLIENTE,NOME_ARQUIVO_ANEXO,Var1,Var2,...,SMS_FLASH,BROKER
TELEFONE,+5511988887777,whatsapp,W0003,,Varejo,12345678900,CT-98765,+5511999998888,2025-09-01 14:56:00,João Silva,,Promoção de Inverno,10%,...,NÃO,
EMAIL,cliente@dominio.com,email,E0001,BR001,Financeiro,98765432100,CT-12345,,2025-09-01 15:10:00,Maria Souza,Fatura_Maria_Souza_07_2025.pdf,Fatura 07/2025,R$350,...,NÃO,
TELEFONE,+5511977776666,sms,S0002,BR002,Atacado,11223344556,CT-45678,,2025-09-01 15:30:00,Carlos Lima,BoletoCarlosLima.pdf,Código 123456,Validade 5min,...,SIM,Pontal

Fluxo de processamento

Faça upload do arquivo .csv em /maestro/campaigns.
Um serviço rotineiro roda a cada 10 minutos: cria /processed e /error se não existirem, e busca arquivos .csv ainda não importados.
Durante a importação, são validados: o nome do arquivo, se cada linha cumpre as regras do ambiente (segmento existe e assessoria tem acesso; templates aprovados; horários de saída válidos; se a coluna BROKER for informada, se o provedor existe e é compatível com o segmento — nome inválido ou provedor sem perfil rejeita o arquivo inteiro).
Na importação: linhas que quebram regras geram {nome original}_EXCEPTIONS.csv em /processed, com a coluna adicional Motivo Falha.
Se não houver provedor para o canal configurado, é criado {nome original}_created.csv em /processed com os contatos processados (sem disparo). Se houver provedor, os disparos são criados e o arquivo gerado é {nome original}_VALIDATED.csv.
Arquivos de anexo (se houver) são destruídos após o envio.
Se houver falha no arquivo inteiro, é gerado {nome do arquivo original}_errorDetail.txt em /error.

Importar templates

Nome do arquivo

{nome do segmento}_{canal}_[{nome da WABA}]_{data}.csv

nome do segmento: nome exato do segmento configurado (Segmentos).
canal: email | sms | whatsapp | rcs (case-insensitive).
nome da WABA (opcional, apenas WhatsApp): descrição da WABA.
data: formato yyyyMMdd (ex.: 20250531).

Exemplos: retail_email_20250510.csv, finance_sms_20250101.csv, store_whatsapp_MinhaWaba_20250320.csv

Colunas do arquivo, por canal

Não é necessário manter a ordem sugerida das colunas, mas os nomes devem ser exatamente como documentado.

Templates WhatsApp:

TEMPLATE_NAME,LANGUAGE,CATEGORY,HEADER_TEXT,BODY_TEXT,FOOTER_TEXT,REPLYBUTTON_1,REPLYBUTTON_2,REPLYBUTTON_3,
URL_BUTTON,URL_BUTTON_TEXT,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE

Campo	Obrigatório	Descrição
`TEMPLATE_NAME`	✅ (criação)	Nome único do template (sem espaços; usar `_` se necessário).
`LANGUAGE`	✅ (criação)	Idioma, formato `pt_BR`, `en_US` etc.
`CATEGORY`	✅ (criação)	`MARKETING`, `UTILITY` ou `AUTHENTICATION`.
`HEADER_TEXT`	❌	Texto do cabeçalho.
`BODY_TEXT`	✅ (criação)	Texto do corpo da mensagem.
`FOOTER_TEXT`	❌	Texto do rodapé.
`REPLYBUTTON_1`/`_2`/`_3`	❌	Texto dos botões de resposta rápida.
`URL_BUTTON`	❌	URL do botão de ação (se existir).
`URL_BUTTON_TEXT`	❌	Texto do botão de URL.
`TEMPLATE_STATUS`	❌	`APROVADO` ou `REJEITADO` (status da revisão).
`REASONS`	❌	Motivos de reprovação, separados por `\|`. Cada motivo deve estar cadastrado no Maestro.
`TEMPLATE_CODE`	❌	Código do template no Maestro (identifica o template na revisão).
`EXTERNAL_CODE`	❌	Identificador externo do template. Deve ser único.

Templates de E-mail:

TEMPLATE_NAME,SUBJECT,BODY_HTML,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE

Campo	Obrigatório	Descrição
`TEMPLATE_NAME`	✅ (criação)	Nome único do template.
`SUBJECT`	✅ (criação)	Assunto do e-mail.
`BODY_HTML`	✅ (criação)	Corpo em HTML (inline).
`TEMPLATE_STATUS`	❌	`APROVADO` ou `REJEITADO`.
`REASONS`	❌	Motivos de reprovação, separados por `\|`.
`TEMPLATE_CODE`	❌	Código do template no Maestro.
`EXTERNAL_CODE`	❌	Identificador externo, único.

Templates de SMS:

TEMPLATE_NAME,TEXT_BODY,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE

Campo	Obrigatório	Descrição
`TEMPLATE_NAME`	✅ (criação)	Nome único do template.
`TEXT_BODY`	✅ (criação)	Texto do corpo, pode conter variáveis (ex.: `{{1}}`).
`TEMPLATE_STATUS`	❌	`APROVADO` ou `REJEITADO`.
`REASONS`	❌	Motivos de reprovação, separados por `\|`.
`TEMPLATE_CODE`	❌	Código do template no Maestro.
`EXTERNAL_CODE`	❌	Identificador externo, único.

Templates de RCS:

TEMPLATE_NAME;MESSAGE_TYPE;MESSAGE;TITLE;FALLBACK;SUGGESTION_1_TITLE;SUGGESTION_1_TYPE;SUGGESTION_1_VALUE;
SUGGESTION_2_TITLE;SUGGESTION_2_TYPE;SUGGESTION_2_VALUE;SUGGESTION_3_TITLE;SUGGESTION_3_TYPE;SUGGESTION_3_VALUE;
SUGGESTION_4_TITLE;SUGGESTION_4_TYPE;SUGGESTION_4_VALUE;TEMPLATE_STATUS;REASONS;TEMPLATE_CODE;EXTERNAL_CODE

Campo	Obrigatório	Descrição
`TEMPLATE_NAME`	✅ (criação)	Nome único do template.
`MESSAGE_TYPE`	✅	`Texto simples`, `Sugestão` ou `RichCard`.
`MESSAGE`	✅	Texto do corpo, pode conter variáveis (ex.: `{{1}}`).
`TITLE`	❌	Título do cartão (usado em `RichCard`).
`FALLBACK`	❌	Texto alternativo quando o dispositivo/operadora não suporta RCS.
`SUGGESTION_x_TITLE`	❌	Texto do botão de sugestão x (1 a 4).
`SUGGESTION_x_TYPE`	❌	`Resposta rápida`, `Abrir URL`, `Ligar`, `Criar evento`, `Compartilhar localização` ou `Ver localização`.
`SUGGESTION_x_VALUE`	❌	Valor correspondente ao tipo (URL, telefone etc.). Vazio quando o tipo for `Resposta rápida`.
`TEMPLATE_STATUS`	❌	`APROVADO` ou `REJEITADO`.
`REASONS`	❌	Motivos de reprovação, separados por `\|`.
`TEMPLATE_CODE`	❌	Código do template no Maestro.
`EXTERNAL_CODE`	❌	Identificador externo, único.

Regra específica do RCS: templates dos tipos Texto simples e Sugestão podem ser criados e revisados via importação. O tipo RichCard é apenas revisado — o template já deve existir no Maestro.

Fluxo de processamento

Faça upload do .csv em /maestro/templates.
Um serviço rotineiro roda a cada 10 minutos: cria /processed e /error se não existirem, e busca arquivos ainda não importados.
Validações: nome do arquivo segue o padrão, segmento existe e assessoria tem acesso, campos obrigatórios do cenário estão presentes.
O comportamento da importação varia conforme os campos informados — veja Fluxos.
O arquivo é movido para /processed (sucesso) ou /error (falha), gerando {nome do arquivo original}_errorDetail.txt em caso de erro.

Fluxos

Situação	Ação do Maestro
Template não existe + `TEMPLATE_STATUS` ausente	Cria o template
Template não existe + `TEMPLATE_STATUS` informado	Cria e revisa
Template existe + `TEMPLATE_STATUS` informado	Apenas revisa
Template existe + `TEMPLATE_STATUS` ausente	Erro

RCS: templates com MESSAGE_TYPE igual a Texto simples ou Sugestão seguem a tabela acima. O tipo RichCard é apenas revisado — não é criado pela importação.

Identificação do template existente — o Maestro busca nesta ordem: TEMPLATE_CODE (código interno) → EXTERNAL_CODE (identificador externo) → se nenhum for informado, um novo template é criado.

Regras

TEMPLATE_STATUS aceita apenas APROVADO ou REJEITADO.
REASONS é obrigatório quando TEMPLATE_STATUS=REJEITADO; motivos múltiplos separados por |, cada um previamente cadastrado no Maestro.
O template existente deve estar com status Em Revisão para ser revisado.
EXTERNAL_CODE deve ser único por empresa.
Se qualquer linha do arquivo contiver erro, nenhuma linha é processada.

FAQ

Posso enviar arquivos sem seguir o padrão de nomenclatura?

Não. O arquivo será rejeitado e movido para a pasta error, com um _errorDetail.txt.

Preciso recriar os diretórios processed e error manualmente?

Não. O sistema os cria automaticamente quando não existirem.

Posso reaproveitar um arquivo já processado?

Não. Arquivos em processed não são reprocessados. Para enviar novamente, gere um novo .csv.

Com que frequência os arquivos são processados?

A cada 10 minutos, via rotina automática.

SFTP não conecta ou arquivo não sai da pasta de origem? Veja Troubleshooting.

Introdução

Guia do Usuário

Motor de Regras

Integrações

Central de Suporte

Configuração

SFTP Robbu

SFTP Próprio

Segurança

Diretórios

Importar campanhas

Nome do arquivo

Colunas do arquivo

Fluxo de processamento

Importar templates

Nome do arquivo

Colunas do arquivo, por canal

Fluxo de processamento

Fluxos

Regras

FAQ

​Configuração

​SFTP Robbu

​SFTP Próprio

​Segurança

​Diretórios

​Importar campanhas

​Nome do arquivo

​Colunas do arquivo

​Fluxo de processamento

​Importar templates

​Nome do arquivo

​Colunas do arquivo, por canal

​Fluxo de processamento

​Fluxos

​Regras

​FAQ

Configuração

SFTP Robbu

SFTP Próprio

Segurança

Diretórios

Importar campanhas

Nome do arquivo

Colunas do arquivo

Fluxo de processamento

Importar templates

Nome do arquivo

Colunas do arquivo, por canal

Fluxo de processamento

Fluxos

Regras

FAQ