Carga SFTP de Templates e Campanhas

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

Configuração

A configuração de SFTP pode ser feita na seção Configurações > Empresa > Transferência de Arquivos A Gerente de Ambiente pode decidir se as assessorias poderão utilizar um SFTP próprio ou somente o gerenciado pela Robbu. Há duas formas de conectar um servidor SFTP ao Maestro:

SFTP Robbu

A Robbu disponibiliza um servidor SFTP gerenciado, pronto para uso imediato

Ao habilitar, o sistema fornece:
- Servidor
- Porta
- Nome de usuário
- Senha

SFTP Próprio

A própria empresa gerencia o seu SFTP.

⚠️ Atenção: Essa opção deve ser habilitada pela Gerente de Ambiente nas configurações de Ambiente

⚠️ Se algum parâmetro estiver em branco ou inválido, a importação será ignorada

Essa flexibilidade permite que cada empresa defina o modelo mais adequado ao seu nível de governança e requisitos de segurança.

Segurança

É fundamental manter as credenciais em segurança.
Garantir o correto uso de porta e endereço do servidor para estabelecer a conexão.
A proteção desses dados garante a integridade dos arquivos durante as transferências.

Diretórios

O Maestro utiliza a seguinte árvore de diretórios dentro do servidor SFTP

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

Dentro de cada um dos diretórios acima, duas pastas serão criadas: /processed para identificar os arquivos importados com sucesso /error para identificar importações que não aconteceram e sinalizar qual foi o erro encontrado

⚠️ Estes 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 que esses diretórios apareçam.

Passo a passo

Importar campanhas

Siga as instruções abaixo para importar uma campanha para o Maestro usando o SFTP

Nome do arquivo

Não há uma nomenclatura específica a se seguir na importação de campanha, mas o nome do arquivo será o nome do Público importado, por isso recomendamos que seja um nome descritivo que possa identificar facilmente o mailing importado.

⚠️ É muito importante que o arquivo tenha um nome consistente com relação à extensão .csv.__ Verifique se a extensão não está duplicada, como em arquivo.csv.csv

Colunas do arquivo

As colunas abaixo são possíveis no 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,Var3,Var4,Var5,Var6,Var7,Var8,Var9,Var10,Var11,Var12,Var13,Var14,Var15,Var16,Var17,Var18,Var19,Var20,SMS_FLASH,BROKER

