> ## Documentation Index
> Fetch the complete documentation index at: https://docs.robbu.global/llms.txt
> Use this file to discover all available pages before exploring further.
# Uso de SFTP
> Orientações para importação automática de Templates e Campanhas via SFTP no Robbu Maestro, incluindo padrões de arquivos, diretórios e fluxo de processamento.
# 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
```plaintext theme={null}
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:**
```csv theme={null}
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
1. Faça upload do arquivo `.csv` em `/maestro/campaigns`
2. 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
3. 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**.
4. 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
5. 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:
```plaintext theme={null}
{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:**
```plaintext theme={null}
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:
```csv theme={null}
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:**
```plaintext theme={null}
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:
```csv theme={null}
TEMPLATE_NAME,SUBJECT,BODY_HTML,TEMPLATE_STATUS,REASONS,TEMPLATE_CODE,EXTERNAL_CODE
ExemploTemplate,ExemploAssunto,Teste
Corpo do e-mail
,,,,
BoasVindas,Seja bem-vindo!,Olá {{1}}
Obrigado por se cadastrar em nossa plataforma.
,,,,
FaturaAtrasada,Lembrete de pagamento,Olá {{1}},
Sua fatura {{2}} está em aberto.
Clique aqui para pagar
,REJEITADO,Motivo1|Motivo2,E0002,EXT050
```
**Templates de SMS:**
```plaintext theme={null}
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:
```csv theme={null}
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:**
```plaintext theme={null}
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:
```csv theme={null}
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
1. Faça upload do `.csv` em `/maestro/templates`
2. 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
3. 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?
4. Importação — o comportamento varia conforme os campos informados (veja [Fluxos](#fluxos) abaixo).
5. 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:
1. `TEMPLATE_CODE` (código interno do Maestro)
2. `EXTERNAL_CODE` (identificador externo)
3. 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
Não. O arquivo será rejeitado e movido para a pasta **error** com um `_errorDetail.txt`.
Não. O sistema os cria automaticamente quando não existirem.
Não. Arquivos em `processed` não são reprocessados. Para enviar novamente, gere um novo `.csv`.
A cada **10 minutos**, via rotina automática.