Descrição dos campos:

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	✅	Canal da mensagem: `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 do template no sistema do cliente).
SEGMENTO	✅	Nome do segmento cadastrado no Maestro.
CPF_CNPJ	✅	Documento do cliente (para validações ou relatórios).
COD_CONTRATO	✅	Código do contrato do cliente.
REMETENTE	⚠️ apenas WHATSAPP	Número de envio no WhatsApp ou remetente configurado.
DATA_HORA_DISPARO	❌	Data e hora de disparo no formato `yyyy-MM-dd HH:mm:ss`.
NOME_CLIENTE	❌	Nome do cliente para referência.
NOME_ARQUIVO_ANEXO	❌ apenas EMAIL	Arquivo inserido na mesma pasta do CSV no SFTP para ser adicionado como anexo em e-mail
SMS_FLASH	❌ apenas SMS	Ative para enviar mensagens de SMS Flash se a conta selecionada tiver essa opção disponível.
BROKER	❌ apenas SMS/RCS	Nome do provedor cadastrado para forçar a saída do registro (ex.: `Pontal`, `Classe A`), exatamente como aparece em Configurações > Integração com provedores (sensível a maiúsculas/minúsculas e espaços). 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 que os campos estejam na ordem sugerida, mas os nomes das colunas devem ser exatamente como estão nesta documentação

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,Var3,Var4,Var5,Var6,Var7,Var8,Var9,Var10,Var11,Var12,Var13,Var14,Var15,Var16,Var17,Var18,Var19,Var20,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%,Cupom123,Loja Centro,Campanha Primavera,Segunda Onda,Lote A,Segmento VIP,Teste A/B,Link Personalizado,CTA1,CTA2,Obs1,Obs2,Obs3,Obs4,Obs5,Obs6,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,00,Vencimento 10/09/2025,Linha Digitável,https://pagamento.com/123,Segunda Via,Campanha Agosto,Cliente Ouro,Instruções,CTA Pagamento,CTA Suporte,Obs1,Obs2,Obs3,Obs4,Obs5,Obs6,Obs7,Obs8,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,Campanha Primavera,Lote B,Segmento Prata,Teste B,Link Resgate,CTA SMS,Obs1,Obs2,Obs3,Obs4,Obs5,Obs6,Obs7,Obs8,Obs9,Obs10,SIM,Pontal

Fluxo de processamento

Faça upload do arquivo .csv em /maestro/campaigns
Um serviço rotineiro roda a cada 10 minutos e executa:
- Cria diretórios processed e error se não existirem.
- Busca arquivos .csv ainda não importados
Durante a importação, algumas validações são executadas:
- Nome do arquivo segue o padrão?
- Cada linha do CSV cumpre as regras do ambiente?
  - Segmentos existem e assessoria possui permissão de acesso?
  - Templates estão aprovados?
  - Horários de saída são válidos?
  - Quando a coluna BROKER é informada (SMS/RCS): o nome corresponde a um provedor cadastrado e há perfil compatível com o segmento? Nome inválido ou provedor sem perfil rejeita o arquivo inteiro.
Importação:
- Cria um arquivo {nome original}_EXCEPTIONS.csv com todos os contatos que não foram processados pois quebraram regras.
  - Este arquivo contém a cópia da linha original com uma coluna adicional Motivo Falha exibindo o porquê do contato não ter sido processado
- Há provedor para o canal configurado?
  - Se não, apenas cria um arquivo {nome original}_created.csv na pasta /processed com todos os contatos que foram processados
  - Se sim, cria os disparos e depois cria um arquivo {nome original}_VALIDATED.csv na pasta /processed com todos os contatos que foram processados
- Os arquivos de anexos (se houver) são destruídos após o envio
Se houver falha no arquivo inteiro
- Gera {nome do arquivo original}_errorDetail.txt com mensagem de erro na pasta /error

Importar templates

Siga as instruções abaixo para importar templates para o Maestro usando o SFTP

Nome do arquivo

O nome do arquivo deve seguir a seguinte nomenclatura:

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

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

Exemplos

retail_email_20250510.csv
finance_sms_20250101.csv
store_whatsapp_MinhaWaba_20250320.csv

Colunas do arquivo

⚠️ Não é necessário que os campos estejam na ordem sugerida, mas os nomes das colunas devem ser exatamente como estão nesta documentação

As colunas abaixo são possíveis no arquivo: 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 no formato `pt_BR`, `en_US`, etc.
CATEGORY	✅ (criação)	Categoria: `MARKETING`, `UTILITY`, `AUTHENTICATION`.
HEADER_TEXT	❌	Texto do cabeçalho (opcional).
BODY_TEXT	✅ (criação)	Texto do corpo da mensagem.
FOOTER_TEXT	❌	Texto do rodapé (opcional).
REPLYBUTTON_1	❌	Texto do botão de resposta rápida 1.
REPLYBUTTON_2	❌	Texto do botão de resposta rápida 2.
REPLYBUTTON_3	❌	Texto do botão de resposta rápida 3.
URL_BUTTON	❌	URL do botão de ação (se existir).
URL_BUTTON_TEXT	❌	Texto exibido no botão de URL.
TEMPLATE_STATUS	❌	Status da revisão: `APROVADO` ou `REJEITADO`.
REASONS	❌	Motivos de reprovação separados por `\|`. Cada motivo deve estar cadastrado no Maestro.
TEMPLATE_CODE	❌	Código do template no Maestro. Usado para identificar o template na revisão.
EXTERNAL_CODE	❌	Identificador externo do template (ex.: ID no sistema do cliente). Deve ser único.

Exemplo:

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
exemplo_template,pt_BR,MARKETING,Cabeçalho Exemplo,Texto do Corpo,Rodapé Exemplo,Sim,Não,Não receber,,,APROVADO,Motivo1|Motivo 2,W0003,EXT001
fatura_atrasada,en_US,UTILITY,Invoice Reminder,"Hello {{Var1}}, your invoice {{Var2}} is overdue.","Contact support if already paid",Pay Now,Ignore,Talk to Agent,https://pay.example.com,Pay Securely,,,,
codigo_otp,pt_BR,AUTHENTICATION,,Seu código de acesso é {{Var1}},Este código expira em 5 minutos,,,,,,REJEITADO,Motivo2 |Motivo3,W0012,EXT001

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 (sem espaços, usar `_` se preciso).
SUBJECT	✅ (criação)	Assunto do e-mail.
BODY_HTML	✅ (criação)	Conteúdo do corpo em HTML (inline).
TEMPLATE_STATUS	❌	Status da revisão: `APROVADO` ou `REJEITADO`.
REASONS	❌	Motivos de reprovação separados por `\|`. Cada motivo deve estar cadastrado no Maestro.
TEMPLATE_CODE	❌	Código do template no Maestro. Usado para identificar o template na revisão.
EXTERNAL_CODE	❌	Identificador externo do template (ex.: ID no sistema do cliente). Deve ser único.

Exemplo:

TEMPLATE_NAME,SUBJECT,BODY_HTML,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE
ExemploTemplate,ExemploAssunto,<html><body><h1>Teste</h1><p>Corpo do e-mail</p></body></html>,,,,
BoasVindas,Seja bem-vindo!,<html><body><h1>Olá {{1}}</h1><p>Obrigado por se cadastrar em nossa plataforma.</p></body></html>,,,,
FaturaAtrasada,Lembrete de pagamento,<html><body><p>Olá {{1}},</p><p>Sua fatura {{2}} está em aberto.</p><p><a href="https://pagamento.exemplo.com/{{2}}">Clique aqui para pagar</a></p></body></html>,REJEITADO,Motivo1|Motivo2,E0002,EXT050

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 (sem espaços, usar `_` se preciso).
TEXT_BODY	✅ (criação)	Texto do corpo do SMS, pode conter variáveis dinâmicas (ex.: `{{1}}`).
TEMPLATE_STATUS	❌	Status da revisão: `APROVADO` ou `REJEITADO`.
REASONS	❌	Motivos de reprovação separados por `\|`. Cada motivo deve estar cadastrado no Maestro.
TEMPLATE_CODE	❌	Código do template no Maestro. Usado para identificar o template na revisão.
EXTERNAL_CODE	❌	Identificador externo do template (ex.: ID no sistema do cliente). Deve ser único.

Exemplo:

TEMPLATE_NAME,TEXT_BODY,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE
ExemploTemplate,ExemploTexto,,,,
BoasVindasSMS,Olá {{1}} bem-vindo(a) à nossa plataforma!,APROVADO,Motivo1|Motivo5,S0002,EXT041
CodigoOTP,Seu código de acesso é {{1}}. Ele expira em 5 minutos.,REJEITADO,Motivo4|Motivo7,S0048,EXT032

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 (sem espaços, usar `_` se preciso).
MESSAGE_TYPE	✅	Tipo da mensagem RCS: `Texto simples`, `Sugestão` ou `RichCard`.
MESSAGE	✅	Texto do corpo da mensagem. Pode conter variáveis dinâmicas (ex.: `{{1}}`).
TITLE	❌	Título do cartão. Usado principalmente em `RichCard`.
FALLBACK	❌	Texto alternativo exibido quando o dispositivo/operadora do destinatário não suporta o recurso RCS.
SUGGESTION_x_TITLE	❌	Texto exibido no botão de sugestão `x` (1 a 4).
SUGGESTION_x_TYPE	❌	Tipo da ação da sugestão `x`: `Resposta rápida`, `Abrir URL`, `Ligar`, `Criar evento`, `Compartilhar localização` ou `Ver localização`.
SUGGESTION_x_VALUE	❌	Valor da ação correspondente ao tipo (ex.: URL para `Abrir URL`, telefone para `Ligar`). Fica vazio quando o tipo for `Resposta rápida`.
TEMPLATE_STATUS	❌	Status da revisão: `APROVADO` ou `REJEITADO`.
REASONS	❌	Motivos de reprovação separados por `\|`. Cada motivo deve estar cadastrado no Maestro.
TEMPLATE_CODE	❌	Código do template no Maestro. Usado para identificar o template na revisão.
EXTERNAL_CODE	❌	Identificador externo do template (ex.: ID no sistema do cliente). Deve ser único.

⚠️ Regra específica do RCS: via importação, os templates dos tipos Texto simples e Sugestão podem ser criados e revisados. O template do tipo RichCard é apenas revisado; isso significa que o template RichCard importado já deve existir no Maestro.

Exemplo:

﻿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
Boas-vindas;Texto simples;Olá! Seja bem-vindo {1}. Estamos felizes em ter você com a gente.;;;;;;;;;;;;;;;;;;BR002
Lembrete de pagamento;Texto simples;Olá, {1}! Sua fatura vence amanhã. Evite juros pagando em dia.;;;;;;;;;;;;;;;;;;BR213
Confirmação de pedido;Sugestão;Seu pedido {1} foi confirmado! O que deseja fazer agora?;;Seu pedido foi confirmado.;Acompanhar pedido;Abrir URL;https://exemplo.com/pedido/123;Falar com atendente;Resposta rápida;;Ligar para a loja;Ligar;5511999999999;;;;;;;BR001
Pesquisa de satisfação;Sugestão;Como você avalia o nosso atendimento?;;Responda de 1 a 3.;Ótimo;Resposta rápida;;Regular;Resposta rápida;;Ruim;Resposta rápida;;;;;;;;BR654

Fluxo de processamento

Faça upload do .csv em /maestro/templates
Um serviço rotineiro roda a cada 10 minutos e executa:
- Cria diretórios processed e error se não existirem.
- Busca arquivos .csv ainda não importados
Durante a importação, algumas validações são executadas:
- Nome do arquivo segue o padrão?
- Segmento existe e assessoria possui permissão de acesso?
- Campos obrigatórios para o cenário identificado estão presentes?
Importação — o comportamento varia conforme os campos informados (veja Fluxos abaixo).
Move o .csv para:
- /processed em caso de sucesso.
- /error em caso de falha.
  - Gera {nome do arquivo original}_errorDetail.txt com mensagem de erro.

Fluxos

O comportamento do Maestro para cada linha do arquivo é determinado pela combinação de campos presentes:

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 (criação e revisão). Já o tipo RichCard é apenas revisado — não é criado pela importação.

Identificação do template existente — o Maestro busca pelo template na seguinte ordem:

TEMPLATE_CODE (código interno do Maestro)
EXTERNAL_CODE (identificador externo)
Se nenhum dos dois for informado → novo template será criado

Regras

TEMPLATE_STATUS: aceita apenas APROVADO ou REJEITADO.
REASONS: obrigatório quando TEMPLATE_STATUS=REJEITADO. Informe ao menos um motivo; motivos múltiplos devem ser separados por |.
Cada motivo informado em REASONS deve estar 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.

​Carga SFTP de Templates e Campanhas

​Configuração

​SFTP Robbu

​SFTP Próprio

​Segurança

​Diretórios

​Passo a passo

​Importar campanhas

​Nome do arquivo

​Colunas do arquivo

​Fluxo de processamento

​Importar templates

​Nome do arquivo

​Colunas do arquivo

​Fluxo de processamento

​Fluxos

​Regras

​FAQ

Carga SFTP de Templates e Campanhas

Configuração

SFTP Robbu

SFTP Próprio

Segurança

Diretórios

Passo a passo

Importar campanhas

Nome do arquivo

Colunas do arquivo

Fluxo de processamento

Importar templates

Nome do arquivo

Colunas do arquivo

Fluxo de processamento

Fluxos

Regras

FAQ